GoliathDevelopersGet an API key
Guides / AI Employees API

AI Employees API

Hire, configure, switch on and off, and assign AI employees to contacts, and answer their suggestion cards, through the Goliath developer API

About

AI employees work your contacts on their own: they answer texts, emails and calls, follow up, take notes and book their own next touch. These operations cover the whole lifecycle — hire and configure an employee, give it mailboxes and trigger forms, switch it on or off, put it on contacts (one at a time or in bulk, optionally on a schedule), read what it is doing, review its suggested edits to its own instructions, and roll back to an earlier version.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading employees (READ scope)

operationId What it does
listEmployees The organization’s AI employees: id, name, job title, status (ACTIVE working, INACTIVE hired but switched off), the template it started from, whether it can answer calls, how many contacts it is on, and when it starts texts (textHours). contactAgentCounts gives the total, active and inactive counts — quote those rather than counting rows.
getEmployee One employee in full: abilities (what it can do right now, defaults resolved — read this rather than inferring from the config), config.wakes (what wakes it), its channels (mailboxes, triggerForms, and any legacyPhoneLines), defaultAssignees, and configDocument — the whole configuration as one JSON document to edit and send back. Webhook URLs read back redacted and are kept on save.
getEmployeeCaseload The contacts one employee is on, newest attachment first, offset-paged (offset, limit default 25, at most 100) with total. Each row says whether it is working that contact now, when it last did, its next scheduled run, and whether the contact replied or escalated. includeRemoved: true adds contacts it was taken off.
getContactEmployees The employees on one contact, as the contact page shows them: attachment ids, schedules, isWorkingNow, and upcomingAgentRuns — at most 25 upcoming runs, soonest first, each a CRON row (a schedule’s next run) or a FOLLOW_UP row (a follow-up the employee booked itself). includeRemoved adds employees taken off.
listEmployeeChannelOptions What an employee can be bound to right now: availableMailboxes (connected Gmail or Outlook inboxes shared with the organization that no employee owns yet) and availableTriggerForms (the organization’s forms, any status).
listEmployeeRevisions An employee’s saved versions, newest first, offset-paged (limit default 10, at most 100): when, who saved it, and the name and job title it held.
listEmployeeSuggestions An employee’s pending suggestion cards, newest first: edits it proposes to its own instructions (action) with its confidence.
listContactReplyDrafts Retired: always returns an empty list. A reply waiting on a person is now a reply card on the contact.

Hiring and configuring (WRITE scope)

operationId What it does
createEmployee Hire an employee under a name (optional title, avatar). It is always created switched off, whatever the config says. Omit config for the general-purpose employee (texts, emails and calls once a channel is attached, notes, tasks, notifying a teammate, booking its own follow-up), or pass a complete config document in the shape of getEmployee.configDocument. Returns the new employee and its configDocument.
updateEmployeeConfig Change an employee’s configuration. Send only the change: edits are exact { find, replace } pairs against the text of configDocument (applied in order, all or nothing), and configPatch is a JSON merge patch for settings. Send config only to replace the whole document; a full replacement that drops text or a channel nobody edited is refused. expectedUpdatedAt refuses a save over a newer one.
updateEmployeeIdentity Change only the name, job title or avatar. A rename is carried into its instructions. Pass expectedUpdatedAt.
restoreEmployeeRevision Put an employee back to a saved version (revisionId from listEmployeeRevisions): instructions, settings, name and job title, saved as a new version. The same checks as updateEmployeeConfig apply.
setEmployeeStatus Switch an employee on (ACTIVE) or off (INACTIVE) — the switch on its page. On, it starts working its contacts with real people right away; off stops it mid-conversation on every contact.
setEmployeeDefaultAssignees Who becomes the owner of a contact the employee works when nobody owns it. mode decides what assigneeUserIds holds: TEAM_RANDOM (default), NONE and SAME_AS_NEW_LEADS take []; SPECIFIC_USER exactly one teammate; ROUND_ROBIN_LIST two or more, in rotation order.
attachEmployeeMailbox Give an employee a mailbox to email from and be woken by (mailboxId from listEmployeeChannelOptions): a connected inbox, shared with the organization, that no other employee owns.
detachEmployeeMailbox Take a mailbox off an employee. Safe to repeat.
detachEmployeePhoneLine Release a phone line an employee still holds from before lines were shared (legacyPhoneLines on getEmployee). Lines are no longer assigned to employees — an employee replies on the number the conversation is on, otherwise a shared organization number — so a released line cannot be attached back.
setEmployeeTriggerForms The forms whose submissions wake the employee. formIds replaces the set; [] means no form wakes it.
createEmployeeAnswerWorkflow Create the DRAFT workflow that hands an employee its contacts’ inbound texts or emails. Nothing runs until you publish it with promoteWorkflowDraft; if one already exists, it is returned instead.
deleteEmployee Fire an employee: taken off every contact (schedules deleted), mailboxes and lines released, forms stop waking it. Its history stays. Admins only, and refused while a workflow step, saved filter, automation trigger or assignment policy still names it — the refusal lists what to change first.

