Skip to main content

Contacts

Contacts are the people you chat with in the Team Inbox (on WhatsApp and the other channels), whether or not they are clients.

  • Create or update: POST /v1/contacts creates a contact, or updates the contact with the same phone number on the same channel in that location (created says which). channel is whatsapp (default) or sms; an SMS contact needs the location's SMS provider in two-way mode.
  • Partial updates: PUT changes only the fields you send.
  • Tags can start automations.
  • Assign chat hands the conversation to a team member and marks it open.

The {id} in a path is the record id returned by the API (for example 5tw9zcQkbu), not the client number shown in the app.

API regionapi.whautomate.com

Search contacts​

GET /v1/contacts

Lists contacts, newest first.

Headers
x-api-keystringrequired
Your Whautomate API key.
Query parameters
limitinteger
Results per page (default 10, max 100).
tagsstring
Comma separated tag names; matches records with any of them.
locationIdstring
Location (workspace) id. Get ids from GET /v1/locations.
pageinteger
Page number, from 1 (default 1).
channelstring
Channel of the contact, for example whatsapp or sms.
searchTextstring
Matches name or phone number.
Response 200
idstring
namestringrequired
Cannot be cleared.
phoneNumberstringrequired
With the country code; stored as digits only. Cannot be cleared.
channelstring
POST: whatsapp (default) or sms. sms makes an SMS inbox contact (one per phone per location, 6 to 15 digits), only at a location whose SMS provider is active in two-way mode (else 400). Fixed after create: PUT ignores it. Responses: the contact's channel (whatsapp, sms, telegram, messenger, instagram, tiktok, website).
locationobjectrequired
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsstring[]
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
lastActivitystring
createdAtstring
When the record was created (ISO 8601, UTC).
updatedAtstring
When the record was last changed (ISO 8601, UTC).
Request
curl -X GET "https://api.whautomate.com/v1/contacts?locationId=Le6dWjQF9K&channel=whatsapp&limit=2" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
[
  {
    "id": "v2yXLlZMP2",
    "name": "Olivia Tan",
    "channel": "whatsapp",
    "phoneNumber": "6593104000",
    "lastActivity": "2026-10-29T11:40:25.007Z",
    "stage": "Lead",
    "tags": [
      "booking"
    ],
    "location": {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    },
    "createdAt": "2026-10-29T11:43:44.431Z",
    "updatedAt": "2026-10-29T12:01:33.495Z"
  },
  {
    "id": "sGvPiEd3QY",
    "name": "Ethan Ng",
    "channel": "whatsapp",
    "phoneNumber": "6593104977",
    "lastActivity": "2026-10-29T11:29:25.183Z",
    "stage": "Customer",
    "tags": [
      "booking"
    ],
    "location": {
      "id": "Le6dWjQF9K",
      "title": "Serene Wellness Studio"
    },
    "createdAt": "2026-10-29T11:43:25.044Z",
    "updatedAt": "2026-10-29T11:43:28.413Z"
  }
]

Get a contact​

GET /v1/contacts/{contactId}

Gets one contact by id.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
contactIdstringrequired
Response 200
idstring
namestringrequired
Cannot be cleared.
phoneNumberstringrequired
With the country code; stored as digits only. Cannot be cleared.
channelstring
POST: whatsapp (default) or sms. sms makes an SMS inbox contact (one per phone per location, 6 to 15 digits), only at a location whose SMS provider is active in two-way mode (else 400). Fixed after create: PUT ignores it. Responses: the contact's channel (whatsapp, sms, telegram, messenger, instagram, tiktok, website).
locationobjectrequired
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsstring[]
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
lastActivitystring
createdAtstring
When the record was created (ISO 8601, UTC).
updatedAtstring
When the record was last changed (ISO 8601, UTC).
Request
curl -X GET "https://api.whautomate.com/v1/contacts/NSasDKs69e" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "id": "NSasDKs69e",
  "name": "Arjun Menon",
  "channel": "whatsapp",
  "phoneNumber": "6598812046",
  "lastActivity": "2026-10-29T12:40:11.019Z",
  "notes": "Asked about corporate packages.",
  "tags": [
    "Price enquiry"
  ],
  "location": {
    "id": "Le6dWjQF9K",
    "title": "Serene Wellness Studio"
  },
  "createdAt": "2026-10-29T12:40:11.026Z",
  "updatedAt": "2026-10-29T12:40:11.026Z"
}

