Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ArnasDon/wacrm/llms.txt

Use this file to discover all available pages before exploring further.

The Contacts API gives you programmatic access to your contact directory. You can list and search contacts, create new ones, and update existing records. All contact lookups are account-scoped — contacts belonging to a different account always return 404, never 403.

​
GET /api/v1/contacts

Required scope: contacts:read Returns a paginated list of contacts ordered newest first. See Pagination and Errors for cursor mechanics and the ?limit= parameter.

​
Query parameters

ParameterTypeDescription
searchstringCase-insensitive substring match against the contact’s name or phone.
tagstringFilter to contacts that have the tag with this tag UUID. Returns the contact’s full tag set.
limitnumberPage size; default 50, max 100.
cursorstringOpaque cursor from the previous page’s meta.next_cursor. Omit for the first page.

​
Response

{
  "data": [
    {
      "id": "a1b2c3d4-…",
      "phone": "+14155550123",
      "name": "Jane Doe",
      "email": null,
      "company": "Acme",
      "avatar_url": null,
      "tags": [
        { "id": "t1u2v3w4-…", "name": "vip", "color": "#3b82f6" }
      ],
      "created_at": "2026-01-15T09:00:00.000Z",
      "updated_at": "2026-06-20T14:30:00.000Z"
    }
  ],
  "meta": { "next_cursor": "eyJ…" }
}
​
data
Contact[]
Array of contact objects for the current page.
​
meta.next_cursor
string | null
Opaque cursor for the next page. null indicates the last page.

​
POST /api/v1/contacts

Required scope: contacts:write Creates a contact. The operation is find-or-create by phone number: if a contact with the given E.164 number already exists in your account, it is returned as-is with HTTP 200; a genuinely new contact returns HTTP 201. This makes POST /api/v1/contacts safe to call idempotently from automations that receive phone numbers without knowing whether a record already exists.

​
Request body

​
phone
string
required
The contact’s phone number in E.164 format (e.g. +14155550123). Used as the unique key for find-or-create.
​
name
string
Display name for the contact.
​
email
string
Email address for the contact.
​
company
string
Company or organisation name.
​
tags
string[]
An array of tag names (not IDs) to assign to the contact. Tags that do not yet exist in your account are created automatically. This replaces any tags set during a prior create call only if the contact is new — to update tags on an existing contact, use PATCH /api/v1/contacts/{id}.

​
Response

Returns the serialized contact object (same shape as the list rows above). HTTP status is 200 when an existing record was matched, 201 when a new contact was created. 
curl -X POST https://your-crm.example.com/api/v1/contacts \
  -H "Authorization: Bearer wacrm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
        "phone": "+14155550123",
        "name": "Jane Doe",
        "company": "Acme",
        "tags": ["vip", "onboarding"]
      }'
The HTTP status code (200 vs. 201) is the reliable signal for whether the contact already existed. Both responses contain the full contact object.

​
GET /api/v1/contacts/{id}

Required scope: contacts:read Returns a single contact by its UUID. Returns 404 if the contact does not exist or if it belongs to a different account — Wacrm never reveals that a resource exists in another account. 
curl https://your-crm.example.com/api/v1/contacts/a1b2c3d4-… \
  -H "Authorization: Bearer wacrm_live_xxx"

​
PATCH /api/v1/contacts/{id}

Required scope: contacts:write Partially updates a contact. Only the fields you include in the request body are changed — omitted fields are left untouched. Sending null for a field clears it.

​
Request body

​
name
string | null
Updated display name. Send null to clear.
​
email
string | null
Updated email address. Send null to clear.
​
company
string | null
Updated company name. Send null to clear.
​
tags
string[]
An array of tag names that replaces the contact’s current tag set entirely. Pass an empty array ([]) to remove all tags. Omit the field to leave tags unchanged.
Returns 404 if the contact does not exist or belongs to a different account. On success, returns the updated contact object with HTTP 200. 
curl -X PATCH https://your-crm.example.com/api/v1/contacts/a1b2c3d4-… \
  -H "Authorization: Bearer wacrm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "company": "Acme Corp", "tags": ["vip"] }'
Sending tags in a PATCH request replaces the entire tag set. If you want to add a single tag without removing others, fetch the current tags first with GET /api/v1/contacts/{id}, merge locally, then send the full list.

Build docs developers (and LLMs) love

Get started for freeTalk to us