CRM API & MCPREADMEDownload YAML

AiEngage CRM Public API

Create, read, update, archive, search, batch-process and link CRM records through one module-agnostic API, plus the field metadata that tells you what each module contains.

Start here: paste your token

Step 1 below has a Paste your key here box. Put your cak_live_… key into it once. From that moment:

  • every code sample on this page — curl, Python, Node, PHP — is written with your token in it, ready to copy and run;
  • the Send button on each endpoint makes the real call and shows you the real response beside it;
  • your browser remembers it, so you only do this once.

Your token stays in this browser and is sent only to your own CRM.

No token yet? Step 1 below shows you where to get one.

What this API is

One API for every CRM module - Contacts, Deals, Companies, Products, and any custom module your organization creates. You name the module in the URL:

There is no separate "Contacts API" and "Deals API" to learn. The request is the same shape every time - only the module name and the field names change.

GET /api/public/v1/objects/contacts
GET /api/public/v1/objects/deals
GET /api/public/v1/objects/your_custom_module

How to use it

  1. Get an API token - in the CRM, Settings → API Keys → Create.
  2. Pick your module - the slug that goes in the URL, like contacts.
  3. Check its fields - GET /properties/{module} lists them.
  4. Enter your data - edit the body in the panel beside any endpoint.
  5. Copy the cURL, or press Send - and read the response.

Each of those is one step below.


Quick Start

Five minutes, start to finish.

Step 1 - Get an API token

In the CRM: Settings → API Keys → Create. Tick the scopes you need - for this guide, crm.contacts.read, crm.contacts.write and crm.schema.read.

One key is enough for everything. Scopes mix freely, so the same key can read records, send email and send WhatsApp. To use every endpoint here, also tick email.from_addresses.read, email.messages.send, email.transactional.send, whatsapp.templates.read and whatsapp.templates.send.

You get a token like cak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6. Copy it now - it is shown only once.

The token acts as the user who created it, and sees only the records that person can see. Two keys from one organization can legitimately return different results.

Paste your key here

One box, once. Every curl, Python, Node and PHP example on this page is rewritten with your key, and the Send buttons start making real calls.

Until you paste one, every example below reads Bearer YOUR_API_TOKEN and Send will come back 401. The key stays in this browser — it is never sent anywhere except to the API you are calling.

Step 2 - Send it on every request

One header, on every call:

You do not have to type it here. Paste your key into the Paste your key here box in Step 1, and every sample on this page - curl, Python, Node, PHP - is rewritten with it, the Send buttons start making real calls, and your browser remembers it.

Paste the key on its own. If you copy it out of Postman it may arrive as Bearer cak_live_...; the box strips that, so the header is never written twice.

Your key is stored in this browser only. Send calls your CRM directly - nothing is relayed through the documentation host.

To run something this page does not list, open the Console in the header, paste any curl, and press Send.

If Send says the request never left the browser, that host has not allowed this page's origin. The sample is still correct - press Copy and run it in a terminal.

Authorization: Bearer cak_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Step 3 - Find out which modules exist

This returns the modules your key can address, each with the slug you put in the URL.

Note: GET /objects is outside this document's scope - it is part of the wider Public API rather than the Modules API documented here, and it was implemented separately. It is shown because it is genuinely the easiest way to discover module names. If you would rather not use it, the Supported modules table further down lists the standard slugs.

curl "https://app.aiengagecrm.com/cback/api/public/v1/objects" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 4 - Find out what a module contains

This is the call that matters most, and the one most people skip:

Read it like this:

KeyWhy you care
nameThe exact key to put inside properties. Not the label.
required_on_createLeave it out of a create and the call fails.
uniqueSafe to use as id_property or matching_property.
optionsFor a picklist, the only values that will be accepted.

Field names differ per organization. An admin can rename, add or hide fields. Never hardcode a field list - read it from here.

curl "https://app.aiengagecrm.com/cback/api/public/v1/properties/contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "results": [
    {
      "name": "email",
      "label": "Email",
      "type": "email",
      "required_on_create": false,
      "unique": true,
      "options": null
    },
    {
      "name": "first_name",
      "label": "First Name",
      "type": "single_line",
      "required_on_create": true,
      "unique": false,
      "options": null
    }
  ]
}

Step 5 - Create your first record

That is the whole loop: authenticate → discover the module → read its fields → write a record.


curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"first_name":"Ada","last_name":"Lovelace","email":"ada@example.com"}}'
{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com" },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}

Every request in Postman

One import, and all 24 endpoints arrive ready to run.

  1. Postman -> Import -> Link
  2. Paste this URL:

  1. Add your token as collection-level Bearer Token auth - every request inherits it.

That URL belongs in Import, not in the address bar of a new request. A request to the document downloads it: you get 200 and a screenful of YAML in the response pane, and nothing in your sidebar. Import is what turns one file into 23 requests.

The collection arrives pointing at the live API already - the document names it as the first server, and Postman takes the base URL from there. Change it only to call a different instance.

You get one request per endpoint, grouped by tag, each carrying real request and response examples - so they run rather than arriving as empty shells.

Prefer a file? Download YAML at the top of this page is the same document, for Import -> File.

The same file imports into Insomnia, Hoppscotch, Stoplight, Redocly and anything else that reads OpenAPI 3.1. openapi-generator will produce a typed client from it directly.


https://developer.aiengagecrm.com/module-public-api.yaml

The endpoints

These say "contact" because that is the one everybody starts with, and because a sentence about a record is a sentence about nothing in particular. Swap the word for whatever you are addressing: {module} is contacts here, and deals, companies, tickets or any other module you can reach works the same way, with the same 24 calls.


Click any endpoint to see what it does and get its ready-made curl command. Copy the command and paste it into a terminal — that is the whole thing. Paste your key in the box at the top and every command here fills itself in; until then they carry YOUR_API_TOKEN for you to replace.

Records

Get Records

What you need
  • An API key. It has to be allowed to read records — the crm.{module}.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m

Purpose

Retrieve the records of a module, newest first, one page at a time. Scope

crm.{module}.read - e.g. calling /objects/contacts requires crm.contacts.read. Note

  • Results are limited to what the acting user may see. Two keys in the same organization can legitimately return different records.
  • Archived records are excluded unless you pass archived=true.
  • Paging is cursor-based. Take paging.next.after from the response and pass it back as ?after=; paging is absent on the last page.
  • limit is clamped to 1..100 rather than rejected.

Possible Errors

CodeHTTPDescriptionResolution
INVALID_CURSOR400The after value is malformed.Pass paging.next.after back verbatim; never build a cursor.
INVALID_PROPERTY400An include name is not a lookup field on this module, or more than 5 were sent.Check GET /properties/{module}.
MISSING_SCOPE403The key lacks crm.{module}.read, or a scope for a module named in include.The message lists every scope needed.
MODULE_NOT_AVAILABLE404Unknown, de-activated or unpublished module.Ask an admin to publish it.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Query parameters

NameTypeDescription
limitinteger
default 10
Page size. Clamped server-side to 1..100 - a value outside that range is silently clamped, not rejected.
afterstringOpaque forward cursor, taken verbatim from `paging.next.after` of the previous page. Do not construct one yourself - a malformed value returns 400 INVALID_CURSOR.
sortstring
default created_at:desc
`field:direction`. Direction is `asc` or `desc`; anything else falls back to `desc`, and an empty field falls back to `created_at`.
archivedstring · enumInclude archived (soft-deleted) records. Only the exact strings `true` and `any` switch this on; anything else is ignored.
propertiesstringComma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless.
includestringComma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum 5; more, or an unknown name, returns 400 INVALID_PROPERTY. Expanding requires `crm.<target>.read` for EVERY distinct target module across the returned rows; missing any returns 403 MISSING_SCOPE listing the full set needed.

Responses and errors

StatusWhat it means, and what to do about it
200

A page of records.

What the API sends back
{
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "properties": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "created_at": "2026-11-10T09:30:00.000Z",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "eyJpZCI6IjY2NTBmMWEyIn0",
      "link": "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?after=eyJpZCI6IjY2NTBmMWEyIn0&limit=25"
    }
  }
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

500

INTERNAL_ERROR - an unexpected failure, or the user who created this token has been deleted. Resolution: revoke the token and issue a new one. Quote correlationId when reporting it.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?sort=created_at%3Adesc&properties=email%2Cfirst_name
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?sort=created_at%3Adesc&properties=email%2Cfirst_name" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

Page size. Clamped server-side to 1..100 - a value outside that range is silently clamped, not rejected.

Opaque forward cursor, taken verbatim from `paging.next.after` of the previous page. Do not construct one yourself - a malformed value returns 400 INV

`field:direction`. Direction is `asc` or `desc`; anything else falls back to `desc`, and an empty field falls back to `created_at`.

Include archived (soft-deleted) records. Only the exact strings `true` and `any` switch this on; anything else is ignored.

Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless

Comma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Expected response200what a successful call returns
1{
2 "results": [
3 {
4 "id": "6650f1a2b3c4d5e6f7a8b9c0",
5 "properties": {
6 "first_name": "Ada",
7 "last_name": "Lovelace",
8 "email": "ada@example.com"
9 },
10 "created_at": "2026-11-10T09:30:00.000Z",
11 "updated_at": "2026-11-10T09:30:00.000Z",
12 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
13 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
14 "archived": false
15 }
16 ],
17 "paging": {
18 "next": {
19 "after": "eyJpZCI6IjY2NTBmMWEyIn0",
20 "link": "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?after=eyJpZCI6IjY2NTBmMWEyIn0&limit=25"
21 }
22 }
23}

Insert Record

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Create one record in a module. Scope

crm.{module}.write - granted only when the token's user has both create and edit permission on the module. Note

  • Only the presence and type of properties is checked at the HTTP layer. Per-field rules - date formats, picklist membership, numeric ranges, required fields - come from your organization's own field configuration, so a body this schema accepts can still be refused.
  • To create many records in one call, use POST /objects/{module}/batch/create instead.
  • Mandatory fields differ per module. Check required_on_create in GET /properties/{module}, or the per-module tables in this document.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400A field failed its rule, or properties is missing.errors[] names the property and the reason.
INVALID_PROPERTY400A key in properties is not a field on this module.Check GET /properties/{module} for real names.
MISSING_SCOPE403The key lacks crm.{module}.write.Remember it needs create AND edit permission.
MODULE_NOT_AVAILABLE404Unknown, de-activated or unpublished module.
IDEMPOTENCY_KEY_CONFLICT409The key was reused with a different body.Use a fresh key per operation.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
201

Created.

