> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cxp.crescendo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a contact

> Create a CXP contact with an optional preserved ID and explicit duplicate checks.

# Create a contact

Create a contact before [importing historical conversations](https://docs.cxp.crescendo.ai/developers/import-conversation.md),
or prepare a contact from a trusted backend:

```http theme={null}
POST /api/v1/cxm/tenants/{tenantId}/contacts
```

Use a tenant API key with `cxm:contacts.write` or a broader scope. See the
[API overview](https://docs.cxp.crescendo.ai/developers/api-overview.md) 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.

```bash theme={null}
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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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](https://docs.cxp.crescendo.ai/developers/api-overview.md#responses-and-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.