> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/api-documentation/crm/contact/create-a-contact.md).

# Create a contact

Creates a contact. Phone numbers and email addresses must be unique within your business; a duplicate returns `409` with the existing contact's details.

```json
{"openapi":"3.0.3","info":{"title":"Cekat Open API","version":"1.0.0"},"tags":[{"name":"Contact","description":"Contacts are the people your business talks to. Each contact has standard fields (name, phone number, email, and so on) plus **custom properties** that you define as columns on your contact board.\n\n## Custom properties\n1. Call `GET /api/crm/contact/filter-fields` or `GET /api/crm/contact/{id}/property` to see the available properties and their column IDs and types.\n2. Read a contact's values from `crm_column` in `GET /api/crm/contact/{contact_id}`. Values are keyed by property name.\n3. Write values with `PUT /api/crm/contact/{id}/property`, or with `values` when creating a contact.\n4. Create new properties with `POST /api/crm/contact/property`.\n"}],"servers":[{"url":"https://api.cekat.ai","description":"Production"}],"security":[{"CekatApiKey":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"CekatApiKey":{"type":"apiKey","in":"header","name":"api_key","description":"Your business's Cekat API key, from **Settings → Developers & API** in the Cekat dashboard (https://chat.cekat.ai/developers?section=apikeys). Available on the Business and Enterprise plans."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same Cekat API key, sent as `Authorization: Bearer YOUR_API_KEY`. Accepted only by endpoints under `/api/...`."}},"schemas":{"Contact":{"type":"object","description":"A contact with its standard fields, relations and custom property values. Additional fields may be present.","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"phone_number":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"type":{"type":"string","description":"Channel the contact came from, for example `whatsapp`."},"platform_id":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"additional_data":{"type":"object","nullable":true,"additionalProperties":true},"stage_id":{"type":"string","format":"uuid","nullable":true},"agent_id":{"type":"string","format":"uuid","nullable":true,"description":"The contact owner's agent ID."},"company_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true},"created_by_name":{"type":"string"},"business":{"$ref":"#/components/schemas/NamedRef"},"stage":{"$ref":"#/components/schemas/NamedRef"},"agent":{"$ref":"#/components/schemas/NamedRef"},"pipeline_status":{"$ref":"#/components/schemas/NamedRef"},"company":{"type":"object","nullable":true,"additionalProperties":true},"conversations":{"type":"array","description":"The contact's conversations, one per inbox.","items":{"type":"object","additionalProperties":true}},"crm_column":{"type":"object","description":"Custom property values, keyed by property (column) name.","additionalProperties":true}}},"NamedRef":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"ApiError":{"type":"object","description":"Error body returned by the `/api/...` endpoints.","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"message":{"type":"string"}}},"correlationId":{"type":"string","description":"Request ID. Include it when contacting Cekat support."}}},"CrmConflictError":{"type":"object","description":"Returned when the email or phone number already belongs to another contact.","properties":{"statusCode":{"type":"integer"},"error":{"type":"object","properties":{"phone_error":{"type":"string"},"email_error":{"type":"string"},"contact_id":{"type":"string","format":"uuid","description":"The existing contact with this email, when the email conflicts."},"contact_name":{"type":"string"}}}}},"RateLimitError":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"ApiUnauthorized":{"description":"The API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"TooManyRequests":{"description":"Rate limit exceeded. Wait and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"paths":{"/api/crm/contact":{"post":{"tags":["Contact"],"operationId":"CreateContact","summary":"Create a contact","description":"Creates a contact. Phone numbers and email addresses must be unique within your business; a duplicate returns `409` with the existing contact's details.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["display_name","phone_number"],"properties":{"display_name":{"type":"string"},"phone_number":{"type":"string","description":"7 to 15 digits including the country code, optionally starting with `+`. Must not start with `0`."},"email":{"type":"string","format":"email"},"note":{"type":"string"},"additional_data":{"type":"object","additionalProperties":true,"description":"Free-form extra data saved on the contact."},"company_id":{"type":"string","format":"uuid"},"stage_id":{"type":"string","format":"uuid","description":"Pipeline stage ID."},"contact_owner_id":{"type":"string","format":"uuid","description":"Agent ID of the contact owner. The agent must be active."},"label_ids":{"type":"array","description":"Contact label IDs to add.","items":{"type":"string","format":"uuid"}},"values":{"type":"array","description":"Custom property values. Columns with a default value are filled in automatically when left out.","items":{"type":"object","required":["column_id"],"properties":{"column_id":{"type":"string","format":"uuid"},"value":{"description":"The value, in the format for the column's type. See **Board** for value formats."}}}}}}}}},"responses":{"200":{"description":"Contact created.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}}}},"400":{"description":"A required field is missing, the phone number is invalid, or a value is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"$ref":"#/components/responses/ApiUnauthorized"},"404":{"description":"The company, stage, owner or label was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The phone number or email already belongs to a contact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmConflictError"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```