What the API sends back
{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

500

INTERNAL_ERROR - an unexpected failure, or the user who created this token has been deleted. Resolution: revoke the token and issue a new one. Quote correlationId when reporting it.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "properties": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada@example.com" } }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response201what a successful call returns
1{
2 "id": "6650f1a2b3c4d5e6f7a8b9c0",
3 "properties": {
4 "first_name": "Ada",
5 "last_name": "Lovelace",
6 "email": "ada@example.com"
7 },
8 "created_at": "2026-11-10T09:30:00.000Z",
9 "updated_at": "2026-11-10T09:30:00.000Z",
10 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
11 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
12 "archived": false
13}

Upsert Record

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • matching_property — required filter: The property to match an existing record on. Mandatory. Best used with a field whose `unique` flag is true.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Create a record, or update it if one already matches on a property you nominate. Useful for syncing from an external system where you know an email or an external id but not the CRM's record id. Scope

crm.{module}.write Note

  • matching_property is mandatory. It is validated in the controller rather than by the body validator, so omitting it gives 400 VALIDATION_ERROR with the message "Query parameter matching_property is required for PUT upsert."
  • The status is 200 whether it created or updated. Read the X-Upsert-Action response header - created or updated - to tell which happened.
  • Use a field marked unique in the property schema. A non-unique field that matches more than one record returns 409 CONFLICT rather than the API guessing which you meant.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400matching_property missing, or a field failed its rule.Add the query parameter.
INVALID_PROPERTY400matching_property is not a field on this module.Check GET /properties/{module}.
FORBIDDEN403The match would change the record's owner and the user lacks Change Owner.A permissions change, not a token change.
CONFLICT409The matching property is not unique and matched several records.Nominate a unique field.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Query parameters

NameTypeDescription
matching_propertyrequiredstringThe property to match an existing record on. Mandatory. Best used with a field whose `unique` flag is true.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

The resulting record. Read X-Upsert-Action to learn whether it was created or updated.

What the API sends back
{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}
400

VALIDATION_ERROR - including a missing matching_property - or INVALID_PROPERTY.

What the API sends back
{
  "status": "error",
  "message": "Query parameter matching_property is required for PUT upsert.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

FORBIDDEN - the acting user may not perform this operation - an owner change without Change Owner, say, or a batch with Mass Update off. Resolution: ask an admin to grant that permission on their profile.

404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

PUThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?matching_property=email
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts?matching_property=email" \
2 -X PUT \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "properties": { "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" } }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

The property to match an existing record on. Mandatory. Best used with a field whose `unique` flag is true.

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response200what a successful call returns
1{
2 "id": "6650f1a2b3c4d5e6f7a8b9c0",
3 "properties": {
4 "first_name": "Ada",
5 "last_name": "Lovelace",
6 "email": "ada@example.com"
7 },
8 "created_at": "2026-11-10T09:30:00.000Z",
9 "updated_at": "2026-11-10T09:30:00.000Z",
10 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
11 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
12 "archived": false
13}

Get Record

What you need
  • An API key. It has to be allowed to read records — the crm.{module}.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.

Purpose

Retrieve a single record by its id, or by any other property. Scope

crm.{module}.read Note

  • A record that exists but sits outside the acting user's visibility returns 404, exactly as a record that does not exist. This is deliberate: existence is never leaked.

Possible Errors

CodeHTTPDescriptionResolution
INVALID_PROPERTY400id_property is not a field on this module.Check GET /properties/{module}.
OBJECT_NOT_FOUND404No such record, or it is outside your visibility.The two are indistinguishable by design.
CONFLICT409id_property is not unique and matched several records.Nominate a unique field.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.

Query parameters

NameTypeDescription
id_propertystringAddress the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more than one record matches, the call returns 409 CONFLICT rather than picking one.
propertiesstringComma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless.
includestringComma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum 5; more, or an unknown name, returns 400 INVALID_PROPERTY. Expanding requires `crm.<target>.read` for EVERY distinct target module across the returned rows; missing any returns 403 MISSING_SCOPE listing the full set needed.

Responses and errors

StatusWhat it means, and what to do about it
200

The record.

What the API sends back
{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

OBJECT_NOT_FOUND - no such record, or it is outside your key's visibility. The two look alike on purpose, so existence never leaks. Resolution: check the id, and that your key's user can see it.

409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0?properties=email%2Cfirst_name
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0?properties=email%2Cfirst_name" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable
Paste your key above first.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

Address the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more tha

Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless

Comma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Expected response200what a successful call returns
1{
2 "id": "6650f1a2b3c4d5e6f7a8b9c0",
3 "properties": {
4 "first_name": "Ada",
5 "last_name": "Lovelace",
6 "email": "ada@example.com"
7 },
8 "created_at": "2026-11-10T09:30:00.000Z",
9 "updated_at": "2026-11-10T09:30:00.000Z",
10 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
11 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
12 "archived": false
13}

Update Record

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Update one record. Partial - only the properties you send are touched; everything else is left as it is. Scope

crm.{module}.write Note

  • Accepts id_property, so you can address the record by email or any other field rather than its id.
  • Changing the owner field needs the acting user to hold Change Owner in their profile. Without it the call returns 403, even though the token holds write.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400A field failed its rule.errors[] names the property.
FORBIDDEN403An owner change the acting user may not make.Needs Change Owner in their profile.
OBJECT_NOT_FOUND404No such record, or outside your visibility.
CONFLICT409id_property matched several records.Use a unique field.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.

Query parameters

NameTypeDescription
id_propertystringAddress the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more than one record matches, the call returns 409 CONFLICT rather than picking one.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

The updated record.

What the API sends back
{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": {
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com"
  },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

FORBIDDEN - the acting user may not perform this operation - an owner change without Change Owner, say, or a batch with Mass Update off. Resolution: ask an admin to grant that permission on their profile.

404

OBJECT_NOT_FOUND - no such record, or it is outside your key's visibility. The two look alike on purpose, so existence never leaks. Resolution: check the id, and that your key's user can see it.

409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

PATCHhttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0" \
2 -X PATCH \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "properties": { "lifecycle_stage": "customer" } }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable
Paste the id of a record you’re happy to change — we don’t fill real records for calls that change data.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

Address the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more tha

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response200what a successful call returns
1{
2 "id": "6650f1a2b3c4d5e6f7a8b9c0",
3 "properties": {
4 "first_name": "Ada",
5 "last_name": "Lovelace",
6 "email": "ada@example.com"
7 },
8 "created_at": "2026-11-10T09:30:00.000Z",
9 "updated_at": "2026-11-10T09:30:00.000Z",
10 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
11 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
12 "archived": false
13}

Archive Record

What you need
  • An API key. It has to be allowed to archive records — the crm.{module}.delete scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.

Purpose

Archive (soft-delete) one record. It stops appearing in listings and searches but is not destroyed. Scope

crm.{module}.delete - a separate scope from write, mapping to the module's delete permission. Note

  • Returns 204 with no body on success.
  • To see archived records again, list with ?archived=true.

Possible Errors

CodeHTTPDescriptionResolution
MISSING_SCOPE403The key holds write but not delete.They are separate scopes.
OBJECT_NOT_FOUND404No such record, or outside your visibility.
CONFLICT409id_property matched several records.Use a unique field.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.

Query parameters

NameTypeDescription
id_propertystringAddress the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more than one record matches, the call returns 409 CONFLICT rather than picking one.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
204

Archived. No body.

400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

OBJECT_NOT_FOUND - no such record, or it is outside your key's visibility. The two look alike on purpose, so existence never leaks. Resolution: check the id, and that your key's user can see it.

409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

DELETEhttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0" \
2 -X DELETE \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55"
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable
Paste the id of a record you’re happy to change — we don’t fill real records for calls that change data.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

Address the record by this property instead of its id - e.g. `id_property=email` with `id=ada@example.com`. If the property is not unique and more tha

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

This is real - it changes data in your CRM.

Search Records

Search Records

What you need
  • An API key. It has to be allowed to read records — the crm.{module}.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Find records matching a filter. A POST that reads - the body carries the filter, nothing is mutated. Scope

crm.{module}.read

Rate limit

This endpoint draws on the tighter search bucket: 5 requests per second, not the general 100 per 10 seconds. Budget for it. How filters combine

Filters inside one group are AND-ed. Groups are OR-ed with each other. Maximum 5 groups, maximum 6 filters per group.

Operators

OperatorTakesNotes
EQ NEQ LT LTE GT GTEvalue
BETWEENvalue + highValueInclusive both ends.
IN NOT_INvalues array
HAS_PROPERTY NOT_HAS_PROPERTYnothingTests whether the field is set at all.
CONTAINS_TOKEN NOT_CONTAINS_TOKENvalueCase-insensitive substring.
STARTS_WITH ENDS_WITHvalueCase-insensitive.

The four text operators quote regex metacharacters, so a value like a.b*c is matched literally and is safe to pass through from user input.

Note

  • An empty body is valid and returns the first page, newest first.
  • When sorts is omitted the default is created_at DESCENDING.
  • Paging is the same cursor scheme as the list endpoint.

Possible Errors

CodeHTTPDescriptionResolution
INVALID_FILTER400Unknown operator, more than 5 groups, or more than 6 filters in a group.The message says which limit you hit.
INVALID_PROPERTY400A propertyName is not a field on this module.Check GET /properties/{module}.
INVALID_CURSOR400Malformed after.Pass the previous cursor back verbatim.
RATE_LIMITED429The tight search bucket is exhausted.5 per second. Wait Retry-After.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Responses and errors

StatusWhat it means, and what to do about it
200

Matching records.

What the API sends back
{
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "properties": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "lifecycle_stage": "customer"
      },
      "created_at": "2026-11-10T09:30:00.000Z",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "eyJpZCI6IjY2NTBmMWEyIn0"
    }
  }
}
400

INVALID_FILTER, INVALID_PROPERTY, INVALID_CURSOR or VALIDATION_ERROR.

