Contacts

Keep WhautoChat contacts in sync with your own systems: create a contact when someone fills in a form, update their details from your CRM, tag them, assign their chat to a team member, or remove them. Contacts created here are the same contacts your team sees in the inbox.

Conventions

Send your key in the x-api-key header and bodies as JSON with Content-Type: application/json. Requests without a valid key get 401 { "message": "Unauthorized" }; other errors look like { "error": "message" }. The workspace goes in the request (workspace: { "id" } in the body, or ?workspaceId= when listing). Lists are plain arrays, paged with page (default 1) and limit (default 10, max 100; higher values are reduced to 100): keep increasing page until you get fewer results than your limit. See REST API for your API host and key.

Endpoints

GET/v1/contactsList contacts POST/v1/contactsCreate a WhatsApp contact GET/v1/contacts/{id}Get a contact PUT/v1/contacts/{id}Update a contact DEL/v1/contacts/{id}Delete a contact POST/v1/contacts/{id}/tags/addAdd tags POST/v1/contacts/{id}/tags/removeRemove tags POST/v1/contacts/{id}/assign-chatAssign the chat to a team member

The contact object

Attributes

idstring

The contact id. Use it in the other contact endpoints and in the Messages API.

namestring

The contact's name

channelstring

whatsapp, telegram, instagram, tiktok, messenger or website. Contacts created or updated through this API are always whatsapp.

phoneNumberstring

Stored without the leading +

username, messengerId, telegramChatId, instagramIdstring

The contact's identifier on other channels, when set

lastActivitystring

Last activity time

notesstring

Free text notes

stagestring

The contact stage, for example Lead or Customer

tagsstring[]

Tag names on the contact

customFieldsobject

Your custom field values as key and value pairs

workspaceobject

The workspace the contact belongs to: { id, title }

createdAt, updatedAtstring

Timestamps

Fields with no value are left out of the response.

The contact object
{
  "id": "Xk82LmQp4T",
  "name": "Maria Lopez",
  "channel": "whatsapp",
  "phoneNumber": "12025550188",
  "lastActivity": "2026-10-12T14:05:11.000Z",
  "notes": "Prefers morning appointments",
  "stage": "Lead",
  "tags": ["new-customer", "newsletter"],
  "customFields": {
    "city": "Austin",
    "plan": "Premium"
  },
  "workspace": {
    "id": "Wq3nT8vYp1",
    "title": "Downtown Studio"
  },
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-12T14:06:40.902Z"
}

List contacts

GET/v1/contacts

Query parameters

workspaceIdstring

Only contacts in this workspace. Must be a workspace in your account.

channelstringdefault all

Only contacts on this channel, for example whatsapp

tagsstring

Comma-separated tag names, for example vip,newsletter. Returns contacts that have any of them. Names must match exactly, including case.

searchTextstring

Matches part of the contact's name, phone number or tags. Not case sensitive.

pageintegerdefault 1

limitintegerdefault 10

Max 100. Higher values are reduced to 100.

200 OK: a JSON array of contacts. When it has fewer than limit items, it's the last page.

Errors

Status	Body	When
`404`	`{ "error": "Invalid Workspace Id" }`	`workspaceId` isn't in your account
`500`	`{ "error": "Could not retrieve Contacts" }`	The request could not be completed. Retry.

Request
curl "https://api.whauto.chat/v1/contacts?workspaceId=Wq3nT8vYp1&tags=vip,newsletter&page=1&limit=50" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
[
  {
    "id": "Xk82LmQp4T",
    "name": "Maria Lopez",
    "channel": "whatsapp",
    "phoneNumber": "12025550188",
    "tags": ["vip"],
    "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
    "createdAt": "2026-10-12T14:05:11.000Z",
    "updatedAt": "2026-10-12T14:06:40.902Z"
  }
]

Create a contact

POST/v1/contacts

Creates a WhatsApp contact in a workspace.

Body parameters

namestringrequired

The contact's name

phoneNumberstringrequired