Create or update a contact​

POST /v1/contacts

Creates a contact, or updates (partial) the contact with the same phone on the same channel in that location; created says which. channel whatsapp (default) or sms (SMS inbox contact, needs the location's SMS provider active in two-way mode, else 400).

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
idstring
namestringrequired
Cannot be cleared.
phoneNumberstringrequired
With the country code; stored as digits only. Cannot be cleared.
channelstring
POST: whatsapp (default) or sms. sms makes an SMS inbox contact (one per phone per location, 6 to 15 digits), only at a location whose SMS provider is active in two-way mode (else 400). Fixed after create: PUT ignores it. Responses: the contact's channel (whatsapp, sms, telegram, messenger, instagram, tiktok, website).
locationobjectrequired
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsobject
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
Response 200
idstring
namestringrequired
Cannot be cleared.
phoneNumberstringrequired
With the country code; stored as digits only. Cannot be cleared.
channelstring
POST: whatsapp (default) or sms. sms makes an SMS inbox contact (one per phone per location, 6 to 15 digits), only at a location whose SMS provider is active in two-way mode (else 400). Fixed after create: PUT ignores it. Responses: the contact's channel (whatsapp, sms, telegram, messenger, instagram, tiktok, website).
locationobjectrequired
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsstring[]
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
lastActivitystring
createdAtstring
When the record was created (ISO 8601, UTC).
updatedAtstring
When the record was last changed (ISO 8601, UTC).
Request
curl -X POST "https://api.whautomate.com/v1/contacts" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Arjun Menon",
    "phoneNumber": "6598812046",
    "location": {
      "id": "Le6dWjQF9K"
    },
    "tags": [
      "Price enquiry"
    ],
    "notes": "Asked about corporate packages."
  }'
Response 200
{
  "id": "NSasDKs69e",
  "name": "Arjun Menon",
  "channel": "whatsapp",
  "phoneNumber": "6598812046",
  "lastActivity": "2026-10-29T12:40:11.019Z",
  "notes": "Asked about corporate packages.",
  "tags": [
    "Price enquiry"
  ],
  "location": {
    "id": "Le6dWjQF9K",
    "title": "Serene Wellness Studio"
  },
  "createdAt": "2026-10-29T12:40:11.026Z",
  "updatedAt": "2026-10-29T12:40:11.026Z",
  "created": true
}

Update a contact​

PUT /v1/contacts/{contactId}

Updates a contact. Only the fields you send change. The phone number of a WhatsApp or SMS contact cannot change (it identifies the chat).

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
contactIdstringrequired
Body
idstring
namestring
Cannot be cleared.
phoneNumberstring
With the country code; stored as digits only. Cannot be cleared.
channelstring
Read only: the contact's channel. An SMS contact may not take the number of another SMS contact in its location and moves only to a location with a two-way SMS provider.
locationobject
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsobject
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
Response 200
idstring
namestringrequired
Cannot be cleared.
phoneNumberstringrequired
With the country code; stored as digits only. Cannot be cleared.
channelstring
POST: whatsapp (default) or sms. sms makes an SMS inbox contact (one per phone per location, 6 to 15 digits), only at a location whose SMS provider is active in two-way mode (else 400). Fixed after create: PUT ignores it. Responses: the contact's channel (whatsapp, sms, telegram, messenger, instagram, tiktok, website).
locationobjectrequired
stageobject
Pipeline stage name. Left out keeps it; null or an empty value clears it.
notesobject
Left out keeps the stored value; null or an empty value clears it.
customFieldsobject
Object of values; replaces the stored values. Left out keeps them; null clears them.
tagsstring[]
Tag names; replace the stored tags. Left out keeps them; null or [] removes them all.
createdboolean
Responses of POST /v1/contacts (and its bulk items): false when a contact with that phone on that channel in that location was updated.
lastActivitystring
createdAtstring
When the record was created (ISO 8601, UTC).
updatedAtstring
When the record was last changed (ISO 8601, UTC).
Request
curl -X PUT "https://api.whautomate.com/v1/contacts/NSasDKs69e" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "Lead",
    "notes": "Asked about corporate packages for 20 staff."
  }'
