> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a contact

> Creates a contact and returns it with `201`. Invalid numbers and emails are rejected, not dropped. Text fields are cleaned up before their length is checked and they are stored, as in the CloudTalk Dashboard and the existing API: emojis and other characters that take 4 bytes in UTF-8, and control characters such as line breaks and tabs, become a space; repeated whitespace becomes one space; and spaces at the start and end are removed. This applies to `name`, `title`, `company`, `industry`, `website`, `address`, `city`, `state`, `zip` and custom field values, not to emails or phone numbers. The contact's `source` is `api`.

**Matching.** By default no duplicate check runs (`matchBy: none`). With `matchBy` set to `phone`, `email` or `emailOrPhone`, a contact that matches is updated instead and the response is `200`. Fields you send overwrite the match, custom fields you do not send are kept, and when several contacts match, the most recently created one is updated and the others stay as they are. With `emailOrPhone` the phone can match one contact and the email another: the most recently created of them gets every value you sent, phones and emails included. The response does not say that more than one contact matched.

**Tags.** `tagIds` takes existing contact tag ids only, so a create never makes a tag by accident. To use a new tag, create it first with [Create a contact tag](/api-reference/contacts/create-a-contact-tag). Read-only tags are refused (see [List contact tags](/api-reference/contacts/list-contact-tags)).

**Retries.** Send an `Idempotency-Key` to retry safely. The same key with the same body returns the original status with the contact as it is now. If that contact has been deleted since, the request creates a new one. While the first request with a key is still running, a retry gets `409 IDEMPOTENCY.REQUEST_IN_PROGRESS`: retry it shortly. The same key with a different body is rejected with `422 IDEMPOTENCY.KEY_REUSED`. Keys are kept for 24 hours. If the key store cannot be reached, a create that carries a key fails with `502 CONTACTS.UPSTREAM_UNAVAILABLE` instead of risking a duplicate. A create without a key never touches the key store.

A [`contact.created`](/guides/webhooks/events/contacts#contact-created) webhook is sent, or [`contact.updated`](/guides/webhooks/events/contacts#contact-updated) when a match changed. CloudTalk also exports the contact to your active CRM integrations.



## API Specification

The full API specification for this endpoint is available in the [documentation index](https://help.cloudtalk.io/llms.txt).


## Related topics

- [Create a contact tag](https://help.cloudtalk.io/api-reference/contacts/create-a-contact-tag.md)
- [Add contact](https://help.cloudtalk.io/api-reference/contacts-legacy/add-contact.md)
- [Add a contact tag](https://help.cloudtalk.io/api-reference/contact-tags-legacy/add-a-contact-tag.md)


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