Contact

A contact is a collection that groups together underlying connected channel recipient identities. It's tied to a specific project and is therefore considered public to all apps sharing the same project. Most contact creation and maintenance is handled by the Conversation API's automatic contact management processes. However, you can also use API calls to manually manage your contacts.

A contact has the following configurable properties:

Field Description
Channel identities List of channel identities specifying how the contact is identified on underlying channels
Channel priority Specifies the channel priority order used when sending messages to this contact. This can be overridden by message specific channel priority order.
Display name Optional display name used in chat windows and other UIs
Email Optional Email of the contact
External id Optional identifier of the contact in external systems
Metadata Optional metadata associated with the contact.

List contacts

List all contacts in the project.

SecurityBasic or oAuth2
Request
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

query Parameters
page_size
integer <int32>

Optional. The maximum number of contacts to fetch. The default is 10 and the maximum is 20.

page_token
string

Optional. Next page token previously returned if any.

external_id
string

Optional. Contact identifier in an external system. If used, channel and identity query parameters can't be used.

channel
string (Channel Identifier)

Optional. Specifies a channel, and must be set to one of the enum values. If set, the identity parameter must be set and external_id can't be used. Used in conjunction with identity to uniquely identify the specified channel identity.

Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"
Example: channel=WHATSAPP
identity
string

Optional. If set, the channel parameter must be set and external_id can't be used. Used in conjunction with channel to uniquely identify the specified channel identity. This will differ from channel to channel. For example, a phone number for SMS, WhatsApp, and Viber Business.

Responses
200

A successful response.

Response Schema: application/json
Array of objects (Contact)

List of contacts belonging to the specified project.

next_page_token
string

Token that should be included in the next list contacts request to fetch the next page.

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

get/v1/projects/{project_id}/contacts
Request samples 
Response samples 
application/json
{
  • "contacts": [
    • {
      }
    ],
  • "next_page_token": "string"
}
Create a Contact
Most Conversation API contacts are created automatically when a message is sent to a new recipient. You can also create a new contact manually using this API call.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
Request Body schema: application/json
required
The contact to create.


required
Array of objects (Channel Identity) 
List of channel identities. Array must contain at least one item.


 
language
required
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority. The channel at the top of the list is tried first.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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.


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of objects (Channel Identity) 
List of channel identities.


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


post/v1/projects/{project_id}/contacts
Request samples 
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "language": "EN_US",
  • "display_name": "New Contact",
  • "email": "new.contact@email.com"
}
Response samples 
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "string",
  • "metadata": "string"
}
Get a Contact
Returns a specific contact as specified by the contact ID.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
contact_id
required
string
The unique ID of the contact.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of objects (Channel Identity) 
List of channel identities.


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


get/v1/projects/{project_id}/contacts/{contact_id}
Request samples 
Response samples 
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "string",
  • "metadata": "string"
}
Delete a Contact
Delete a contact as specified by the contact ID.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
contact_id
required
string
The unique ID of the contact.


 
Responses 
200
A successful response.


Response Schema: application/json
any
 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


delete/v1/projects/{project_id}/contacts/{contact_id}
Request samples 
Response samples 
application/json
null
Update a Contact
Updates a contact as specified by the contact ID.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
contact_id
required
string
The unique ID of the contact.


 
query Parameters
update_mask.paths
Array of strings
The set of field mask paths.


 
Request Body schema: application/json
required
The updated contact.


Array of objects (Channel Identity) 
List of channel identities.


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
Responses 
200
A successful response.


Response Schema: application/json
Array of objects (Channel Identity) 
List of channel identities.


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


patch/v1/projects/{project_id}/contacts/{contact_id}
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "string",
  • "metadata": "string"
}
Merge two contacts
The remaining contact will contain all conversations that the removed
contact did. If both contacts had conversations within the same App,
messages from the removed contact will be merged into corresponding active
conversations in the destination contact. Channel
identities will be moved from the source contact to the destination contact
only for channels that weren't present there before. Moved channel
identities will be placed at the bottom of the channel priority list.
Optional fields from the source contact will be copied only if
corresponding fields in the destination contact are empty The contact being
removed cannot be referenced after this call.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
destination_id
required
string
The unique ID of the contact that should be kept when merging two contacts.


 
Request Body schema: application/json
required
The contact to be removed.