Response 200
{
  "id": "NSasDKs69e",
  "name": "Arjun Menon",
  "channel": "whatsapp",
  "phoneNumber": "6598812046",
  "lastActivity": "2026-10-29T12:40:11.019Z",
  "notes": "Asked about corporate packages for 20 staff.",
  "stage": "Lead",
  "tags": [
    "Price enquiry"
  ],
  "location": {
    "id": "Le6dWjQF9K",
    "title": "Serene Wellness Studio"
  },
  "createdAt": "2026-10-29T12:40:11.026Z",
  "updatedAt": "2026-10-29T12:40:11.321Z"
}

Delete a contact​

DEL /v1/contacts/{contactId}

Deletes a contact.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
contactIdstringrequired
Response 200
successboolean
Request
curl -X DELETE "https://api.whautomate.com/v1/contacts/NSasDKs69e" \
  -H "x-api-key: YOUR_API_KEY"
Response 200
{
  "success": true
}

Add tags to a contact​

POST /v1/contacts/{contactId}/tags/add

Adds tags to a contact. Unknown tags are created. Adding a tag can start automations.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
tagsstring[]required
Tag names. Unknown tags are created.
Response 200
idstring
tagsstring[]
The tags on the record after the change.
Request
curl -X POST "https://api.whautomate.com/v1/contacts/NSasDKs69e/tags/add" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "Corporate",
      "Hot lead"
    ]
  }'
Response 200
{
  "id": "NSasDKs69e",
  "tags": [
    "Price enquiry",
    "Corporate"
  ]
}

Remove tags from a contact​

POST /v1/contacts/{contactId}/tags/remove

Removes tags from a contact.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
tagsstring[]required
Tag names. Unknown tags are created.
Response 200
idstring
tagsstring[]
The tags on the record after the change.
Request
curl -X POST "https://api.whautomate.com/v1/contacts/NSasDKs69e/tags/remove" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      "Price enquiry"
    ]
  }'
Response 200
{
  "id": "NSasDKs69e",
  "tags": [
    "Corporate",
    "Hot lead"
  ]
}

Assign a contact's chat​

POST /v1/contacts/{contactId}/assign-chat

Assigns a contact's conversation to a team member and marks it as open, for example after a lead is qualified in your own system. Get the staffId from Staffs.

Headers
x-api-keystringrequired
Your Whautomate API key.
Path parameters
contactIdstringrequired
Body
staffIdstringrequired
Response 200
idstring
successboolean
Request
curl -X POST "https://api.whautomate.com/v1/contacts/NSasDKs69e/assign-chat" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "staffId": "XCRbjjnGrB"
  }'
Response 200
{
  "id": "NSasDKs69e",
  "success": true
}

Bulk​

Bulk endpoints take up to 100 items and run each one through the single endpoint (same checks and plan limits). They answer 200 with a result per item, so check failed. Bulk calls run no automations; webhooks still fire.

Create or update contacts in bulk​

POST /v1/contacts/bulk

Creates contacts, or updates the contact with the same phone on the same channel (channel whatsapp, the default, or sms, as POST /v1/contacts) in that location (partial; each result data has created true or false). Up to 100 items, run one by one through the single route (same validation and plan limits, per item deactivated location check). Bulk runs no automations; webhooks still fire.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
itemsobject[]required

Up to 100 contact create bodies, the same as POST /v1/contacts

Response 200
succeededinteger
failedinteger
resultsobject[]
Request
curl -X POST "https://api.whautomate.com/v1/contacts/bulk" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Mei Chen",
        "phoneNumber": "6591835507",
        "location": {
          "id": "Le6dWjQF9K"
        },
        "tags": [
          "Instagram ad"
        ]
      },
      {
        "name": "Farid Hassan",
        "location": {
          "id": "Le6dWjQF9K"
        }
      }
    ]
  }'
Response 200
{
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 200,
      "data": {
        "id": "ABo2fvzCBz",
        "name": "Mei Chen",
        "channel": "whatsapp",
        "phoneNumber": "6591835507",
        "lastActivity": "2026-10-29T12:40:11.782Z",
        "tags": [
          "Instagram ad"
        ],
        "location": {
          "id": "Le6dWjQF9K",
          "title": "Serene Wellness Studio"
        },
        "createdAt": "2026-10-29T12:40:11.786Z",
        "updatedAt": "2026-10-29T12:40:11.786Z",
        "created": true
      }
    },
    {
      "index": 1,
      "ok": false,
      "status": 400,
      "error": "Invalid parameters"
    }
  ]
}

