Contacts API - Create, Update and Sync Contacts

Create, update, look up and bulk sync ChatMaxima contacts by API, with custom attributes and your own ids, to keep your CRM and your messaging contacts in step.

Overview

The Contacts API keeps ChatMaxima's contacts in step with your CRM, store or database. You can create or update one contact, sync up to 500 at a time, look a contact up by your own id, and list contacts across every channel in your workspace.

Each contact has a contact_id, shared across every channel the person uses. Once they have messaged you on a channel, you can send to them there with the Send Messages API using either contact_id or your own id, stored as contact_vendor_ref_id.

Prerequisites

An API key on a plan with API access (Pro or higher). See ChatMaxima API.

The contact object

{
  "contact_id": "abc123def456",
  "contact_vendor_ref_id": "crm-001",
  "contact_name": "Jane Doe",
  "contact_email": "jane@example.com",
  "contact_mobile": "15551234567",
  "contact_location": "",
  "contact_organization": "Acme Inc",
  "contact_bio": "",
  "contact_image_url": "",
  "contact_attributes": { "plan_tier": "gold" },
  "contact_created_at": "2026-01-01 10:00:00",
  "contact_updated_at": "2026-01-02 10:00:00"
}

Field	Description
`contact_id`	ChatMaxima's id for the person, shared across all their channels.
`contact_vendor_ref_id`	Your own id for the contact.
`contact_name`, `contact_email`, `contact_mobile`	Name, email and mobile. Mobile is stored as digits only, without `+` or spaces.
`contact_location`, `contact_organization`, `contact_bio`, `contact_image_url`	Optional profile details.
`contact_attributes`	Your custom attributes, keyed by attribute name.
`contact_created_at`, `contact_updated_at`	Timestamps in UTC.

Create or update a contact

POST /api/v2/contacts/ creates the contact, or updates it if it already exists.

curl -X POST https://chatmaxima.com/api/v2/contacts/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_vendor_ref_id": "crm-001",
    "contact_name": "Jane Doe",
    "contact_email": "jane@example.com",
    "contact_mobile": "+15551234567",
    "contact_attributes": { "plan_tier": "gold", "signup_source": "website" }
  }'

Send at least one of contact_vendor_ref_id, contact_mobile (or contact_phone) and contact_email. All other fields are optional.

How a match is found:

If contact_vendor_ref_id is sent, the contact with that id is updated.
Otherwise, a contact created through the API with the same mobile and email is updated. If you send both, both must match.
If nothing matches, a new contact is created. When the same person already exists on another channel, for example WhatsApp, the new record is linked to them by mobile number, or by email, and you get their existing contact_id back.

The response is 201 with message "Contact created successfully." for a new contact, or 200 with "Contact updated successfully." for an update. data is the contact object.

Note: On update, only the fields you send are changed. Sending a contact_attributes key that does not exist yet creates a new custom attribute in your workspace. Empty values are ignored, so you cannot clear an attribute through the API.

Sync contacts in bulk

POST /api/v2/contacts/sync/ creates or updates up to 500 contacts in one call, using the same rules as above for each one.

curl -X POST https://chatmaxima.com/api/v2/contacts/sync/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "contact_vendor_ref_id": "crm-001", "contact_name": "Jane Doe", "contact_mobile": "+15551234567" },
      { "contact_vendor_ref_id": "crm-002", "contact_email": "sam@example.com" }
    ]
  }'

One bad contact does not stop the batch. The response reports each one by its position:

{
  "status": "success",
  "code": 200,
  "message": "Contact sync completed.",
  "data": {
    "created": 1,
    "updated": 1,
    "failed": 0,
    "total": 2,
    "results": [
      { "index": 0, "status": "updated", "contact_id": "abc123def456" },
      { "index": 1, "status": "created", "contact_id": "xyz789ghi012" }
    ]
  }
}

Get a contact

curl https://chatmaxima.com/api/v2/contacts/crm-001/ \
  -H "Authorization: YOUR_API_KEY"

The id in the path can be the contact_id or your contact_vendor_ref_id. It returns 404 NOT_FOUND if no contact matches.

Update a contact

PUT /api/v2/contacts/{id}/ changes only the fields you send. The change applies to the person on every channel they use.

curl -X PUT https://chatmaxima.com/api/v2/contacts/crm-001/ \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_organization": "Acme Inc", "contact_attributes": { "plan_tier": "platinum" } }'

The mobile number of a contact who reached you on WhatsApp or SMS cannot be changed, because it identifies them on that channel. Trying returns 422 MOBILE_LOCKED.

List contacts

GET /api/v2/contacts/ lists contacts from every channel in your workspace, newest first, one row per person.

Query parameter	Description
`search`	Matches part of the name, email or mobile.
`contact_vendor_ref_id`	Exact match on your own id.
`contact_mobile`	Exact match on the mobile number.
`contact_email`	Exact match on the email.
`page`	Page number, starting at 1.
`per_page`	Contacts per page, 1 to 100. Default 20.

Contacts with neither an email nor a mobile number are not listed. The response meta contains page, per_page, total, total_pages, has_next and has_prev.

Errors

HTTP	Code	When it happens
400	`INVALID_JSON`	The body is not valid JSON.
400	`MISSING_CONTACTS_ARRAY`	Sync was called without a `contacts` array.
404	`NOT_FOUND`	No contact matches the id in the path.
422	`INVALID_CONTACT`	None of `contact_vendor_ref_id`, `contact_mobile` and `contact_email` was sent.
422	`BATCH_TOO_LARGE`	Sync was sent more than 500 contacts.
422	`MOBILE_LOCKED`	You tried to change the mobile of a WhatsApp or SMS contact.

Authentication, plan and rate-limit errors are listed on the API overview.

Best Practices

Always send contact_vendor_ref_id so updates find the right contact every time.
Send mobile numbers with the country code. They are stored as digits only.
Use sync for imports, and keep each call to 500 contacts or fewer.