What the API sends back
{
  "status": "error",
  "message": "Max 5 filterGroups allowed.",
  "category": "INVALID_FILTER",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

500

INTERNAL_ERROR - an unexpected failure, or the user who created this token has been deleted. Resolution: revoke the token and issue a new one. Quote correlationId when reporting it.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/search
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/search" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{ "filterGroups": [ { "filters": [ { "propertyName": "email", "operator": "CONTAINS_TOKEN", "value": "@example.com" }, { "propertyName": "created_at", "operator": "GTE", "value": "2026-01-01" } ] } ], "sorts": [ { "propertyName": "created_at", "direction": "DESCENDING" } ], "limit": 25 }'
URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Expected response200what a successful call returns
1{
2 "results": [
3 {
4 "id": "6650f1a2b3c4d5e6f7a8b9c0",
5 "properties": {
6 "first_name": "Ada",
7 "last_name": "Lovelace",
8 "email": "ada@example.com",
9 "lifecycle_stage": "customer"
10 },
11 "created_at": "2026-11-10T09:30:00.000Z",
12 "updated_at": "2026-11-10T09:30:00.000Z",
13 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
14 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
15 "archived": false
16 }
17 ],
18 "paging": {
19 "next": {
20 "after": "eyJpZCI6IjY2NTBmMWEyIn0"
21 }
22 }
23}

Batch Operations

Insert Records (batch)

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Create up to 100 records in a single call. Scope

crm.{module}.write Sample Response (HTTP 207)

{
  "status": "partially_completed",
  "results": [
    { "id": "6650f1a2b3c4d5e6f7a8b9c0", "properties": { "email": "ada@example.com" }, "archived": false }
  ],
  "errors": [
    { "index": 1, "category": "VALIDATION_ERROR", "message": "Property 'email' is required." }
  ]
}

Note

  • The status code is always 207, success or failure. Read status and errors; the code alone tells you nothing.
  • Each input is processed independently, so one bad row does not abort the other ninety-nine.
  • One Idempotency-Key covers the whole batch. A replay returns the cached 207 body unchanged.
  • More than 100 inputs is rejected up front with 400 and nothing is written.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400inputs missing, not an array, or over 100 items.Split into batches of 100. Nothing was written.
MISSING_SCOPE403The key lacks crm.{module}.write.
Per-item errors207Inside errors[], not as an HTTP status.Inspect each entry's index.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
207

Multi-Status. Per-item outcomes - read status and errors.

What the API sends back
{
  "status": "completed",
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "properties": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "created_at": "2026-11-12T06:15:00.000Z",
      "updated_at": "2026-11-12T06:15:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    },
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c1",
      "properties": {
        "first_name": "Grace",
        "last_name": "Hopper",
        "email": "grace@example.com"
      },
      "created_at": "2026-11-12T06:15:00.000Z",
      "updated_at": "2026-11-12T06:15:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "errors": []
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/create
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/create" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "inputs": [ { "properties": { "first_name": "Ada", "email": "ada@example.com" } }, { "properties": { "first_name": "Grace", "email": "grace@example.com" } } ] }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response207what a successful call returns
1{
2 "status": "completed",
3 "results": [
4 {
5 "id": "6650f1a2b3c4d5e6f7a8b9c0",
6 "properties": {
7 "first_name": "Ada",
8 "last_name": "Lovelace",
9 "email": "ada@example.com"
10 },
11 "created_at": "2026-11-12T06:15:00.000Z",
12 "updated_at": "2026-11-12T06:15:00.000Z",
13 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
14 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
15 "archived": false
16 },
17 {
18 "id": "6650f1a2b3c4d5e6f7a8b9c1",
19 "properties": {
20 "first_name": "Grace",
21 "last_name": "Hopper",
22 "email": "grace@example.com"
23 },
24 "created_at": "2026-11-12T06:15:00.000Z",
25 "updated_at": "2026-11-12T06:15:00.000Z",
26 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
27 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
28 "archived": false
29 }
30 ],
31 "errors": []
32}

Get Records (batch)

What you need
  • An API key. It has to be allowed to read records — the crm.{module}.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Fetch up to 100 records by id in one call. A POST that reads. Scope

crm.{module}.read

Rate limit

Uses the tighter search bucket: 5 requests per second. Note

  • Each input may carry its own id_property, so you can mix ids and emails in one call.
  • Records outside the acting user's visibility come back as per-item OBJECT_NOT_FOUND inside errors[], not as a failed call.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400inputs missing or over 100 items.Split into batches of 100.
MISSING_SCOPE403The key lacks crm.{module}.read.
RATE_LIMITED429The search bucket is exhausted.5 per second.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Query parameters

NameTypeDescription
propertiesstringComma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless.
includestringComma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum 5; more, or an unknown name, returns 400 INVALID_PROPERTY. Expanding requires `crm.<target>.read` for EVERY distinct target module across the returned rows; missing any returns 403 MISSING_SCOPE listing the full set needed.

Responses and errors

StatusWhat it means, and what to do about it
207

Multi-Status. One id that could not be read does not stop the others - it lands in errors[] with the index it came from.

What the API sends back
{
  "status": "partially_completed",
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "properties": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com"
      },
      "created_at": "2026-11-10T09:30:00.000Z",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "errors": [
    {
      "index": 1,
      "category": "OBJECT_NOT_FOUND",
      "message": "Record id '000000000000000000000000' not found."
    }
  ]
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/read?properties=email%2Cfirst_name
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/read?properties=email%2Cfirst_name" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{ "inputs": [ { "id": "6650f1a2b3c4d5e6f7a8b9c0" }, { "id": "6650f1a2b3c4d5e6f7a8b9c1" } ] }'
URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless

Comma-separated **lookup field names on this module** to expand inline. The valid set is per-tenant - read it from `GET /properties/{module}`. Maximum

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Expected response207what a successful call returns
1{
2 "status": "partially_completed",
3 "results": [
4 {
5 "id": "6650f1a2b3c4d5e6f7a8b9c0",
6 "properties": {
7 "first_name": "Ada",
8 "last_name": "Lovelace",
9 "email": "ada@example.com"
10 },
11 "created_at": "2026-11-10T09:30:00.000Z",
12 "updated_at": "2026-11-10T09:30:00.000Z",
13 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
14 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
15 "archived": false
16 }
17 ],
18 "errors": [
19 {
20 "index": 1,
21 "category": "OBJECT_NOT_FOUND",
22 "message": "Record id '000000000000000000000000' not found."
23 }
24 ]
25}

Update Records (batch)

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Update up to 100 records in one call. Scope

crm.{module}.write ⚠ A batch of more than one record is a MASS UPDATE

This is the one place where a batch behaves differently from a loop of single calls. A batch with two or more inputs is treated as the API's mass update, and is checked against the acting user's profile before anything is written:

  • Mass Update switched off in their profile - the whole batch is refused with 403, nothing written.
  • A batch that only sets owner fields is the API's Change Owner action, and needs Change Owner instead.
  • A single-item batch is an ordinary update and stays open, exactly as PATCH does.
  • An owner change inside a batch that also sets other fields still needs Change Owner, and surfaces as that item's error rather than refusing the batch.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400inputs missing or over 100 items.Nothing was written.
FORBIDDEN403Multi-item batch and the user lacks Mass Update (or Change Owner for an owner-only batch).Nothing was written. A profile change is needed.
MISSING_SCOPE403The key lacks crm.{module}.write.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
207

Multi-Status.

What the API sends back
{
  "status": "completed",
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "properties": {
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "lifecycle_stage": "customer"
      },
      "created_at": "2026-11-10T09:30:00.000Z",
      "updated_at": "2026-11-12T06:20:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "errors": []
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

Either the scope is missing, or this is a multi-item batch and the acting user's profile does not grant Mass Update (or Change Owner, for an owner-only batch). Nothing was written.

404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/update
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/update" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "inputs": [ { "id": "6650f1a2b3c4d5e6f7a8b9c0", "properties": { "lifecycle_stage": "customer" } }, { "id": "grace@example.com", "id_property": "email", "properties": { "lifecycle_stage": "customer" } } ] }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response207what a successful call returns
1{
2 "status": "completed",
3 "results": [
4 {
5 "id": "6650f1a2b3c4d5e6f7a8b9c0",
6 "properties": {
7 "first_name": "Ada",
8 "last_name": "Lovelace",
9 "email": "ada@example.com",
10 "lifecycle_stage": "customer"
11 },
12 "created_at": "2026-11-10T09:30:00.000Z",
13 "updated_at": "2026-11-12T06:20:00.000Z",
14 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
15 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
16 "archived": false
17 }
18 ],
19 "errors": []
20}

Archive Records (batch)

What you need
  • An API key. It has to be allowed to archive records — the crm.{module}.delete scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Archive (soft-delete) up to 100 records in one call. Scope

crm.{module}.delete ⚠ A batch of more than one record is a MASS DELETE

Same rule as batch update: two or more inputs is the API's mass delete, and the whole batch is refused with 403 before anything is archived when the acting user's profile has Mass Delete switched off. A single-item batch is an ordinary archive and stays open.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400inputs missing or over 100 items.Nothing was archived.
FORBIDDEN403Multi-item batch and Mass Delete is off for this user.Nothing was archived.
MISSING_SCOPE403The key lacks crm.{module}.delete.write is not enough.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
207

Multi-Status. results[] here is not a record - an archived record is not returned, only the id that was archived.

What the API sends back
{
  "status": "completed",
  "results": [
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c0",
      "archived": true
    },
    {
      "id": "6650f1a2b3c4d5e6f7a8b9c1",
      "archived": true
    }
  ],
  "errors": []
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

Scope missing, or Mass Delete is switched off for the acting user. Nothing was archived.

404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/archive
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/batch/archive" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "inputs": [ { "id": "6650f1a2b3c4d5e6f7a8b9c0" }, { "id": "6650f1a2b3c4d5e6f7a8b9c1" } ] }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response207what a successful call returns
1{
2 "status": "completed",
3 "results": [
4 {
5 "id": "6650f1a2b3c4d5e6f7a8b9c0",
6 "archived": true
7 },
8 {
9 "id": "6650f1a2b3c4d5e6f7a8b9c1",
10 "archived": true
11 }
12 ],
13 "errors": []
14}

Associations

Get Associations

What you need
  • An API key. It has to be allowed to read records — the crm.{module}.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.
  • toModule — goes in the URL: API name of the module on the FAR side of the association.

Purpose

List the records of another module that are linked to this one - the data behind the CRM's Related Lists. Scope

Both sides are checked. You need crm.{module}.read and crm.{toModule}.read.

The route middleware only covers the near {module}, because the scope gate substitutes {module} and cannot see {toModule}. The far side is checked inside the controller. Both halves are real - a contacts-only token cannot read a contact's linked deals. Note

  • This is the only list on this API that uses offset paging (page + limit, with a total). Everything else is cursor-paged.

Possible Errors

CodeHTTPDescriptionResolution
MISSING_SCOPE403Missing the read scope for the near side or the far side.Both are required.
MODULE_NOT_AVAILABLE404Either module is unknown or unpublished.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.
toModulerequiredstringAPI name of the module on the FAR side of the association.

Query parameters

NameTypeDescription
limitinteger
default 20
How many links to return. Clamped server-side to 1..100 - a value outside that range is silently clamped, not rejected. Read `paging.total` to see how many there are in all.
pageinteger
default 1
1-based page number. This endpoint is offset-paged, not cursor-paged: ask for `page=2` to get the next `limit` of them, and keep going until `results` comes back empty.

Responses and errors

StatusWhat it means, and what to do about it
200

The linked far-side records.

What the API sends back
{
  "results": [
    {
      "id": "6651aabbccddeeff00112233",
      "properties": {
        "deal_name": "Acme renewal",
        "amount": 12000
      },
      "created_at": "2026-10-01T08:00:00.000Z",
      "updated_at": "2026-11-01T08:00:00.000Z",
      "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
      "archived": false
    }
  ],
  "paging": {
    "total": 1,
    "page": 1,
    "limit": 10
  }
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals?limit=10
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals?limit=10" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable
Paste your key above first.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Additional filtersquery parametersoptional

How many links to return. Clamped server-side to 1..100 - a value outside that range is silently clamped, not rejected. Read `paging.total` to see how

1-based page number. This endpoint is offset-paged, not cursor-paged: ask for `page=2` to get the next `limit` of them, and keep going until `results`

These become the ?name=value part of the URL above. Empty means the parameter is left out altogether, which is not the same as sending it empty.

Expected response200what a successful call returns
1{
2 "results": [
3 {
4 "id": "6651aabbccddeeff00112233",
5 "properties": {
6 "deal_name": "Acme renewal",
7 "amount": 12000
8 },
9 "created_at": "2026-10-01T08:00:00.000Z",
10 "updated_at": "2026-11-01T08:00:00.000Z",
11 "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
12 "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
13 "archived": false
14 }
15 ],
16 "paging": {
17 "total": 1,
18 "page": 1,
19 "limit": 10
20 }
21}

Create Association

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.
  • toModule — goes in the URL: API name of the module on the FAR side of the association.
  • toId — goes in the URL: Id of the record on the far side.

Purpose

Link two records across modules - for example a contact to a deal. Scope

Both sides: crm.{module}.write and crm.{toModule}.write. Sample Response (new link, HTTP 201)

{
  "from": { "module": "contacts", "id": "6650f1a2b3c4d5e6f7a8b9c0" },
  "to":   { "module": "deals",    "id": "6651aabbccddeeff00112233" },
  "id": "6652ffeeddccbbaa99887766",
  "created": true
}

Note

  • Idempotent. If the link already exists, in either direction, the call returns 200 with created: false and id: null - not an error. Safe to retry.
  • No request body is needed; everything is in the path.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400These two records cannot be linked.
FORBIDDEN403Missing the write scope for the far side.Both sides need write.
OBJECT_NOT_FOUND404One of the records does not exist.
MODULE_NOT_AVAILABLE404One of the modules is unknown or unpublished.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.
toModulerequiredstringAPI name of the module on the FAR side of the association.
toIdrequiredstringId of the record on the far side.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

The link already existed, in one direction or the other. Not an error - this endpoint is idempotent.

What the API sends back
{
  "from": {
    "module": "contacts",
    "id": "6650f1a2b3c4d5e6f7a8b9c0"
  },
  "to": {
    "module": "deals",
    "id": "6651aabbccddeeff00112233"
  },
  "id": null,
  "created": false
}
201

The link was created by this call.

What the API sends back
{
  "from": {
    "module": "contacts",
    "id": "6650f1a2b3c4d5e6f7a8b9c0"
  },
  "to": {
    "module": "deals",
    "id": "6651aabbccddeeff00112233"
  },
  "id": "6652ffeeddccbbaa99887766",
  "created": true
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

FORBIDDEN - the acting user may not perform this operation - an owner change without Change Owner, say, or a batch with Mass Update off. Resolution: ask an admin to grant that permission on their profile.

404

OBJECT_NOT_FOUND - no such record, or it is outside your key's visibility. The two look alike on purpose, so existence never leaks. Resolution: check the id, and that your key's user can see it.

429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

PUThttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals/6651aabbccddeeff00112233
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals/6651aabbccddeeff00112233" \
2 -X PUT \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55"
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable
Paste the id of a record you’re happy to change — we don’t fill real records for calls that change data.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

This is real - it changes data in your CRM.
Expected response200what a successful call returns
1{
2 "from": {
3 "module": "contacts",
4 "id": "6650f1a2b3c4d5e6f7a8b9c0"
5 },
6 "to": {
7 "module": "deals",
8 "id": "6651aabbccddeeff00112233"
9 },
10 "id": null,
11 "created": false
12}

Delete Association

What you need
  • An API key. It has to be allowed to create and edit records — the crm.{module}.write scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • id — goes in the URL: The record's unique id. When `id_property` is also sent, this is that property's value instead.
  • toModule — goes in the URL: API name of the module on the FAR side of the association.
  • toId — goes in the URL: Id of the record on the far side.

Purpose

Remove the link between two records. The records themselves are untouched. Scope

Both sides: crm.{module}.write and crm.{toModule}.write. Note

  • Returns 204 with no body on success.
  • A link that does not exist returns 404, not a misleading 204.

Possible Errors

CodeHTTPDescriptionResolution
FORBIDDEN403Missing the write scope for the far side.
OBJECT_NOT_FOUND404No association found between these records.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
idrequiredstringThe record's unique id. When `id_property` is also sent, this is that property's value instead.
toModulerequiredstringAPI name of the module on the FAR side of the association.
toIdrequiredstringId of the record on the far side.

Headers

NameTypeDescription
Idempotency-KeystringMakes a retry safe. Same key + same body replays the cached response with `Idempotency-Replayed: true`; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
204

Unlinked. No body.

401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

FORBIDDEN - the acting user may not perform this operation - an owner change without Change Owner, say, or a batch with Mass Update off. Resolution: ask an admin to grant that permission on their profile.

404

No association found between these records.

What the API sends back
{
  "status": "error",
  "message": "No association found between these records.",
  "category": "OBJECT_NOT_FOUND",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

DELETEhttps://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals/6651aabbccddeeff00112233
1curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals/6651aabbccddeeff00112233" \
2 -X DELETE \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55"
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

URL parameterseditable
Paste the id of a record you’re happy to change — we don’t fill real records for calls that change data.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

This is real - it changes data in your CRM.

Fields Metadata

Get Fields

What you need
  • An API key. It has to be allowed to read field definitions — the crm.schema.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m

Purpose

List the fields a module has in this organization. Call this first: it tells you the exact property names to use in properties, which are required, which are unique and which values a picklist accepts. Scope

crm.schema.read - not a per-module scope. It is granted on the manage_organization feature permission, so one schema-enabled key can read every module's fields. Note

  • Fields are returned in layout order.
  • Fields marked is_public_api_visible = false are filtered out entirely - they will never appear here, and never in a record's properties.
  • options is null for every type except pick_list, picklist, multi_select and dropdown.
  • This is the live source of truth for a tenant. The per-module tables in this document are the seeded defaults, which an admin may have changed.

Possible Errors

CodeHTTPDescriptionResolution
MISSING_SCOPE403The key lacks crm.schema.read.This is an org-level scope, not per module.
MODULE_NOT_AVAILABLE404Unknown, de-activated or unpublished module.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.

Responses and errors

StatusWhat it means, and what to do about it
200

The module's fields, in layout order.

What the API sends back
{
  "results": [
    {
      "name": "email",
      "label": "Email",
      "type": "email",
      "group": "Contact Information",
      "description": null,
      "options": null,
      "required_on_create": false,
      "read_only": false,
      "unique": true,
      "searchable": true,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    },
    {
      "name": "lifecycle_stage",
      "label": "Lifecycle Stage",
      "type": "pick_list",
      "group": "Contact Information",
      "description": null,
      "options": [
        {
          "label": "Lead",
          "value": "lead",
          "display_order": 0,
          "hidden": false
        },
        {
          "label": "Customer",
          "value": "customer",
          "display_order": 1,
          "hidden": false
        }
      ],
      "required_on_create": false,
      "read_only": false,
      "unique": false,
      "searchable": true,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

MODULE_NOT_AVAILABLE - no module matches that name, it is de-activated, or an admin set public_api_enabled = false on it. Resolution: holding the scope does not override publication - ask an admin to publish the module.

What the API sends back
{
  "status": "error",
  "message": "No module matches 'contact'. Call GET /objects for the available modules and use the `slug` from that list.",
  "category": "MODULE_NOT_AVAILABLE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/properties/contacts
1curl "https://app.aiengagecrm.com/cback/api/public/v1/properties/contacts" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Expected response200what a successful call returns
1{
2 "results": [
3 {
4 "name": "email",
5 "label": "Email",
6 "type": "email",
7 "group": "Contact Information",
8 "description": null,
9 "options": null,
10 "required_on_create": false,
11 "read_only": false,
12 "unique": true,
13 "searchable": true,
14 "created_at": "2026-01-15T10:00:00.000Z",
15 "updated_at": "2026-01-15T10:00:00.000Z"
16 },
17 {
18 "name": "lifecycle_stage",
19 "label": "Lifecycle Stage",
20 "type": "pick_list",
21 "group": "Contact Information",
22 "description": null,
23 "options": [
24 {
25 "label": "Lead",
26 "value": "lead",
27 "display_order": 0,
28 "hidden": false
29 },
30 {
31 "label": "Customer",
32 "value": "customer",
33 "display_order": 1,
34 "hidden": false
35 }
36 ],
37 "required_on_create": false,
38 "read_only": false,
39 "unique": false,
40 "searchable": true,
41 "created_at": "2026-01-15T10:00:00.000Z",
42 "updated_at": "2026-01-15T10:00:00.000Z"
43 }
44 ]
45}

Get Field

What you need
  • An API key. It has to be allowed to read field definitions — the crm.schema.read scope. A key without it gets 403 MISSING_SCOPE.
  • module — goes in the URL: API name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug m
  • property — goes in the URL: The field's public name, as returned by `GET /properties/{module}`.

Purpose

Retrieve one field definition by its public name. Scope

crm.schema.read Note

  • Matched on the field's public name, which is what GET /properties/{module} returns as name.
  • Hidden fields are invisible here just as they are in the list.

Possible Errors

CodeHTTPDescriptionResolution
INVALID_PROPERTY404The property does not exist on this module.Note the status: this category is a 404 here, while the same category is a 400 on every other endpoint. This is the actual backend behaviour.
MODULE_NOT_AVAILABLE404Unknown, de-activated or unpublished module.

Path parameters

NameTypeDescription
modulerequiredstringAPI name of the module whose records you want. Resolution tries the exact slug, then a case-insensitive slug match, then the module's display / singular / plural name - prefer the slug. A module that does not exist, is de-activated, or has `public_api_enabled = false` returns 404 MODULE_NOT_AVAILABLE.
propertyrequiredstringThe field's public name, as returned by `GET /properties/{module}`.

Responses and errors

StatusWhat it means, and what to do about it
200

The field definition.

What the API sends back
{
  "name": "email",
  "label": "Email",
  "type": "email",
  "group": "Contact Information",
  "description": null,
  "options": null,
  "required_on_create": false,
  "read_only": false,
  "unique": true,
  "searchable": true,
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-01-15T10:00:00.000Z"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

The property does not exist on this module (INVALID_PROPERTY), or the module itself is unavailable (MODULE_NOT_AVAILABLE). INVALID_PROPERTY is a 404 here and a 400 everywhere else - documented as the backend actually behaves.

What the API sends back
{
  "status": "error",
  "message": "Property 'emial' does not exist on module 'contacts'.",
  "category": "INVALID_PROPERTY",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/properties/contacts/email
1curl "https://app.aiengagecrm.com/cback/api/public/v1/properties/contacts/email" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Expected response200what a successful call returns
1{
2 "name": "email",
3 "label": "Email",
4 "type": "email",
5 "group": "Contact Information",
6 "description": null,
7 "options": null,
8 "required_on_create": false,
9 "read_only": false,
10 "unique": true,
11 "searchable": true,
12 "created_at": "2026-01-15T10:00:00.000Z",
13 "updated_at": "2026-01-15T10:00:00.000Z"
14}

Email

List From Addresses

What you need
  • An API key. It has to be allowed to read your from addresses — the email.from_addresses.read scope. A key without it gets 403 MISSING_SCOPE.

Purpose

The organization email addresses this key is allowed to send from.

Call it before your first send. from_account_id on POST /campaign/send is an opaque id, and this is the only way to discover it - there is no way to guess one, and an address you can see in the CRM UI is not necessarily one an API key may use. Scope

email.from_addresses.read

Org-wide, not per-module. Granted to a key whose creating user has the Email Channel feature permission - the same permission that lets that person compose mail in the CRM. Parameters

None. Note

  • Only organization addresses are listed. A person's own address belongs to that person; an API key is not a person, so personal addresses are never usable here and never appear.
  • trackable: false addresses are listed, not hidden. An address that sends over its own SMTP server gets no delivery, open or click callbacks, so POST /campaign/send refuses it. It is shown with the reason, because an address visible in Settings but absent here looks like a bug.
  • Disabled addresses are omitted entirely.

Possible Errors

CodeHTTPDescriptionResolution
UNAUTHORIZED401Token missing, malformed or revoked.Check the Authorization header.
MISSING_SCOPE403The key lacks email.from_addresses.read.Re-issue the key with that scope ticked.
RATE_LIMITED429Per-window limit hit.Wait Retry-After seconds.

Responses and errors

StatusWhat it means, and what to do about it
200

The addresses this key may send from.

What the API sends back
{
  "status": "success",
  "message": "From addresses retrieved successfully",
  "data": {
    "from_addresses": [
      {
        "id": "6a1d971c81fd34ecd50b8c63",
        "display_name": "Support",
        "email_address": "support@yourcompany.com",
        "reply_to": "support@yourcompany.com",
        "sending_server": "AiTrillion",
        "trackable": true,
        "reason": null
      },
      {
        "id": "6a1d971c81fd34ecd50b8c64",
        "display_name": "Billing",
        "email_address": "billing@yourcompany.com",
        "reply_to": "billing@yourcompany.com",
        "sending_server": "Custom SMTP",
        "trackable": false,
        "reason": "Sends over its own SMTP server, so opens, clicks and delivery cannot be tracked. Not usable with this API."
      }
    ]
  }
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/email/from-addresses
1curl "https://app.aiengagecrm.com/cback/api/public/v1/email/from-addresses" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "From addresses retrieved successfully",
4 "data": {
5 "from_addresses": [
6 {
7 "id": "6a1d971c81fd34ecd50b8c63",
8 "display_name": "Support",
9 "email_address": "support@yourcompany.com",
10 "reply_to": "support@yourcompany.com",
11 "sending_server": "AiTrillion",
12 "trackable": true,
13 "reason": null
14 },
15 {
16 "id": "6a1d971c81fd34ecd50b8c64",
17 "display_name": "Billing",
18 "email_address": "billing@yourcompany.com",
19 "reply_to": "billing@yourcompany.com",
20 "sending_server": "Custom SMTP",
21 "trackable": false,
22 "reason": "Sends over its own SMTP server, so opens, clicks and delivery cannot be tracked. Not usable with this API."
23 }
24 ]
25 }
26}

Send Campaign Message

What you need
  • An API key. It has to be allowed to send email — the email.messages.send scope. A key without it gets 403 MISSING_SCOPE.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Send one email from one of your organization's addresses, and track what happens to it afterwards.

One call sends one message, with its own subject and body. Despite the path this does not run a marketing campaign - there is no audience, template or recipient list. The name points at where the sends are recorded: one per-organization campaign of type api_log, holding one row per message. Call it once per message.

This can deliver real mail. test_mode defaults to true, which validates everything and sends nothing. You must pass "test_mode": false to actually deliver. Pressing Send on this page with the default body is safe.

Scope

email.messages.send

Org-wide. Granted to a key whose creating user has the Email Channel feature permission. Parameters

NameInRequiredDescription
from_account_idbodyyesAn id from GET /email/from-addresses. Must be trackable.
tobodyyesOne recipient address.
subjectbodyyesSubject line.
body_htmlbodyyesHTML body, up to 256,000 bytes.
body_textbodynoPlain-text alternative. Derived from the HTML when omitted.
test_modebodynoDefaults to true - validate and report, send nothing. Pass false to deliver.

Note

  • Where your sends appear. Every send is appended to a single per-organization log in your CRM, shown under Marketing as API Sends. The first call creates it; every call after that adds a row. campaign_id is that log and is the same on every response; recipient_id identifies this one message inside it.
  • Each message is its own. Unlike a marketing campaign, which sends one message to many people, every call here carries its own subject and body and they are stored per message.
  • test_mode defaults to true. Omitting it validates and reports; it does not send. This is deliberate - the field is absent far more often by accident than on purpose.
  • Idempotency-Key is required. A send is irreversible, and a retry after a timeout is the usual way a recipient gets the same message twice. Reuse the key on a retry; use a new one per message.
  • What is tracked, and for how long. Delivery, opens, clicks and bounces are recorded against recipient_id and kept permanently. The message body is kept for 30 days and then removed; the delivery record and all of its tracking survive.
  • An unsubscribe footer is appended to every message sent through this endpoint.
  • No email signature is appended. A CRM signature belongs to the person who wrote it - the Settings screen that holds them says "only you can see and change these" - and an API key is not a person, which is the same reason a personal from-address is never usable here. Put whatever footer you want in body_html; it is yours to compose.
  • Opted-out recipients are refused, including anyone who previously unsubscribed or hard-bounced. This is not overridable.
  • Tighter rate limit than the rest of the API: 5 requests per minute and 500 per day, rather than the general 100 per 10 seconds.
  • Each send counts against both your API call quota and your email allowance.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400A field is missing or malformed.errors names the field.
IDEMPOTENCY_KEY_REQUIRED400No Idempotency-Key header.Send one.
UNAUTHORIZED401Token missing, malformed or revoked.Check the Authorization header.
MISSING_SCOPE403The key lacks email.messages.send.Re-issue the key with that scope.
IDEMPOTENCY_KEY_CONFLICT409Same key reused with a different body.Use a fresh key for a new message.
SEND_NOT_ALLOWED422The from address is unknown, disabled, personal or not trackable; or the recipient has opted out.The message says which. Check GET /email/from-addresses.
RATE_LIMITED4295/minute or 500/day exceeded.Wait Retry-After seconds.
SEND_FAILED502The provider refused the message.The message carries the provider's reason. Safe to retry with the same key.

Headers

NameTypeDescription
Idempotency-KeyrequiredstringREQUIRED on this endpoint. Use a fresh value for each new message, and reuse the SAME value when retrying a request whose outcome you are unsure of - that is what stops a retry delivering the email twice. Same key + same body replays the first response; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

Validated (test_mode true) or sent (test_mode false). Read dispatched to tell which.

What the API sends back
{
  "status": "success",
  "message": "Validated. Nothing was sent or stored.",
  "data": {
    "test_mode": true,
    "dispatched": false,
    "would_send": {
      "from_account_id": "6a1d971c81fd34ecd50b8c63",
      "from": "Support <support@yourcompany.com>",
      "reply_to": "support@yourcompany.com",
      "to": "ada@example.com",
      "subject": "Your receipt",
      "body_bytes": 29,
      "sending_server": "AiTrillion"
    }
  }
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

422

The send was refused before anything left - an unusable from address, or a recipient who has opted out.

What the API sends back
{
  "status": "error",
  "message": "This address sends over its own SMTP server, so delivery, open and click tracking are not available for it. Choose an address whose sending server is the CRM.",
  "category": "SEND_NOT_ALLOWED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

502

The provider refused the message. Nothing was delivered.

What the API sends back
{
  "status": "error",
  "message": "The email could not be sent.",
  "category": "SEND_FAILED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
Everything else is filled in already. You only need to enter your API key and body_html — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/campaign/send
1curl "https://app.aiengagecrm.com/cback/api/public/v1/campaign/send" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "from_account_id": "6a1d971c81fd34ecd50b8c63", "to": "ada@example.com", "subject": "Your receipt", "body_html": "<p>Thanks for your order.</p>", "test_mode": true }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Test mode is on - nothing is really sent.
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Validated. Nothing was sent or stored.",
4 "data": {
5 "test_mode": true,
6 "dispatched": false,
7 "would_send": {
8 "from_account_id": "6a1d971c81fd34ecd50b8c63",
9 "from": "Support <support@yourcompany.com>",
10 "reply_to": "support@yourcompany.com",
11 "to": "ada@example.com",
12 "subject": "Your receipt",
13 "body_bytes": 29,
14 "sending_server": "AiTrillion"
15 }
16 }
17}

Send Email (like SMTP)

What you need
  • An API key. It has to be allowed to send email — the email.transactional.send scope. A key without it gets 403 MISSING_SCOPE.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Use this the way you would use an SMTP server. You give it a from address, a to, a subject and a body, and it sends the mail. If you have ever configured SMTP in an app, you already know this endpoint.

Nothing is written to your CRM - no contact is created, no record is touched, no timeline entry appears. cc and bcc work as they do anywhere else. It is for receipts, one-time codes, invoices and notifications: mail whose job is to arrive rather than to be measured.

This can deliver real mail. test_mode defaults to true, which validates everything and sends nothing. You must pass "test_mode": false to actually deliver.

Despite the path, no contact is involved. POST /email/send is the endpoint that finds or creates one. This endpoint deliberately does not. The two names suggest the opposite of what they do, so check which one you want before wiring it in. Scope

email.transactional.send

Its own scope, separate from email.messages.send. A key that can already send through /campaign/send cannot call this endpoint until this scope is ticked as well - carbon copies reach people your CRM holds no record of, so granting that is a deliberate act rather than something an existing key inherited. Parameters

NameInRequiredDescription
frombodyyes\The address to send from, e.g. billing@yourdomain.com. Must be one your organization has verified.
from_account_idbodyyes\An id from GET /email/from-addresses - the older way of naming the same address.
tobodyyesThe primary recipient.
ccbodynoOne address, or an array of them. Visible to every recipient.
bccbodynoOne address, or an array of them. Hidden from the others.
reply_tobodynoOverrides the from-address's own reply-to.
subjectbodyyesSubject line.
body_textbodyyesPlain-text body, up to 256,000 bytes.
test_modebodynoDefaults to true - validate and report, send nothing. Pass false to deliver.

\* Send exactly one of from or from_account_id. Sending neither, or both, is a VALIDATION_ERROR. from is the one to reach for: it reads like any SMTP configuration and needs no lookup first. from_account_id still works and is unchanged, so nothing already calling this endpoint has to be touched.

from has to be an address your organization has verified - one that appears in GET /email/from-addresses. This is not a rule of ours: mail sent from a domain the sending infrastructure has not authenticated is refused outright or filed as spam, so an unverified address could not be delivered whatever we did with it. Every transactional email API works this way. If the address is not recognised you get a SEND_NOT_ALLOWED naming the ones that would have worked.

body_html is rejected, not ignored. This endpoint sends a text-only message, and accepting an HTML body only to drop it would leave you certain you had sent formatting nobody received. Use POST /campaign/send for an HTML message. Note

  • Opens and clicks are not tracked here. Open tracking works by embedding an invisible pixel in an HTML body, and this endpoint sends no HTML at all - so there is nowhere to put one. Delivery, bounces and failures are tracked exactly as everywhere else; the Opened and Clicked columns simply never fill for these messages. Every response says so in its tracking object, so you do not have to remember it.
  • One credit per call, however many people you reach. A message with one to and three cc costs exactly what one with no copies costs. What limits your reach is the ceiling below, not the price.
  • At most 50 addresses across to, cc and bcc together.
  • Duplicates are removed, not refused. An address already in to is dropped from cc and bcc; one in both cc and bcc keeps its cc place. The response lists cc and bcc exactly as sent, so you can see what was actually done.
  • Every recipient is checked, not just to. Anyone who has unsubscribed or hard-bounced is refused from the cc line too - a bounced address costs your sending reputation wherever it sits.
  • No unsubscribe footer is appended. This is not marketing mail, and an unsubscribe link on an invoice teaches people to opt out of their own receipts. The opt-out check above still applies.
  • No contact is created, matched or modified.
  • No email signature is appended. A CRM signature belongs to the person who wrote it, and a key is not a person. Put whatever footer you want in body_text.
  • 15 requests per hour, per key - the tightest limit in this API, because one call can reach fifty inboxes.
  • Idempotency-Key is required. A send is irreversible, and a retry after a timeout is the usual way someone gets the same message twice. Reuse the key on a retry; use a new one per message.
  • Where your sends appear. Each one is appended to the same per-organization log as /campaign/send, and listed in the CRM under Marketing → API Email with its delivery status. campaign_id is that log; recipient_id identifies this message inside it.
  • Bodies are removed after 30 days. The row, its subject and its whole delivery history are kept indefinitely - only the message text is cleared, and the screen says so rather than showing you an empty frame. Counts are never reduced.
  • Each send counts against both your API call quota and your email allowance.

Possible Errors

CodeHTTPDescriptionResolution
VALIDATION_ERROR400A field is missing or malformed, or body_html was sent.errors names the field.
IDEMPOTENCY_KEY_REQUIRED400No Idempotency-Key header.Send one.
UNAUTHORIZED401Token missing, malformed or revoked.Check the Authorization header.
MISSING_SCOPE403The key lacks email.transactional.send.Re-issue the key with that scope ticked. Holding email.messages.send is not enough.
IDEMPOTENCY_KEY_CONFLICT409Same key reused with a different body.Use a fresh key for a new message.
SEND_NOT_ALLOWED422A from the organization has not verified; a from address that is personal, disabled or sends over its own SMTP; a recipient or copied address that has opted out; or more than 50 addresses.The message says which, and an unverified from is answered with the addresses that would work.
RATE_LIMITED42915/hour or 360/day exceeded.Wait Retry-After seconds.
SEND_FAILED502The provider refused the message.The message carries the reason. Safe to retry with the same key.

Headers

NameTypeDescription
Idempotency-KeyrequiredstringREQUIRED on this endpoint. Use a fresh value for each new message, and reuse the SAME value when retrying a request whose outcome you are unsure of - that is what stops a retry delivering the email twice. Same key + same body replays the first response; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

Validated (test_mode true) or sent (test_mode false). Read dispatched to tell which.

What the API sends back
{
  "status": "success",
  "message": "Validated. Nothing was sent or stored.",
  "data": {
    "test_mode": true,
    "dispatched": false,
    "would_send": {
      "from_account_id": "6a1d971c81fd34ecd50b8c63",
      "from": "Accounts <accounts@yourcompany.com>",
      "reply_to": "accounts@yourcompany.com",
      "to": "ada@example.com",
      "cc": [
        "finance@example.com"
      ],
      "bcc": [],
      "recipient_count": 2,
      "subject": "Your invoice INV-1042",
      "body_bytes": 96,
      "sending_server": "AiTrillion",
      "tracking": {
        "opens": false,
        "clicks": false,
        "delivery": true
      },
      "credits": 1
    }
  }
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

422

Refused before anything left - an unusable from address, a recipient or copied address that may not be mailed, or too many addresses on one message.

What the API sends back
{
  "status": "error",
  "message": "finance@example.com cannot be copied on this message: this address hard bounced.",
  "category": "SEND_NOT_ALLOWED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

502

The provider refused the message. Nothing was delivered.

What the API sends back
{
  "status": "error",
  "message": "The email could not be sent.",
  "category": "SEND_FAILED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/contact/email/send
1curl "https://app.aiengagecrm.com/cback/api/public/v1/contact/email/send" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "from": "billing@yourdomain.com", "to": "ada@example.com", "cc": [ "finance@example.com" ], "subject": "Your invoice INV-1042", "body_text": "Hi Ada,\n\nYour invoice INV-1042 is ready. The total is 4,200 INR.\n\nThanks,\nAccounts", "test_mode": true }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Test mode is on - nothing is really sent.
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Validated. Nothing was sent or stored.",
4 "data": {
5 "test_mode": true,
6 "dispatched": false,
7 "would_send": {
8 "from_account_id": "6a1d971c81fd34ecd50b8c63",
9 "from": "Accounts <accounts@yourcompany.com>",
10 "reply_to": "accounts@yourcompany.com",
11 "to": "ada@example.com",
12 "cc": [
13 "finance@example.com"
14 ],
15 "bcc": [],
16 "recipient_count": 2,
17 "subject": "Your invoice INV-1042",
18 "body_bytes": 96,
19 "sending_server": "AiTrillion",
20 "tracking": {
21 "opens": false,
22 "clicks": false,
23 "delivery": true
24 },
25 "credits": 1
26 }
27 }
28}

Send Email to a Contact

What you need
  • An API key. It has to be allowed to send email — the email.messages.send scope. A key without it gets 403 MISSING_SCOPE.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Send one email to a PERSON, and leave it on their record.

This is the difference from POST /campaign/send, and the only reason both exist. That endpoint takes an address, delivers, and logs the result; nothing is attached to anybody, so opening the person in the CRM shows no sign of it. This one finds the contact behind the address — creating it when there is none — and writes the message to their timeline, exactly where a mail typed into the CRM would appear. The reply that comes back tomorrow has somewhere to land.

Reach for /campaign/send when you are sending to an address and only want it tracked. Reach for this when the recipient is someone your CRM should know.

This can deliver real mail. test_mode defaults to true, which validates everything, reports what it would do, and changes nothing — no message, and no contact. You must pass "test_mode": false to actually send. Pressing Send on this page with the default body is safe.

Scope

email.messages.send

The same scope /campaign/send uses: both send one email from an organization address, so a key granted that may do either.

The contact

The address in to is looked up, and what happens next comes back in contact_action:

contact_actionWhat happened
matchedThey were already in the CRM, and nothing about them changed.
updatedThey were already there, and the fields you sent in contact were written. Fields you did not send are untouched.
createdThey were not there, so a contact was made.
unavailableThere was nothing to attach to — the organization has no Contacts module. The mail is still sent.

When several contacts share the address, the oldest is used. That is not arbitrary: every part of this CRM that resolves a person from an address does the same, so a send, a conversation and a ticket all land on one record rather than scattering across duplicates.

Creating one needs a name, and a send has none

first_name is required on the Contacts module, so a contact created from nothing but an address would be refused. The local part is used instead — ada@example.com becomes ada. Send a contact object to do better; anything you put there wins over the derived value. Parameters

NameInRequiredDescription
from_account_idbodyyesAn organization address, from GET /email/from-addresses.
tobodyyesThe recipient. This is also what identifies the contact.
subjectbodyyesSubject line. Merge fields resolve against the contact.
body_htmlbodyyesHTML body. Merge fields resolve here too.
body_textbodynoPlain-text alternative. Derived from the HTML when omitted.
contactbodynoContact fields to create the record with, or update it with.
test_modebodynoDefaults to true — validate and report, change nothing. Pass false to send.

Merge fields

{{contacts.first_name}} in the subject or body is replaced with that contact's value before sending. The older ${Contacts.First Name} form works too. A field that cannot be resolved is left as it is rather than failing the send.

Headers

NameTypeDescription
Idempotency-KeyrequiredstringREQUIRED on this endpoint. Use a fresh value for each new message, and reuse the SAME value when retrying a request whose outcome you are unsure of - that is what stops a retry delivering the email twice. Same key + same body replays the first response; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

Validated (test_mode true) or sent (test_mode false). Read dispatched to tell which.

What the API sends back
{
  "status": "success",
  "message": "Validated. Nothing was sent, and no contact was created or changed.",
  "data": {
    "test_mode": true,
    "dispatched": false,
    "would_send": {
      "from_account_id": "6a1d971c81fd34ecd50b8c63",
      "from": "Support <support@yourcompany.com>",
      "to": "ada@example.com",
      "subject": "Your order shipped",
      "body_bytes": 29,
      "sending_server": "AiTrillion"
    },
    "contact": {
      "contact_id": null,
      "action": "would_create"
    }
  }
}
400

VALIDATION_ERROR or INVALID_PROPERTY - the body or a query parameter failed validation. Resolution: errors[] names the property at fault - fix that one.

What the API sends back
{
  "status": "error",
  "message": "Request body failed validation.",
  "category": "VALIDATION_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [
    {
      "property": "properties",
      "code": "INVALID_VALUE",
      "message": "The properties field is required."
    }
  ],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

422

A gate refused the send and nothing was delivered: an unknown or disabled from-address, a personal one, an address that sends over its own SMTP (tracking would never report anything), an inactive contact, or a recipient who has opted out.

What the API sends back
{
  "status": "error",
  "message": "An API key may only send from an Organization Email address.",
  "category": "SEND_NOT_ALLOWED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

502

The provider refused the message. Nothing was delivered.

What the API sends back
{
  "status": "error",
  "message": "The email could not be sent.",
  "category": "SEND_FAILED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
Everything else is filled in already. You only need to enter your API key and body_html — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/email/send
1curl "https://app.aiengagecrm.com/cback/api/public/v1/email/send" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "from_account_id": "6a1d971c81fd34ecd50b8c63", "to": "ada@example.com", "subject": "Hi {{contacts.first_name}}, your order shipped", "body_html": "<p>It is on its way.</p>", "contact": { "first_name": "Ada", "last_name": "Lovelace" }, "test_mode": true }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Test mode is on - nothing is really sent.
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Validated. Nothing was sent, and no contact was created or changed.",
4 "data": {
5 "test_mode": true,
6 "dispatched": false,
7 "would_send": {
8 "from_account_id": "6a1d971c81fd34ecd50b8c63",
9 "from": "Support <support@yourcompany.com>",
10 "to": "ada@example.com",
11 "subject": "Your order shipped",
12 "body_bytes": 29,
13 "sending_server": "AiTrillion"
14 },
15 "contact": {
16 "contact_id": null,
17 "action": "would_create"
18 }
19 }
20}

WhatsApp

List Templates

What you need
  • An API key. It has to be allowed to read WhatsApp templates — the whatsapp.templates.read scope. A key without it gets 403 MISSING_SCOPE.

Purpose

Every WhatsApp template your organization has had approved, and the placeholders each one expects. Call this first: sending needs a template id, and the ids are opaque.

Only approved templates come back. Draft, pending, rejected and paused ones are invisible to an API key, so a template you can see in the dashboard but not here is a status problem, not a key problem. Scope

whatsapp.templates.read

Org-wide. Granted to a key whose creating user has the WhatsApp feature permission.

Reading placeholders

A template's placeholders arrive in one of two shapes, depending on how the template was built:

ShapeLooks likeMeans
Object{"1": "first_name", "2": "order_number"}position → the field that fills it
Array["first_name", "order_number"]the same, already in order

Either way it is the ORDER that matters. When you send you pass an array of values in that order - never the field names back. Parameters

None.

Responses and errors

StatusWhat it means, and what to do about it
200

Every approved template, ordered by name.

What the API sends back
{
  "status": "success",
  "message": "Templates retrieved",
  "data": [
    {
      "id": "6ae06ed29fe2c3647a017c74",
      "name": "order_shipped",
      "provider_name": "order_shipped_17930933304259302",
      "category": "marketing",
      "language": "en",
      "template_type": "standard",
      "supports_send": true,
      "body": "Hi {{1}}, order {{2}} is on its way.",
      "placeholders": {
        "1": "first_name",
        "2": "order_number"
      },
      "sender_id": "66f0a1b2c3d4e5f6a7b8c9d0"
    }
  ]
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates
1curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Templates retrieved",
4 "data": [
5 {
6 "id": "6ae06ed29fe2c3647a017c74",
7 "name": "order_shipped",
8 "provider_name": "order_shipped_17930933304259302",
9 "category": "marketing",
10 "language": "en",
11 "template_type": "standard",
12 "supports_send": true,
13 "body": "Hi {{1}}, order {{2}} is on its way.",
14 "placeholders": {
15 "1": "first_name",
16 "2": "order_number"
17 },
18 "sender_id": "66f0a1b2c3d4e5f6a7b8c9d0"
19 }
20 ]
21}

Get Template

What you need
  • An API key. It has to be allowed to read WhatsApp templates — the whatsapp.templates.read scope. A key without it gets 403 MISSING_SCOPE.
  • id — goes in the URL: The template's `id`, as List Templates returns it.

Purpose

One approved template by id, in exactly the shape the list returns - so one decoder handles both. Scope

whatsapp.templates.read

A 404 here means one of two things

Either no template has that id in your organization, or it has one and it is not approved. The API deliberately does not tell you which: a key cannot be used to probe which ids exist. Parameters

NameInRequiredDescription
idpathyesThe template id, from List Templates.

Path parameters

NameTypeDescription
idrequiredstringThe template's `id`, as List Templates returns it.

Responses and errors

StatusWhat it means, and what to do about it
200

The template.

What the API sends back
{
  "status": "success",
  "message": "Template retrieved",
  "data": {
    "id": "6ae06ed29fe2c3647a017c74",
    "name": "order_shipped",
    "provider_name": "order_shipped_17930933304259302",
    "category": "marketing",
    "language": "en",
    "template_type": "standard",
    "supports_send": true,
    "body": "Hi {{1}}, order {{2}} is on its way.",
    "placeholders": {
      "1": "first_name",
      "2": "order_number"
    },
    "sender_id": "66f0a1b2c3d4e5f6a7b8c9d0"
  }
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

No approved template with that id in this organization.

What the API sends back
{
  "status": "error",
  "message": "Template not found or not approved.",
  "category": "TEMPLATE_NOT_FOUND",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

Everything else is filled in already. You only need to enter your API key — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

GEThttps://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates/6ae06ed29fe2c3647a017c74
1curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates/6ae06ed29fe2c3647a017c74" \
2 -H "Authorization: Bearer YOUR_API_TOKEN"
URL parameterseditable
Paste your key above first.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Template retrieved",
4 "data": {
5 "id": "6ae06ed29fe2c3647a017c74",
6 "name": "order_shipped",
7 "provider_name": "order_shipped_17930933304259302",
8 "category": "marketing",
9 "language": "en",
10 "template_type": "standard",
11 "supports_send": true,
12 "body": "Hi {{1}}, order {{2}} is on its way.",
13 "placeholders": {
14 "1": "first_name",
15 "2": "order_number"
16 },
17 "sender_id": "66f0a1b2c3d4e5f6a7b8c9d0"
18 }
19}

Send Template

What you need
  • An API key. It has to be allowed to send WhatsApp templates — the whatsapp.templates.send scope. A key without it gets 403 MISSING_SCOPE.
  • id — goes in the URL: The template to send, as List Templates returns it.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Send one approved template to one phone number.

This delivers real messages and spends WhatsApp credits. There is no test_mode on this endpoint, and no dry run. Every accepted call reaches the recipient.

Scope

whatsapp.templates.send

Org-wide. Granted to a key whose creating user has the WhatsApp feature permission.

Retries are NOT protected

Unlike POST /campaign/send, this endpoint does not accept an Idempotency-Key, so a retry after a timeout sends the message a second time and spends a second credit. If you cannot tell whether a call arrived, check the WhatsApp send log before trying again rather than retrying blind.

The phone number

Everything that is not a digit is stripped, so +91 98765 43210 and 919876543210 are the same number. What remains must be at least 10 digits, and it must carry the country code - there is no default country.

Placeholders

placeholders is an array of the values that fill the template's {{1}}, {{2}}, … in order. Read that order from placeholders on the template itself (List Templates explains both shapes it takes). A template with a media or text header also accepts header_placeholder.

Which number it is sent from

A template is registered under one WhatsApp sender, and that sender is authoritative: when the template carries a sender_id, omit sender_id here or pass the same one. Passing a different one is refused with SENDER_MISMATCH rather than sent and rejected by the provider. Only for an older template with no bound sender does sender_id choose between the senders of a multi-sender organization, and omitting it there falls back to the organization default.

Before it sends, four gates run in order

  1. the opt-in / unsubscribe rules for this template and sender
  2. a price estimate for this destination
  3. your WhatsApp credit balance
  4. the deduction, and only then the provider call

A failure at any gate returns before the message leaves, and nothing is charged. Parameters

NameInRequiredDescription
idpathyesThe template to send, from List Templates.
phonebodyyesRecipient with country code. Non-digits are stripped; 10 digits must remain.
template_languagebodynoLanguage code. Defaults to the template's own.
placeholdersbodynoThe values for {{1}}, {{2}}, … in order.
header_placeholderbodynoThe value for a media or text header, when the template has one.
sender_idbodynoOnly for a template bound to no sender.

Path parameters

NameTypeDescription
idrequiredstringThe template to send, as List Templates returns it.

Responses and errors

StatusWhat it means, and what to do about it
200

Accepted by the provider and on its way.

What the API sends back
{
  "status": "success",
  "message": "Message sent",
  "data": {
    "id": "3f8a21b0-7c4d-4e2a-9b11-5d6e7f8a9b0c",
    "sent_credits": 0.0825
  }
}
400

The payload is invalid (VALIDATION_ERROR), or the phone number has fewer than 10 digits once stripped (INVALID_PHONE).

What the API sends back
{
  "status": "error",
  "message": "Invalid phone number.",
  "category": "INVALID_PHONE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
402

Not enough WhatsApp credits. Nothing was sent or charged.

What the API sends back
{
  "status": "error",
  "message": "Insufficient WhatsApp credits.",
  "category": "INSUFFICIENT_CREDITS",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

No approved template with that id in this organization.

What the API sends back
{
  "status": "error",
  "message": "Template not found or not approved.",
  "category": "TEMPLATE_NOT_FOUND",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
422

A gate refused the send, and nothing was charged. SENDER_MISMATCH - sender_id contradicts the template's bound sender. SENDER_REQUIRED - the organization has several senders and the template is bound to none, so one must be named. PROVIDER_NOT_CONFIGURED - no usable WhatsApp sender. OPT_IN_REQUIRED - this recipient has not opted in, or has unsubscribed. RATE_LOOKUP_FAILED - the price for this destination could not be determined.

What the API sends back
{
  "status": "error",
  "message": "This recipient has not opted in to receive messages.",
  "category": "OPT_IN_REQUIRED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

500

The send failed unexpectedly. Quote correlationId — EXCEPT when the message reads Token creator user no longer exists, which you can fix yourself: the user who created this key has been deleted, and a key needs an author to create or update a contact with. Revoke the key and generate a new one.

What the API sends back
{
  "status": "error",
  "message": "Could not send the message.",
  "category": "INTERNAL_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
502

The provider refused the message. Nothing was delivered.

What the API sends back
{
  "status": "error",
  "message": "The message could not be sent.",
  "category": "PROVIDER_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
Everything else is filled in already. You only need to enter your API key and phone — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates/6ae06ed29fe2c3647a017c74/send
1curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates/6ae06ed29fe2c3647a017c74/send" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Content-Type: application/json" \
5 -d '{ "phone": "91XXXXXXXXXX", "template_language": "en", "placeholders": [ "Ada", "A-1043" ] }'
URL parameterseditable
Paste your key above first.

These fill the braces in the URL above. They start as this document's examples, which are illustrations - a real id from your own CRM is what makes Send work.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

This is real - it changes data in your CRM.
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Message sent",
4 "data": {
5 "id": "3f8a21b0-7c4d-4e2a-9b11-5d6e7f8a9b0c",
6 "sent_credits": 0.0825
7 }
8}

Send WhatsApp to a Contact

What you need
  • An API key. It has to be allowed to send WhatsApp templates — the whatsapp.templates.send scope. A key without it gets 403 MISSING_SCOPE.
  • Your data, as JSON — the Enter your data box is pre-filled with a working example you can edit.

Purpose

Send an approved template to a PERSON, and leave it on their record.

The message is the same one POST /whatsapp/templates/{id}/send delivers. What differs is what happens around it: the number is looked up in your CRM, a contact is created when it is new, and the send is written to that contact's timeline. Sending to a number the CRM has never seen used to leave nothing behind — the message went, and the person did not exist.

Reach for the template endpoint when you are messaging a number. Reach for this when the recipient is someone your CRM should know.

This delivers real messages and spends WhatsApp credits. There is no test_mode on either WhatsApp endpoint, and no dry run. Every accepted call reaches the recipient.

Scope

whatsapp.templates.send

The same scope the template endpoint uses: both send one approved template, so a key granted that may do either.

An Idempotency-Key is required here

Unlike the older template route, this endpoint refuses a request without one. A WhatsApp send cannot be recalled and spends a credit, so a retry after a timeout would deliver twice and charge twice. Use a fresh value per message and the SAME value when retrying one whose outcome you are unsure of.

The contact

The number is matched after non-digits are stripped, so +91 98765 43210 and 919876543210 are the same person. What happened comes back in contact_action:

contact_actionWhat happened
matchedThey were already in the CRM, and nothing about them changed.
updatedThey were already there, and the fields you sent in contact were written. Fields you did not send are untouched.
createdThey were not there, so a contact was made.
unavailableThere was nothing to attach to — the organization has no Contacts module. The message is still sent.

When several contacts share the number, the oldest is used, the same rule the rest of the CRM follows when it resolves a person.

The contact is resolved BEFORE the message is sent

So a send that is then refused — no credits, not opted in — still leaves the contact behind. That is intended: the person is real, you tried to reach them, and your next attempt finds the same record instead of making a second one.

Creating one needs a name, and a number is not one

first_name is required on the Contacts module, so the number stands in for it: a new contact is called 919876543210 until someone renames it. Send a contact object to do better; anything you put there wins.

The template fills itself in from the contact

A template records which contact field belongs in each numbered slot. GET /whatsapp/templates returns that as placeholders:

"placeholders": { "1": "first_name", "2": "order_number" }

Because this endpoint is given a person rather than a number, it can read those fields off the contact itself. Send no placeholders and the slots fill themselves.

-d '{"phone":"91XXXXXXXXXX","template_id":"6ae06ed29fe2c3647a017c74"}'

Anything you DO send wins, slot by slot. Pass a value and it is used; leave one empty and the contact answers for it. So you can supply the one field the CRM cannot know and let it fill the rest:

-d '{"phone":"91XXXXXXXXXX","template_id":"…","placeholders":["","A-1043"]}'

The response says which slots it answered for, in placeholders_from_contact. A slot the contact has no value for is sent empty rather than as the literal {{2}} — a blank in a message is survivable, a stray token is not.

Field names are matched without regard to case, a multi-select field is joined with commas, and a mapping written as a full merge tag (contacts.first_name) resolves through the same engine a campaign uses. This is the behaviour the CRM's own inbox already applies when it prefills a template, so a send from here and a send from there put the same value in the same slot.

Only this endpoint fills from a contact. POST /whatsapp/templates/{id}/send is given a phone number and nothing else, so it has no contact to read and sends exactly the placeholders you pass it.

Parameters

NameInRequiredDescription
phonebodyyesRecipient with country code. Non-digits are stripped; 10 digits must remain.
template_idbodyyesThe template to send, from GET /whatsapp/templates.
template_languagebodynoLanguage code. Defaults to the template's own.
placeholdersbodynoThe values for {{1}}, {{2}}, … in order. Omit it and they are taken from the contact; any value you do send wins for that slot.
header_placeholderbodynoThe value for a media or text header, when the template has one.
sender_idbodynoOnly for a template bound to no sender.
contactbodynoContact fields to create the record with, or update it with.

Headers

NameTypeDescription
Idempotency-KeyrequiredstringREQUIRED on this endpoint. Use a fresh value for each new message, and reuse the SAME value when retrying a request whose outcome you are unsure of - that is what stops a retry delivering the email twice. Same key + same body replays the first response; same key + different body returns 409 IDEMPOTENCY_KEY_CONFLICT. Cached 24 hours.

Responses and errors

StatusWhat it means, and what to do about it
200

Accepted by the provider and on its way.

What the API sends back
{
  "status": "success",
  "message": "Message sent",
  "data": {
    "id": "3f8a21b0-7c4d-4e2a-9b11-5d6e7f8a9b0c",
    "sent_credits": 0.0825,
    "contact_id": "6650f1a2b3c4d5e6f7a8b9c0",
    "contact_action": "created"
  }
}
400

The payload is invalid (VALIDATION_ERROR), or the number has fewer than 10 digits once stripped (INVALID_PHONE). Both are refused before the contact step, so nothing is created.

What the API sends back
{
  "status": "error",
  "message": "Invalid phone number.",
  "category": "INVALID_PHONE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
401

UNAUTHORIZED - token missing, malformed, unknown, revoked or expired. Resolution: paste a current key. message varies with the cause, category does not - branch on category.

What the API sends back
{
  "status": "error",
  "message": "Missing or malformed Authorization header.",
  "category": "UNAUTHORIZED",
  "correlationId": "01M722ZY936QDSH0XGVVR3S97F",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
402

Not enough WhatsApp credits. Nothing was sent or charged — but the contact was already resolved, so it remains.

What the API sends back
{
  "status": "error",
  "message": "Insufficient WhatsApp credits.",
  "category": "INSUFFICIENT_CREDITS",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
403

MISSING_SCOPE - the token does not hold this route's scope. Resolution: the message names the scope; re-issue the key with it.

What the API sends back
{
  "status": "error",
  "message": "Token is missing the required scope: crm.contacts.write.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
404

No approved template with that template_id in this organization. Refused before the contact step.

What the API sends back
{
  "status": "error",
  "message": "Template not found or not approved.",
  "category": "TEMPLATE_NOT_FOUND",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
409

CONFLICT - an id_property or matching_property on a non-unique field matched more than one record, or an idempotency key was reused with a different body. Resolution: use a field marked unique.

422

A gate refused the send, and nothing was charged. The same set the template endpoint returns: SENDER_MISMATCH, SENDER_REQUIRED, PROVIDER_NOT_CONFIGURED, OPT_IN_REQUIRED, RATE_LOOKUP_FAILED.

What the API sends back
{
  "status": "error",
  "message": "This recipient has not opted in to receive messages.",
  "category": "OPT_IN_REQUIRED",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
429

RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait Retry-After seconds.

500

The send failed unexpectedly. Quote correlationId — EXCEPT when the message reads Token creator user no longer exists, which you can fix yourself: the user who created this key has been deleted, and a key needs an author to create or update a contact with. Revoke the key and generate a new one.

What the API sends back
{
  "status": "error",
  "message": "Could not send the message.",
  "category": "INTERNAL_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
502

The provider refused the message. Nothing was delivered.

What the API sends back
{
  "status": "error",
  "message": "The message could not be sent.",
  "category": "PROVIDER_ERROR",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}
Everything else is filled in already. You only need to enter your API key and phone — then press Send.
API keyAuthorization: Bearer
live data
https://app.aiengagecrm.com/cback/api/public/v1

Production - the live AiEngage CRM API

Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.

POSThttps://app.aiengagecrm.com/cback/api/public/v1/whatsapp/send
1curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/send" \
2 -X POST \
3 -H "Authorization: Bearer YOUR_API_TOKEN" \
4 -H "Idempotency-Key: 8f14e45f-ea2b-4f8a-9c21-7d3b6a1e0c55" \
5 -H "Content-Type: application/json" \
6 -d '{ "phone": "91XXXXXXXXXX", "template_id": "6ae06ed29fe2c3647a017c74", "placeholders": [ "Ada", "A-1043" ], "contact": { "first_name": "Ada" } }'
Idempotency-Keynew each send

Reuse the same value to retry a send you are unsure of; a new one means a new message.

Enter your datarequest bodyeditable

Edit this and the samples above update with it, so Copy gives you the request you actually sent.

Send one, without the JSON

Paste your key and press Load templates. WhatsApp only sends approved templates — there is no free text.

This really sends. There is no test mode on WhatsApp.
This is real - it changes data in your CRM.
Expected response200what a successful call returns
1{
2 "status": "success",
3 "message": "Message sent",
4 "data": {
5 "id": "3f8a21b0-7c4d-4e2a-9b11-5d6e7f8a9b0c",
6 "sent_credits": 0.0825,
7 "contact_id": "6650f1a2b3c4d5e6f7a8b9c0",
8 "contact_action": "created"
9 }
10}

Test console

Every endpoint on this page has a Send button, but it only ever sends the request this document describes. The console takes the opposite approach: paste any curl command - yours, a colleague’s, one from a ticket - and it runs exactly that, against your own CRM, and shows you what came back.

It opens from Console in the header, from the button in the corner, or from any row below. Your key and whatever you type stay in this browser.

Step 1 — your API key

Create one in the CRM under Settings → API keys. Paste it here and every sample on this page, and the console, will use it.

Step 2 — pick something to run

Each of these opens the console with a working command already in it. Read it, change what you like, press Send.

MethodWhat it does
GETGet Records
POSTSearch Records
POSTInsert Records (batch)
GETGet Associations
GETGet Fields
GETList From Addresses
GETList Templates

Step 3 — or paste your own

Open the console and paste any command. It reads the same things a shell does, so a sample copied straight out of a terminal works unchanged: quotes, -H headers, -d bodies, and lines continued with a trailing backslash.

It sends for real. A GET only reads, but a POST, PUT, PATCH or DELETE changes your data. The console says which it is about to do before you press Send. The two email send endpoints default to test_mode, so pressing Send validates and reports rather than delivering — but the two WhatsApp ones have no test_mode and no dry run, and every accepted call reaches the recipient and spends credits.

Reference

Authentication

Four token kinds are accepted, and every authentication failure in every mode returns an identical 401 UNAUTHORIZED body, so a caller cannot probe which one it nearly matched.

ModeTokenWho uses it
1cak_live_<32 chars>External integrations. Settings → API Keys.
2Purpose-scoped user JWTThe in-app CRM agent.
3Dashboard login JWTA signed-in person using their own session.
4cak_oauth_<...>A remote MCP client that completed the OAuth flow.

If the user who created a token is deleted, the token stops working and returns 500 INTERNAL_ERROR telling you to revoke and re-issue. cak_test_ is reserved and is rejected.

Scopes

A key carries a list of scopes, and they mix freely. One key can read records, send email and send WhatsApp; there is no per-channel key. There are three families:

FamilyCovers
crm.<module>.<action>records, schema, campaigns, reports
email.<area>.<action>from addresses, sending
whatsapp.<area>.<action>templates, sending

The crm.* family is substituted per request - calling /objects/contacts checks crm.contacts.read, not a literal crm.{module}.read.

ScopeGranted when the token's user has
crm.{module}.readview permission on that module
crm.{module}.writecreate AND edit permission
crm.{module}.deletedelete permission
crm.schema.readthe manage_organization feature permission

Note that write needs both create and edit - a user who can create but not edit cannot be granted it.

Which modules you can reach

Module.public_api_enabled decides whether third parties may address a module. It is default-ON: a module is reachable unless an admin explicitly turned it off.

A module turned off that way returns 404 MODULE_NOT_AVAILABLE even when your token holds a scope for it - the scope grant does not override publication. A de-activated module is unavailable to everyone.

This publication gate applies to cak_live_* keys only. The other three token modes are not third parties, so it is relaxed for them.

The record envelope

Every record read or written uses the same envelope. Metadata at the top level, everything the module defines under properties.

properties is always an object - {} when empty, never []. Timestamps are UTC, YYYY-MM-DDTHH:MM:SS.sssZ.

{
  "id": "6650f1a2b3c4d5e6f7a8b9c0",
  "properties": { "first_name": "Ada", "email": "ada@example.com" },
  "created_at": "2026-11-10T09:30:00.000Z",
  "updated_at": "2026-11-10T09:30:00.000Z",
  "created_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "updated_by": "6640a1b2c3d4e5f6a7b8c9d0",
  "archived": false
}

Errors

Every error shares one envelope:

Branch on category, never on message. The wording can change; the category will not. Log correlationId - it is the one thing that lets anyone trace your exact request in the backend.

documentation_url points at aitrillion.com, not aiengagecrm.com. That is not a typo here: the backend emits that host on every error, so this document reproduces what you will actually receive.

CategoryHTTPDescriptionResolution
UNAUTHORIZED401Token missing, malformed, unknown, revoked or expired.Check the Authorization: Bearer header.
MISSING_SCOPE403Authenticated, but the token lacks this route's scope.The message names the scope. Re-issue the key with it.
FORBIDDEN403Scoped, but the acting user may not do this - an owner change without Change Owner, or a mass update with that tool off.A permissions change, not a token change.
VALIDATION_ERROR400Body or query parameter failed validation.errors[] names the property. Also returned for a batch over 100 items, and for upsert without matching_property. Nothing was written.
INVALID_PROPERTY400A property name does not exist on this module, or more than 5 include values.Call GET /properties/{module} for the real names.
INVALID_FILTER400Unknown operator, more than 5 filter groups, or more than 6 filters in a group.Check the operator table in the search guide.
INVALID_CURSOR400The after cursor is malformed.Pass paging.next.after back verbatim.
OBJECT_NOT_FOUND404No such record, or it is outside the acting user's visibility.The two are deliberately indistinguishable so existence never leaks.
MODULE_NOT_AVAILABLE404No module matches that name, it is de-activated, or unpublished.Holding the scope does not override publication.
ENDPOINT_NOT_FOUND404The version is valid, but nothing serves that method and path.Check the path against this document. A route that works on one host and 404s on another is not deployed there yet.
VERSION_NOT_AVAILABLE404The first path segment is not a version this host serves.available_versions in the body lists the ones it does.
CONFLICT409An id_property or matching_property on a non-unique field matched more than one record.Use a field marked unique.
IDEMPOTENCY_KEY_CONFLICT409The same key was reused with a different body.Use a fresh key per operation.
RATE_LIMITED429Per-window limit hit.Wait Retry-After seconds.
RATE_LIMITED_DAILY429Daily quota spent.Retry-After counts to end of day.
RATE_LIMITED_MONTHLY429Monthly quota spent.Retry-After counts to end of month.
INTERNAL_ERROR500Unexpected failure, or the token's creating user was deleted.Revoke and re-issue. Quote correlationId.
{
  "status": "error",
  "message": "Token is missing the required scope: crm.deals.read.",
  "category": "MISSING_SCOPE",
  "correlationId": "01J8ZQ9K3M4N5P6Q7R8S9T0V",
  "errors": [],
  "documentation_url": "https://developer.aiengagecrm.com/#g-errors"
}

Rate limits

Every authenticated response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

A 401 does not. Authentication runs before the rate limiter, so a rejected key never reaches it — do not write a client that expects those headers on every response, because the one response you are most likely to hit first has none of them.

Browsers see none of these headers at all unless the server sends Access-Control-Expose-Headers. From your own code (curl, Python, PHP) they are all there.

BucketRateDaily capApplies to
general100 per 10s250,00019 of the 24 endpoints
search5 per 1s50,000/objects/{module}/search and /objects/{module}/batch/read
email_send5 per 60s500POST /campaign/send and POST /email/send
contact_email_send15 per 1h360POST /contact/email/send

Tokens on the elevated tier get 5x both.

Idempotency

Send Idempotency-Key on any mutating call to make a retry safe.

  • Same key, same body - the cached response is replayed with Idempotency-Replayed: true.
  • Same key, different body - 409 IDEMPOTENCY_KEY_CONFLICT.

Cached 24 hours, keyed by organization + route + key so it cannot collide across tenants. For a batch call, one key covers the whole batch.

Supported modules

Use any of these as {module} in the URL:

contacts · deals · companies · products · quotes · invoices · payments · leads · tasks · tickets · meetings · calls · notes — plus any custom module your organization has created.

Field lists are not printed here, on purpose. Fields are defined per organization: an admin adds, renames and removes them, so any list written into this document would be a snapshot that goes stale and quietly starts lying.

Call GET /properties/{module} instead. It returns exactly what your organization has, right now — names, types, which are required, which are unique, and a picklist's accepted values.

Module resolution is forgiving: the exact slug is tried first, then a case-insensitive slug match, then the module's display, singular or plural name. Prefer the slug.

Scope of this document

  • has no endpoint documented here.

Email and WhatsApp are here rather than on pages of their own because they are the same API wearing the same clothes: one cak_live_ token, the same three-part scopes, the same error envelope, the same rate-limit headers. Splitting them out would duplicate all of that and let the copies drift.

The MCP chapter is the one deliberate exception, and it is not an endpoint reference. MCP reaches far more of the CRM than Modules does - reports, analytics, dashboards and the rest - but it reaches them as an assistant's tools rather than as routes you call, and it grants its access with the same scopes documented here. It is covered because the two share one authentication path and one scope model, and splitting them across two documents would hide that.

The OpenAPI file itself carries the 16 Modules operations, the two Email ones and the three WhatsApp ones, and nothing else: the MCP chapter adds no paths, no servers and no tags, so anything generated from the spec - a Postman collection, a client library - covers exactly those 24 calls.