source_id
required
string
Required. The ID of the contact that should be removed.


 
strategy
string (ConversationMergeStrategy) 
 Value: "MERGE"  
Responses 
200
A successful response.


Response Schema: application/json
Array of objects (Channel Identity) 
List of channel identities.


 
channel_priority
Array of strings (Channel Identifier) 
List of channels defining the channel priority.


Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "KAKAOTALKCHAT" "LINE" "WECHAT"  
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
string (ContactLanguage) 
 Enum: Description
AF
Afrikaans


SQ
Albanian


AR
Arabic


AZ
Azerbaijani


BN
Bengali


BG
Bulgarian


CA
Catalan


ZH
Chinese


ZH_CN
Chinese (CHN)


ZH_HK
Chinese (HKG)


ZH_TW
Chinese (TAI)


HR
Croatian


CS
Czech


DA
Danish


NL
Dutch


EN
English


EN_GB
English (UK)


EN_US
English (US)


ET
Estonian


FIL
Filipino


FI
Finnish


FR
French


DE
German


EL
Greek


GU
Gujarati


HA
Hausa


HE
Hebrew


HI
Hindi


HU
Hungarian


ID
Indonesian


GA
Irish


IT
Italian


JA
Japanese


KN
Kannada


KK
Kazakh


KO
Korean


LO
Lao


LV
Latvian


LT
Lithuanian


MK
Macedonian


MS
Malay


ML
Malayalam


MR
Marathi


NB
Norwegian


FA
Persian


PL
Polish


PT
Portuguese


PT_BR
Portuguese (BR)


PT_PT
Portuguese (PT)


PA
Punjabi


RO
Romanian


RU
Russian


SR
Serbian


SK
Slovak


SL
Slovenian


ES
Spanish


ES_AR
Spanish (ARG)


ES_ES
Spanish (SPA)


ES_MX
Spanish (MEX)


SW
Swahili


SV
Swedish


TA
Tamil


TE
Telugu


TH
Thai


TR
Turkish


UK
Ukrainian


UR
Urdu


UZ
Uzbek


VI
Vietnamese


ZU
Zulu


 
metadata
string
Metadata associated with the contact. Up to 1024 characters long.


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


post/v1/projects/{project_id}/contacts/{destination_id}:merge
Request samples 
application/json
{
  • "source_id": "string"
}
Response samples 
application/json
{
  • "channel_identities": [
    • {
      }
    ],
  • "channel_priority": [
    • "WHATSAPP"
    ],
  • "display_name": "string",
  • "email": "string",
  • "external_id": "string",
  • "id": "{CONTACT_ID}",
  • "language": "string",
  • "metadata": "string"
}
Get Channel Profile
Get user profile from a specific channel.
Supported only on MESSENGER, INSTAGRAM, VIBER and LINE channels.


SecurityBasic or oAuth2 
Request 
path Parameters
project_id
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
Request Body schema: application/json
required
app_id
required
string
The ID of the app.


 
required
contact_id (object) or identified_by (object)
The recipient to check profile information. Requires either contact_id or identified_by.


 
channel
required
string (GetChannelProfileConversationChannel) 
The channel. Must be one of the supported channels for this operation.


 Enum: "MESSENGER" "INSTAGRAM" "VIBER" "LINE"  
Responses 
200
A successful response.


Response Schema: application/json
profile_name
string
The profile name.


 
400
Malformed request


401
Incorrect credentials


403
Correct credentials but you don't have access to the requested resource


500
Correct credentials but you don't have access to the requested resource


501
Something went wrong on our end, try again with exponential back-off


post/v1/projects/{project_id}/contacts:getChannelProfile
Request samples 
application/json
{
  • "app_id": "{APP_ID}",
  • "recipient": {
    • "contact_id": "{CONTACT_ID}"
    },
  • "channel": "MESSENGER"
}
Response samples 
application/json
{
  • "profile_name": "John Doe"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2023 Sinch. All rights reserved.