Skip to main content
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.

​
Contact fields

Writable Contact fields are:
  • name, title, email, phone, cnam, mobile, birthday, gender, and image
  • address with street, city, state, zip, and country
  • company with name, industry, position, website, and address
  • preferredContactMethod, marketingOptIn, contactSource, leadSource, and status
  • socialMedia with linkedin, twitter, facebook, and instagram
  • tags, notes, agentContext, customFields, lastTask, lists, and appointments
cnam is Contact display data and does not change outbound caller ID. customFields accepts at most 20 top-level keys and 8,192 UTF-8 JSON bytes after the update. POST /api/v2/contact creates or updates a Contact. Supply id or target to resolve an existing person, or phone or email to create one. Provided top-level fields replace their current values. Use PATCH /api/v2/contact/{contactId} when nested values should merge or a field should be removed: objects merge recursively, arrays and scalar values replace, and explicit null removes a field.

​
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 Vida API Skill.