ContactsPOST

Add contact

Adds a contact to the channel account. Provide at least one of phone_number or username. whatsapp_options is WhatsApp-only; unsupported channels return 501 unsupported_by_provider.

https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

account_id

stringrequired

Identifier used in the contacts route.

Request body

phone_number

string

Phone number containing a country or region code, using digits only with no plus sign, spaces, or separators. Provide phone_number or username.

username

string

Channel username. Provide username or phone_number; format rules depend on the target channel.

whatsapp_options

object

Optional WhatsApp-only contact settings. Pass first_name, full_name, and sync_to_device_contacts only as fields nested inside whatsapp_options; omit this object for other channels.

first_name

string

Optional WhatsApp contact first name.

full_name

string

Optional WhatsApp contact full name.

sync_to_device_contacts

boolean

Whether to also save the contact to the system address book of the device linked to this WhatsApp account. Defaults to false.

Response body

id

string

Contact identifier.

conversation_id

string

Conversation identifier for this contact; use it to send messages or locate the chat.

display_name

string

Contact display name, or an empty string when missing.

avatar_url

string

Contact avatar URL, or an empty string when missing.

provider_user_id

string

Channel-side user identifier for the contact.

is_blocked

boolean

Whether the contact is blocked by the connected account.

extra

object

Provider-specific extra fields, such as phone.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

Request

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "8600000000000",
  "username": "alice_user",
  "whatsapp_options": {
    "first_name": "Alice",
    "full_name": "Alice Example",
    "sync_to_device_contacts": false
  }
}'

Response

{
  "data": {
    "id": "8600000000000@s.whatsapp.net",
    "conversation_id": "123456789012345@lid",
    "display_name": "Alice Example",
    "avatar_url": "",
    "provider_user_id": "8600000000000@s.whatsapp.net",
    "extra": { "phone": "8600000000000" }
  }
}