Putting employees on contacts (WRITE scope)

operationId What it does
assignEmployeeToContact Put one switched-on employee on one contact, optionally with a schedule. From then on it answers that contact’s texts, emails and calls.
attachEmployeeToContacts Put one switched-on employee on up to 200 contacts the key owner can open, recorded as the key owner’s own assignment. changedCount is how many were newly added. When interruptedContactId is set, the batch stopped there (interruptedReason says why): send that contact and the rest again.
detachEmployeeFromContacts Take one employee off up to 200 contacts. Schedules are dropped, history kept. Same interrupted-batch reporting.
runEmployeesOnContacts Put several switched-on employees on any number of contacts and wake each pairing once (runNow, default true) and/or on a schedule. message (at most 2,000 characters) is an internal instruction carried into every run; the contact never sees it. Runs as a bulk task — poll getBulkTask with the returned bulkTaskId.
removeEmployeesFromContacts Take several employees off any number of contacts as a bulk task. Schedules are dropped, history kept. An empty employeeIds removes every employee, system-managed ones included.
setEmployeeSchedule Replace (or add) the schedule of one employee on one contact (attachmentId from getContactEmployees). A fresh cadence: runs already spent do not count against it.
clearEmployeeSchedule Drop one attachment’s schedule. The employee stays on the contact and still answers when the contact writes in. Safe to repeat.
cancelEmployeeFollowUp Cancel a follow-up an employee booked on a contact before it runs (followUpId: a FOLLOW_UP row’s id from getContactEmployees). Returns CANCELLED, or NOT_FOUND when it already ran.
stopEmployeeRuns Stop what one employee is doing on one contact right now, at its next step. It stays on the contact and wakes again the next time something wakes it. Returns STOP_REQUESTED, or NOTHING_RUNNING.

A schedule is a 5-field cronExpression read in an IANA timezone, at most once a day, plus maxRuns — how many runs before it stops. Schedules are never open-ended. Each scheduled run can text, email or call the contact.

attachEmployeeToContacts and runEmployeesOnContacts put an employee back on a contact a teammate had taken it off, because you named that contact. Leave those contacts out first if that is not what you want.

Suggestion cards (WRITE scope)

An employee proposes edits to its own instructions as suggestion cards. Over the API you can answer them on the key owner’s behalf; answers are recorded as coming from the API, not as feedback heard from a person.

operationId What it does
acceptEmployeeSuggestion Accept a card: its edit lands on the employee’s instructions. outcome is APPLIED, RETIRED (the instructions moved on; the card is gone) or REFUSED (message says what to fix).
dismissEmployeeSuggestion Dismiss a card with a reason: NOT_RELEVANT, WRONG_TONE, WRONG_FACTS, ALREADY_DONE or OTHER.
commentOnEmployeeSuggestion Comment on a card (“keep the opener shorter”). It changes nothing on the card; the employee reads it when writing its next cards. submissionKey (1–100 characters, e.g. a UUID) is required: send a new one per comment and the same one on a retry, so a retried call is heard once.
discardEmployeeReplyDraft Retired: always refused, since employees no longer hold reply drafts.

Example

List your employees, then put one on two contacts:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listEmployees", "variables": {} }'
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9d3e1a52-7c4b-4f0e-a1b2-c3d4e5f60718" \
  -d '{ "operationId": "attachEmployeeToContacts", "variables": { "employeeId": "EMPLOYEE_ID", "contactIds": ["CONTACT_ID_1", "CONTACT_ID_2"] } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.