Full international number with country code, for example +12025550188. Send digits only after the + (no spaces, dashes or brackets): only the leading + is removed, so other characters are stored as sent.

workspaceobjectrequired

The workspace for the contact

stagestring

Contact stage, for example Subscriber, Lead, Engaged, Customer or Inactive

tagsstring[]

Tag names. Spaces around each name are trimmed. Tags that don't exist in your account yet are created.

notesstring

Free text notes

customFieldsobject

Custom field values, for example { "city": "Austin" }

200 OK: the new contact.

The same number can exist once in each workspace. If a contact with the same phone number (compared on its digits) already exists there, nothing is created: find it with GET /v1/contacts?searchText=12025550188 and update it.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`name`, `phoneNumber` or `workspace.id` is missing
`400`	`{ "error": "Contact exists for the phoneNumber" }`	A contact with that number already exists in the workspace
`400`	`{ "error": "5000 Contact Limit reached. Please upgrade your subscription or purchase add-ons to add new contacts." }`	Your plan's contact limit is reached (the body has the limit message)
`404`	`{ "error": "Invalid Workspace" }`	The workspace isn't in your account
`500`	`{ "error": "Could not create Contact" }`	The request could not be completed. Retry.

Request
curl -X POST https://api.whauto.chat/v1/contacts \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Lopez",
    "phoneNumber": "+12025550188",
    "workspace": { "id": "Wq3nT8vYp1" },
    "stage": "Lead",
    "tags": ["new-customer", "newsletter"],
    "notes": "Prefers morning appointments",
    "customFields": { "city": "Austin", "plan": "Premium" }
  }'

Response 200
{
  "id": "Xk82LmQp4T",
  "name": "Maria Lopez",
  "channel": "whatsapp",
  "phoneNumber": "12025550188",
  "lastActivity": "2026-10-12T14:05:11.000Z",
  "notes": "Prefers morning appointments",
  "stage": "Lead",
  "tags": ["new-customer", "newsletter"],
  "customFields": { "city": "Austin", "plan": "Premium" },
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-12T14:05:11.000Z"
}

Get a contact

GET/v1/contacts/{id}

Path parameters

idstringrequired

Contact id

200 OK: the contact.

Errors

Status	Body	When
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`500`	`{ "error": "Could not retrieve Contact" }`	The request could not be completed. Retry.

Request
curl "https://api.whauto.chat/v1/contacts/Xk82LmQp4T" \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{
  "id": "Xk82LmQp4T",
  "name": "Maria Lopez",
  "channel": "whatsapp",
  "phoneNumber": "12025550188",
  "stage": "Lead",
  "tags": ["new-customer", "newsletter"],
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-12T14:06:40.902Z"
}

Update a contact

PUT/v1/contacts/{id}

Path parameters

idstringrequired

Contact id

This is a full update, so name, phoneNumber and workspace.id are required every time, even if they haven't changed.

Body parameters

namestringrequired

The contact's name

phoneNumberstringrequired

Full international number. A leading + is removed.

workspaceobjectrequired

The contact's workspace

stagestring

Replaces the stage

tagsstring[]

Replaces all of the contact's tags. New tag names are created in your account.

notesstring

Replaces the notes

customFieldsobject

Replaces all custom field values. Keys you leave out are removed.

200 OK: the updated contact.

If you leave out stage, notes, customFields or tags (or send an empty value), the current value is kept. You can't clear them with this endpoint. To remove tags, use remove tags.
Updating sets the contact's channel to whatsapp and its last activity to the current time.
This endpoint doesn't check whether another contact already has the new phone number.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`name`, `phoneNumber` or `workspace.id` is missing
`404`	`{ "error": "Invalid Workspace" }`	The workspace isn't in your account
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`500`	`{ "error": "Could not update Contact" }`	The request could not be completed. Retry.

Request
curl -X PUT https://api.whauto.chat/v1/contacts/Xk82LmQp4T \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Lopez",
    "phoneNumber": "+12025550188",
    "workspace": { "id": "Wq3nT8vYp1" },
    "stage": "Customer",
    "customFields": { "city": "Austin", "plan": "Enterprise" }
  }'