Update contacts in bulk​

POST /v1/contacts/bulk/update

Updates contacts partially (as PUT /v1/contacts/{contactId}); every item needs id. Up to 100 items, run one by one through the single route (same validation and plan limits, per item deactivated location check). Bulk runs no automations; webhooks still fire.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
itemsobject[]required

Up to 100 update bodies, the same as PUT /v1/contacts/{contactId}, each with the record id

Response 200
succeededinteger
failedinteger
resultsobject[]
Request
curl -X POST "https://api.whautomate.com/v1/contacts/bulk/update" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "ABo2fvzCBz",
        "stage": "Lead"
      },
      {
        "id": "doesNotExist1",
        "notes": "Call back on Monday"
      }
    ]
  }'
Response 200
{
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 200,
      "data": {
        "id": "ABo2fvzCBz",
        "name": "Mei Chen",
        "channel": "whatsapp",
        "phoneNumber": "6591835507",
        "lastActivity": "2026-10-29T12:40:11.782Z",
        "stage": "Lead",
        "tags": [
          "Instagram ad"
        ],
        "location": {
          "id": "Le6dWjQF9K",
          "title": "Serene Wellness Studio"
        },
        "createdAt": "2026-10-29T12:40:11.786Z",
        "updatedAt": "2026-10-29T12:40:11.889Z"
      }
    },
    {
      "index": 1,
      "ok": false,
      "status": 404,
      "error": "Contact not found"
    }
  ]
}

Delete contacts in bulk​

POST /v1/contacts/bulk/delete

Deletes contacts by contactIds. Up to 100 items, run one by one through the single route (same validation and plan limits, per item deactivated location check). Bulk runs no automations; webhooks still fire.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
contactIdsstring[]required
Up to 100
Response 200
succeededinteger
failedinteger
resultsobject[]
Request
curl -X POST "https://api.whautomate.com/v1/contacts/bulk/delete" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "ABo2fvzCBz",
      "doesNotExist1"
    ]
  }'
Response 200
{
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 200,
      "data": {
        "success": true
      }
    },
    {
      "index": 1,
      "ok": false,
      "status": 404,
      "error": "Contact not found"
    }
  ]
}

Add tags to contacts in bulk​

POST /v1/contacts/bulk/add-tags

Adds tags to contacts. Up to 100 items, run one by one through the single route (same validation and plan limits, per item deactivated location check). Bulk runs no automations; webhooks still fire.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
contactIdsstring[]required
Up to 100
tagsstring[]required
Tag names
Response 200
succeededinteger
failedinteger
resultsobject[]
Request
curl -X POST "https://api.whautomate.com/v1/contacts/bulk/add-tags" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "ABo2fvzCBz",
      "NSasDKs69e"
    ],
    "tags": [
      "November promo"
    ]
  }'
Response 200
{
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 200,
      "data": {
        "id": "ABo2fvzCBz",
        "tags": [
          "Instagram ad",
          "November promo"
        ]
      }
    },
    {
      "index": 1,
      "ok": true,
      "status": 200,
      "data": {
        "id": "NSasDKs69e",
        "tags": [
          "Corporate",
          "Hot lead"
        ]
      }
    }
  ]
}

Remove tags from contacts in bulk​

POST /v1/contacts/bulk/remove-tags

Removes tags from contacts. Up to 100 items, run one by one through the single route (same validation and plan limits, per item deactivated location check). Bulk runs no automations; webhooks still fire.

Headers
x-api-keystringrequired
Your Whautomate API key.
Body
contactIdsstring[]required
Up to 100
tagsstring[]required
Tag names
Response 200
succeededinteger
failedinteger
resultsobject[]
Request
curl -X POST "https://api.whautomate.com/v1/contacts/bulk/remove-tags" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "ABo2fvzCBz",
      "NSasDKs69e"
    ],
    "tags": [
      "November promo"
    ]
  }'
Response 200
{
  "succeeded": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "status": 200,
      "data": {
        "id": "ABo2fvzCBz",
        "tags": [
          "Instagram ad"
        ]
      }
    },
    {
      "index": 1,
      "ok": true,
      "status": 200,
      "data": {
        "id": "NSasDKs69e",
        "tags": [
          "Corporate",
          "Hot lead"
        ]
      }
    }
  ]
}
Last updated on