---
title: "Create a Contact"
method: POST
path: "/v1/projects/{project_id}/contacts"
tags: ["Contact"]
---

# Create a Contact

`POST /v1/projects/{project_id}/contacts`

Most Conversation API contacts are [created automatically](https://developers.sinch.com/docs/conversation/contact-management/) when a message is sent to a new recipient. You can also create a new contact manually using this API call.

## Request body

- ContactCreateRequest — A participant in a conversation typically representing a person. It is associated with a collection of channel identities.
  - `channel_identities` ChannelIdentity[], required — List of channel identities. Array must contain at least one item.
    - `app_id` string — Required if using a channel that uses app-scoped channel identities. Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped channel identities, which means contacts will have different channel identities on different Conversation API apps. These can be thought of as virtual identities that are app-specific and, therefore, the app_id must be included in the API call.
    - `channel` 'SMS' | 'RCS' | 'WHATSAPP' | 'MMS' | 'KAKAOTALK' | 'KAKAOTALKCHAT' | 'VIBERBM' | 'LINE' | 'INSTAGRAM' | 'MESSENGER' | 'WECHAT' | 'TELEGRAM' | 'APPLEBC', required — The identifier of the channel you want to include. Must be one of the enum values.
    - `identity` string, required — The channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.
  - `channel_priority` ConversationChannel[] — List of channels defining the channel priority. The channel at the top of the list is tried first.
  - `display_name` string — The display name. A default 'Unknown' will be assigned if left empty.
  - `email` string — Email of the contact.
  - `external_id` string — Contact identifier in an external system.
  - `language` 'AF' | 'SQ' | 'AR' | 'AZ' | 'BN' | 'BG' | 'CA' | 'ZH' | 'ZH_CN' | 'ZH_HK' | 'ZH_TW' | 'HR' | 'CS' | 'DA' | 'NL' | 'EN' | 'EN_GB' | 'EN_US' | 'ET' | 'FIL' | 'FI' | 'FR' | 'DE' | 'EL' | 'GU' | 'HA' | 'HE' | 'HI' | 'HU' | 'ID' | 'GA' | 'IT' | 'JA' | 'KN' | 'KK' | 'KO' | 'LO' | 'LV' | 'LT' | 'MK' | 'MS' | 'ML' | 'MR' | 'NB' | 'FA' | 'PL' | 'PT' | 'PT_BR' | 'PT_PT' | 'PA' | 'RO' | 'RU' | 'SR' | 'SK' | 'SL' | 'ES' | 'ES_AR' | 'ES_ES' | 'ES_MX' | 'SW' | 'SV' | 'TA' | 'TE' | 'TH' | 'TR' | 'UK' | 'UR' | 'UZ' | 'VI' | 'ZU', required
  - `metadata` string — Metadata associated with the contact. Up to 1024 characters long.

## Response `200`

A successful response.

- Contact — A participant in a conversation typically representing a person. It is associated with a collection of channel identities.
  - `channel_identities` ChannelIdentity[] — List of channel identities.
    - `app_id` string — Required if using a channel that uses app-scoped channel identities. Currently, FB Messenger, Instagram, LINE, and WeChat use app-scoped channel identities, which means contacts will have different channel identities on different Conversation API apps. These can be thought of as virtual identities that are app-specific and, therefore, the app_id must be included in the API call.
    - `channel` 'SMS' | 'RCS' | 'WHATSAPP' | 'MMS' | 'KAKAOTALK' | 'KAKAOTALKCHAT' | 'VIBERBM' | 'LINE' | 'INSTAGRAM' | 'MESSENGER' | 'WECHAT' | 'TELEGRAM' | 'APPLEBC', required — The identifier of the channel you want to include. Must be one of the enum values.
    - `identity` string, required — The channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.
  - `channel_priority` ConversationChannel[] — List of channels defining the channel priority.
  - `display_name` string — The display name. A default 'Unknown' will be assigned if left empty.
  - `email` string — Email of the contact.
  - `external_id` string — Contact identifier in an external system.
  - `id` string — The ID of the contact.
  - `language` 'AF' | 'SQ' | 'AR' | 'AZ' | 'BN' | 'BG' | 'CA' | 'ZH' | 'ZH_CN' | 'ZH_HK' | 'ZH_TW' | 'HR' | 'CS' | 'DA' | 'NL' | 'EN' | 'EN_GB' | 'EN_US' | 'ET' | 'FIL' | 'FI' | 'FR' | 'DE' | 'EL' | 'GU' | 'HA' | 'HE' | 'HI' | 'HU' | 'ID' | 'GA' | 'IT' | 'JA' | 'KN' | 'KK' | 'KO' | 'LO' | 'LV' | 'LT' | 'MK' | 'MS' | 'ML' | 'MR' | 'NB' | 'FA' | 'PL' | 'PT' | 'PT_BR' | 'PT_PT' | 'PA' | 'RO' | 'RU' | 'SR' | 'SK' | 'SL' | 'ES' | 'ES_AR' | 'ES_ES' | 'ES_MX' | 'SW' | 'SV' | 'TA' | 'TE' | 'TH' | 'TR' | 'UK' | 'UR' | 'UZ' | 'VI' | 'ZU'
  - `metadata` string — Metadata associated with the contact. Up to 1024 characters long.

## Other responses

- `400` — Malformed request. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.
- `401` — Incorrect credentials. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.
- `403` — Correct credentials but you don't have access to the requested resource. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.
- `500` — Correct credentials but you don't have access to the requested resource. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.
- `501` — Something went wrong on our end, try again with exponential back-off. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.

---

[API](https://skmtc.net/sinch/apis/conversation-api-sinch.md) · [All operations](https://skmtc.net/sinch/apis/conversation-api-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/conversation-api-sinch/revisions/bdb3e0c48bf7/schema)