Create a contact

Create a contact before importing historical conversations, or prepare a contact from a trusted backend:

POST /api/v1/cxm/tenants/{tenantId}/contacts

Use a tenant API key with cxm:contacts.write or a broader scope. See the API overview for authentication and common limits. This endpoint creates a new contact; it does not update or merge an existing one.

Send a request

At least one primary email or phone is required. Secondary addresses alone do not satisfy this requirement.

curl --request POST \
  --url "https://platform.crescendo.ai/api/v1/cxm/tenants/tenant_demo/contacts" \
  --header "Authorization: Bearer $CXP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "contact": {
      "contactId": "external-contact-123",
      "email": "jane@example.com",
      "phone": "+15125550100",
      "firstName": "Jane",
      "lastName": "Doe",
      "tags": ["historical-import"],
      "secondaryEmails": ["jane.alt@example.com"]
    }
  }'

A successful request returns 201 Created:

{
  "contact": {
    "contactId": "external-contact-123",
    "result": "created"
  }
}

Choose fields

Field	Behavior
`contactId`	Optional preserved ID, up to 255 characters. Omit it to generate `ct_<uuid>`. The literal `anonymous` is reserved.
`email`	Primary email, up to 320 characters; trimmed, validated and lowercased.
`phone`	Primary phone, up to 64 characters before normalization; stored in E.164 format. Unsupported extensions are rejected.
`name`, `firstName`, `lastName`	Optional names, each up to 255 characters. Explicit `name` wins; otherwise supplying both structured names also sets the display name to their joined value.
`secondaryEmails`, `secondaryPhones`	Optional arrays, each with at most 50 values. Values follow primary-address validation and normalization. Duplicates and repetitions of the primary value are removed.
`tags`	Optional array of at most 50 nonblank strings, each up to 100 characters; deduplicated without case sensitivity.

Contacts receive current creation timestamps. Organization associations, custom fields, historical timestamps and arbitrary source data are not accepted.

Handle an existing contact

A supplied ID that already exists returns 409 ContactIdConflict with existingContactId. An ID conflict takes precedence over an address conflict. CXP checks every supplied primary and secondary email/phone against stored primary and secondary addresses. A match returns 409 ContactIdentityConflict:

{
  "code": "ContactIdentityConflict",
  "message": "A contact with a supplied email or phone already exists",
  "existingContactId": "ct_existing"
}

The response identifies one blocking contact. Other supplied addresses may match other contacts, so review the source records before mapping or merging them. The endpoint does not make that decision for you. IDs and primary emails have database uniqueness protection. Phone and secondary address conflict checks do not guarantee uniqueness against simultaneous writers. Deduplicate your source data and serialize work targeting the same identities. Preserve source IDs or save returned IDs in your import mapping. A duplicate-ID error does not establish that an earlier request contained the same data. If a timeout leaves the outcome unclear, verify the result before retrying. See common errors and response conventions.

API guides

API reference

Create a contact

Create a contact

Send a request

Choose fields

Handle an existing contact

​Create a contact

​Send a request

​Choose fields

​Handle an existing contact

Create a contact

Send a request

Choose fields

Handle an existing contact