VocalDocscontracts 1.65.0

Create or update Contacts in a batch

POST /v1/contacts/upsert

PropertyValue
Operationupsert_contacts
GroupContacts
Scopecontacts:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited contacts.contact.upsert (mutation)
Released in1.61.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Upserts at most 1,000 Contacts (a target) by the order of section 2.5, rule 2, in one transaction per item (1.61.0), and answers one outcome per item; a conflicting or invalid item writes nothing and blocks no other. Each created Contact writes contact.created.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the contacts:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/contacts/upsert" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {}
    ]
  }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: ContactUpsertRequest.

FieldTypeRequiredDescription
contactsarray of ContactCreateRequestyesAt most 1000 items (a target), each a Contact as a create names it.

Responses

StatusContent typeShapeError codes
200application/jsonContactUpsertResult
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is ContactUpsertResult.

FieldTypeRequiredDescription
object"contact_upsert"yes
resultsarray of ContactUpsertItemResultyes