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

# Create contacts

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

Creates a batch of up to 1000 contacts as specified by the list of contacts.

The contacts are created asynchronously. A `CONTACT_CREATE` event will be generated for every successfully created contact.

## Request body

- CreateContactsRequest
  - `contacts` ContactCreateRequest[], required — List of contacts to be created in Conversation API.
    - `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`

OK

## Other responses

- `401` — Invalid credentials
- `403` — Permission denied. The specified project may not be allowed to use the batch endpoint.
- `500` — Internal error

---

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