# Create a Contact

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.

Endpoint: POST /v1/projects/{project_id}/contacts
Version: 1.0
Security: Basic, oAuth2

## Security:

  - `Basic` (unknown)
    http basic

  - `oAuth2` (unknown)
    oauth2

## Path parameters:

  - `project_id` (string, required)
    The unique ID of the project. You can find this on the [Sinch Dashboard](https://dashboard.sinch.com/convapi/apps).

## Request body:

  - `application/json` (unknown)
    The contact to create.

## Request fields (application/json):

  - `channel_identities` (array, required)
    List of channel identities. Array must contain at least one item.

  - `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_identities.channel` (string, required)
    The identifier of the channel you want to include. Must be one of the enum values.
    Enum: "SMS", "RCS", "WHATSAPP", "MMS", "KAKAOTALK", "KAKAOTALKCHAT", "VIBERBM", "LINE", "INSTAGRAM", "MESSENGER", "WECHAT", "TELEGRAM", "APPLEBC"

  - `channel_identities.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` (array)
    List of channels defining the channel priority for the contact. The channel at the top of the list will be tried first. Note that this priority order can be overridden by the `channel_priority_order` set in a send message request, the order of `channel_identities` set in a send message request, or the channel that is already in use if a conversation already exists for this contact.

  - `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` (string, required)
    Enum: "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.

## Request examples:

  - `Create new contact with only one channel` (unknown)

  - `Create new contact with multiple channels` (unknown)

## Response 200:

  - `200` (unknown)
    A successful response.

## Response 200 fields (application/json):

  - `channel_identities` (array)
    List of channel identities.

  - `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_identities.channel` (string, required)
    The identifier of the channel you want to include. Must be one of the enum values.
    Enum: "SMS", "RCS", "WHATSAPP", "MMS", "KAKAOTALK", "KAKAOTALKCHAT", "VIBERBM", "LINE", "INSTAGRAM", "MESSENGER", "WECHAT", "TELEGRAM", "APPLEBC"

  - `channel_identities.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` (array)
    List of channels defining the channel priority. Note that this priority order can be overridden by the `channel_priority_order` set in a send message request, the order of `channel_identities` set in a send message request, or the channel that is already in use if a conversation already exists for this contact.

  - `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.
    Example: {CONTACT_ID}

  - `language` (string)
    Enum: "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.

## Response 400:

  - `400` (unknown)
    Malformed request. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 401:

  - `401` (unknown)
    Incorrect credentials. See [common error responses](https://developers.sinch.com/docs/conversation/api-reference/#common-error-responses) for more information.

## Response 403:

  - `403` (unknown)
    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.

## Response 403 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 500:

  - `500` (unknown)
    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.

## Response 500 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

## Response 501:

  - `501` (unknown)
    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.

## Response 501 fields (application/json):

  - `error` (object)

  - `error.code` (integer)

  - `error.details` (array)

  - `error.details.type_url` (string)

  - `error.details.value` (string)

  - `error.message` (string)

  - `error.status` (string)

