Contacts and ongoing objectives

Maintain customer context and compact workflow state across communications and Tasks.

Use Contacts for work centered on people: outreach, follow-up, appointment preparation, collections, recruiting, and customer success. Keep inventory, documents, invoices, and other non-contact records in their source system.

Find before creating

Search Contacts with GET /api/v2/contact using exact identifiers or q, and follow the returned pagination. Reuse the existing Contact when one represents the same person.

Create or update with the documented Contact routes, then read the persisted Contact before continuing.

Represent one ongoing objective

Use one stable Contact List name for each ongoing objective. Before creating a new list, inspect existing names and reuse an exact match instead of creating a synonym.

Enroll a Contact and merge compact state with:

PATCH /api/v2/contact/{contactId}/list/{listName}/state

Useful state can include the current phase, a next action, a not-before time, the last outcome, and small objective-specific data. These are workflow vocabulary, not a required universal state machine.

Continue work from evidence

Before taking the next action:

  1. Read the Contact and its matching objective state.
  2. Inspect related active Tasks and recent Contact communication logs.
  3. Read current source-system data when it affects the decision.
  4. Respect the recorded not-before time unless new information requires reevaluation.
  5. Perform and verify the action.
  6. Patch the outcome and next action.

A queued Task is not proof that communication occurred. Follow the Contact log's conversation reference for full details.

Keep state compact

Do not store transcripts, complete API responses, credentials, cookies, or copied source records in Contact custom fields. Store only the facts required for the next decision and remain within the documented size limit.

Remove a Contact from the objective only when the objective is truly complete or abandoned. Waiting, paused, cooling-down, and blocked Contacts should stay enrolled and record that state.


For recommended state shapes and request templates, use the GetVoiceBot API Skill.

Open the app All docs