Response 200
{
  "id": "Xk82LmQp4T",
  "name": "Maria Lopez",
  "channel": "whatsapp",
  "phoneNumber": "12025550188",
  "lastActivity": "2026-10-14T09:30:00.000Z",
  "notes": "Prefers morning appointments",
  "stage": "Customer",
  "tags": ["new-customer", "newsletter"],
  "customFields": { "city": "Austin", "plan": "Enterprise" },
  "workspace": { "id": "Wq3nT8vYp1", "title": "Downtown Studio" },
  "createdAt": "2026-10-12T14:05:11.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

Delete a contact

DEL/v1/contacts/{id}

Path parameters

idstringrequired

Contact id

Permanently deletes the contact. Its related records are cleaned up in the background afterwards, and it no longer counts toward your plan's contact limit.

Errors

Status	Body	When
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`500`	`{ "error": "Could not delete Contact" }`	The request could not be completed. Retry.

Request
curl -X DELETE https://api.whauto.chat/v1/contacts/Xk82LmQp4T \
  -H "x-api-key: $WHAUTOCHAT_API_KEY"

Response 200
{ "success": true }

Add tags to a contact

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

Path parameters

idstringrequired

Contact id

Body parameters

tagsstring[]required

At least one tag name. Names are case sensitive and used exactly as sent.

Adds tags without touching the contact's other tags. Tags the contact already has are skipped, and tag names that don't exist in your account yet are created.

200 OK: the contact id and its full tag list.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`tags` is missing or empty
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`500`	`{ "error": "Could not add Contact Tags" }`	The request could not be completed. Retry.

Request
curl -X POST https://api.whauto.chat/v1/contacts/Xk82LmQp4T/tags/add \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["vip", "black-friday-2026"] }'

Response 200
{
  "id": "Xk82LmQp4T",
  "tags": ["new-customer", "newsletter", "vip", "black-friday-2026"]
}

Remove tags from a contact

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

Path parameters

idstringrequired

Contact id

Body parameters

tagsstring[]required

At least one tag name

Tags the contact doesn't have are ignored. The tags stay in your account's tag list; use the Contact tags API to delete a tag itself.

200 OK: the contact id and its remaining tags.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`tags` is missing or empty
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`500`	`{ "error": "Could not remove Contact Tags" }`	The request could not be completed. Retry.

Request
curl -X POST https://api.whauto.chat/v1/contacts/Xk82LmQp4T/tags/remove \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["newsletter"] }'

Response 200
{
  "id": "Xk82LmQp4T",
  "tags": ["new-customer", "vip", "black-friday-2026"]
}

Assign a chat

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

Path parameters

idstringrequired

Contact id

Body parameters

staffIdstringrequired

The team member's id, from the Staff API (GET /v1/staffs)

Assigns the contact's conversation to a team member and sets the conversation status to open. Use it to hand a conversation to a person from your own routing logic.

200 OK: the contact id and success: true.

Errors

Status	Body	When
`400`	`{ "error": "Invalid parameters" }`	`staffId` is missing
`404`	`{ "error": "Contact not found" }`	The contact isn't in your account
`404`	`{ "error": "Staff not found" }`	The team member isn't in your account
`500`	`{ "error": "Could not assign chat to staff" }`	The request could not be completed. Retry.

Request
curl -X POST https://api.whauto.chat/v1/contacts/Xk82LmQp4T/assign-chat \
  -H "x-api-key: $WHAUTOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "staffId": "Pr7bK2mWx9" }'

Response 200
{
  "id": "Xk82LmQp4T",
  "success": true
}

The contact object​

List contacts​

Create a contact​

Get a contact​

Update a contact​

Delete a contact​

Add tags to a contact​

Remove tags from a contact​

Assign a chat​

The contact object

List contacts

Create a contact

Get a contact

Update a contact

Delete a contact

Add tags to a contact

Remove tags from a contact

Assign a chat