API: Contact Import

To import or update a single contact via the Cloud Chat API, send a POST request to the endpoint below with your access key and the required fields.

Want to import multiple contacts at once? Use the Bulk Contact Import via API endpoint. The two endpoints have different body formats — do not mix them.

Endpoint

POST https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import

Headers

Request Body

The body is a simple JSON object (flat), without arrays. At least one of the fields phone_number, identifier, or email must be present.

{
  "phone_number": "+5599123456789",
  "identifier": "CUSTOM_ID",
  "email": "[email protected]",
  "name": "Contact Name",
  "company_name": "Company X",
  "tags": "tag1, tag2, tag3",
  "CUSTOM_ATTRIBUTE": "value"
}

Available Fields

*At least one among phone_number, email, or identifier must be provided.

Example Request (curl)

curl -X POST \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/external_import' \
  --header 'content-type: application/json' \
  --header 'api_access_token: YOUR_TOKEN' \
  --data '{
    "phone_number": "+5599123456789",
    "name": "Contact Name",
    "email": "[email protected]",
    "company_name": "Company X",
    "tags": "tag1, tag2"
  }'

Create and Update Behavior (Upsert)

This endpoint creates a new contact or updates an existing one automatically. To determine if the contact already exists, the system searches in the following priority order:

1. First by email

2. If no email provided, by identifier

3. If no identifier provided, by phone_number

Important: The search uses only the first available field in the order above. It does not try subsequent fields if the first search yields no result.

What this means in practice

If you want to update a contact that already exists by phone number (e.g., add an email), and you send:

{
  "phone_number": "+5511999998888",
  "email": "[email protected]"
}

The system will search by email first (since the email field is present). If [email protected] does not exist in any contact, it will not attempt to search by phone_number. The result will be an attempt to create a new contact, which may silently fail due to a phone conflict.

How to do it correctly

To update an existing contact by phone number, send only the phone number as the identifier in the first call, without the field you wish to add as an identifier:

Step 1 — Locate the contact (if you need the ID):

curl -X GET \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/search?q=+5511999998888' \
  --header 'api_access_token: YOUR_TOKEN'

Step 2 — Update via individual update endpoint:

curl -X PUT \
  'https://{{CLOUDCHAT_DOMAIN}}/api/v1/accounts/{{ACCOUNT_ID}}/contacts/{{CONTACT_ID}}' \
  --header 'content-type: application/json' \
  --header 'api_access_token: YOUR_TOKEN' \
  --data '{"email": "[email protected]"}'

Response

Note: The 204 status indicates that the request was received but does not return the created/updated contact. If you need to confirm the change, perform a contact query after the call.

⚠️ Phone number variant lookup is not supported on this endpoint. This endpoint performs an exact lookup by phone_number. If you need to match contacts across Brazilian phone number variants (12 vs 13 digits, with or without the leading 9), use the Bulk Contact Import via API endpoint with api_version: "v2" (or normalize_lookup: true).

Difference Between This Endpoint and Bulk Import

Do not mix formats! Sending {"upsert": true, "data": [...]} to this endpoint (external_import) will not work. That format is exclusive to the bulk create endpoint (bulk_create).

Where to Find Configuration Parameters

• CLOUDCHAT_DOMAIN: The domain visible in your browser URL when accessing Cloud Chat

• ACCOUNT_ID: In account settings

• API_TOKEN: At https://{{CLOUDCHAT_DOMAIN}}/app/accounts/{{ACCOUNT_ID}}/profile/settings