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_moduleHow to use it
- Get an API token - in the CRM, Settings → API Keys → Create.
- Pick your module - the slug that goes in the URL, like
contacts. - Check its fields -
GET /properties/{module}lists them. - Enter your data - edit the body in the panel beside any endpoint.
- 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_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6Step 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 /objectsis 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:
| Key | Why you care |
|---|---|
name | The exact key to put inside properties. Not the label. |
required_on_create | Leave it out of a create and the call fails. |
unique | Safe to use as id_property or matching_property. |
options | For 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.
- Postman -> Import -> Link
- Paste this URL:
- 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.yamlThe 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
- An API key. It has to be allowed to read records — the
crm.{module}.readscope. A key without it gets403 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.afterfrom the response and pass it back as?after=;pagingis absent on the last page. limitis clamped to 1..100 rather than rejected.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
INVALID_CURSOR | 400 | The after value is malformed. | Pass paging.next.after back verbatim; never build a cursor. |
INVALID_PROPERTY | 400 | An include name is not a lookup field on this module, or more than 5 were sent. | Check GET /properties/{module}. |
MISSING_SCOPE | 403 | The key lacks crm.{module}.read, or a scope for a module named in include. | The message lists every scope needed. |
MODULE_NOT_AVAILABLE | 404 | Unknown, de-activated or unpublished module. | Ask an admin to publish it. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| limit | integer default 10 | Page size. Clamped server-side to 1..100 - a value outside that range is silently clamped, not rejected. |
| after | string | Opaque forward cursor, taken verbatim from `paging.next.after` of the previous page. Do not construct one yourself - a malformed value returns 400 INVALID_CURSOR. |
| sort | string 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`. |
| archived | string · enum | Include archived (soft-deleted) records. Only the exact strings `true` and `any` switch this on; anything else is ignored. |
| properties | string | Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless. |
| include | string | Comma-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
| Status | What 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: 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. 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 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 |
| 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" |
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.
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.
| 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
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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
propertiesis 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/createinstead. - Mandatory fields differ per module. Check
required_on_createinGET /properties/{module}, or the per-module tables in this document.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | A field failed its rule, or properties is missing. | errors[] names the property and the reason. |
INVALID_PROPERTY | 400 | A key in properties is not a field on this module. | Check GET /properties/{module} for real names. |
MISSING_SCOPE | 403 | The key lacks crm.{module}.write. | Remember it needs create AND edit permission. |
MODULE_NOT_AVAILABLE | 404 | Unknown, de-activated or unpublished module. | |
IDEMPOTENCY_KEY_CONFLICT | 409 | The key was reused with a different body. | Use a fresh key per operation. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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: 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. 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 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 |
| 429 | RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait |
| 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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_propertyis mandatory. It is validated in the controller rather than by the body validator, so omitting it gives400 VALIDATION_ERRORwith the message "Query parameter matching_property is required for PUT upsert."- The status is 200 whether it created or updated. Read the
X-Upsert-Actionresponse header -createdorupdated- to tell which happened. - Use a field marked
uniquein the property schema. A non-unique field that matches more than one record returns409 CONFLICTrather than the API guessing which you meant.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | matching_property missing, or a field failed its rule. | Add the query parameter. |
INVALID_PROPERTY | 400 | matching_property is not a field on this module. | Check GET /properties/{module}. |
FORBIDDEN | 403 | The match would change the record's owner and the user lacks Change Owner. | A permissions change, not a token change. |
CONFLICT | 409 | The matching property is not unique and matched several records. | Nominate a unique field. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| matching_propertyrequired | string | The property to match an existing record on. Mandatory. Best used with a field whose `unique` flag is true. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What it means, and what to do about it |
|---|---|
| 200 | The resulting record. Read 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 |
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. 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 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 |
| 429 | RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to read records — the
crm.{module}.readscope. A key without it gets403 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
INVALID_PROPERTY | 400 | id_property is not a field on this module. | Check GET /properties/{module}. |
OBJECT_NOT_FOUND | 404 | No such record, or it is outside your visibility. | The two are indistinguishable by design. |
CONFLICT | 409 | id_property is not unique and matched several records. | Nominate a unique field. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
Query parameters
| Name | Type | Description |
|---|---|---|
| id_property | string | 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 than one record matches, the call returns 409 CONFLICT rather than picking one. |
| properties | string | Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless. |
| include | string | Comma-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
| Status | What 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: 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. 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 |
| 429 | RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0?properties=email%2Cfirst_name" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
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.
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.
| 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
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | A field failed its rule. | errors[] names the property. |
FORBIDDEN | 403 | An owner change the acting user may not make. | Needs Change Owner in their profile. |
OBJECT_NOT_FOUND | 404 | No such record, or outside your visibility. | |
CONFLICT | 409 | id_property matched several records. | Use a unique field. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
Query parameters
| Name | Type | Description |
|---|---|---|
| id_property | string | 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 than one record matches, the call returns 409 CONFLICT rather than picking one. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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: 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. 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 |
| 429 | RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to archive records — the
crm.{module}.deletescope. A key without it gets403 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
MISSING_SCOPE | 403 | The key holds write but not delete. | They are separate scopes. |
OBJECT_NOT_FOUND | 404 | No such record, or outside your visibility. | |
CONFLICT | 409 | id_property matched several records. | Use a unique field. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
Query parameters
| Name | Type | Description |
|---|---|---|
| id_property | string | 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 than one record matches, the call returns 409 CONFLICT rather than picking one. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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: 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. 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 |
| 429 | RATE_LIMITED, RATE_LIMITED_DAILY or RATE_LIMITED_MONTHLY. The category tells you which. Resolution: wait |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
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.
Search Records
Search Records
- An API key. It has to be allowed to read records — the
crm.{module}.readscope. A key without it gets403 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
| Operator | Takes | Notes |
|---|---|---|
EQ NEQ LT LTE GT GTE | value | |
BETWEEN | value + highValue | Inclusive both ends. |
IN NOT_IN | values array | |
HAS_PROPERTY NOT_HAS_PROPERTY | nothing | Tests whether the field is set at all. |
CONTAINS_TOKEN NOT_CONTAINS_TOKEN | value | Case-insensitive substring. |
STARTS_WITH ENDS_WITH | value | Case-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
sortsis omitted the default iscreated_at DESCENDING. - Paging is the same cursor scheme as the list endpoint.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
INVALID_FILTER | 400 | Unknown operator, more than 5 groups, or more than 6 filters in a group. | The message says which limit you hit. |
INVALID_PROPERTY | 400 | A propertyName is not a field on this module. | Check GET /properties/{module}. |
INVALID_CURSOR | 400 | Malformed after. | Pass the previous cursor back verbatim. |
RATE_LIMITED | 429 | The tight search bucket is exhausted. | 5 per second. Wait Retry-After. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Status | What 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 |
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. 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 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 |
| 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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 }' |
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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)
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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
statusanderrors; the code alone tells you nothing. - Each input is processed independently, so one bad row does not abort the other ninety-nine.
- One
Idempotency-Keycovers 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | inputs missing, not an array, or over 100 items. | Split into batches of 100. Nothing was written. |
MISSING_SCOPE | 403 | The key lacks crm.{module}.write. | |
| Per-item errors | 207 | Inside errors[], not as an HTTP status. | Inspect each entry's index. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What it means, and what to do about it |
|---|---|
| 207 | Multi-Status. Per-item outcomes - read 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: 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } } ] }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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)
- An API key. It has to be allowed to read records — the
crm.{module}.readscope. A key without it gets403 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_FOUNDinsideerrors[], not as a failed call.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | inputs missing or over 100 items. | Split into batches of 100. |
MISSING_SCOPE | 403 | The key lacks crm.{module}.read. | |
RATE_LIMITED | 429 | The search bucket is exhausted. | 5 per second. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| properties | string | Comma-separated property names to limit what comes back under `properties`. Envelope metadata (id, timestamps, archived) is always returned regardless. |
| include | string | Comma-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
| Status | What 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 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: 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } ] }' |
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.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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)
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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
PATCHdoes. - 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | inputs missing or over 100 items. | Nothing was written. |
FORBIDDEN | 403 | Multi-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_SCOPE | 403 | The key lacks crm.{module}.write. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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: 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } } ] }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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)
- An API key. It has to be allowed to archive records — the
crm.{module}.deletescope. A key without it gets403 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | inputs missing or over 100 items. | Nothing was archived. |
FORBIDDEN | 403 | Multi-item batch and Mass Delete is off for this user. | Nothing was archived. |
MISSING_SCOPE | 403 | The key lacks crm.{module}.delete. | write is not enough. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What it means, and what to do about it |
|---|---|
| 207 | Multi-Status. 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: 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } ] }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to read records — the
crm.{module}.readscope. A key without it gets403 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 atotal). Everything else is cursor-paged.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
MISSING_SCOPE | 403 | Missing the read scope for the near side or the far side. | Both are required. |
MODULE_NOT_AVAILABLE | 404 | Either module is unknown or unpublished. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
| toModulerequired | string | API name of the module on the FAR side of the association. |
Query parameters
| Name | Type | Description |
|---|---|---|
| limit | integer 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. |
| page | integer 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
| Status | What 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/objects/contacts/6650f1a2b3c4d5e6f7a8b9c0/associations/deals?limit=10" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
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.
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.
| 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
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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: falseandid: null- not an error. Safe to retry. - No request body is needed; everything is in the path.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | These two records cannot be linked. | |
FORBIDDEN | 403 | Missing the write scope for the far side. | Both sides need write. |
OBJECT_NOT_FOUND | 404 | One of the records does not exist. | |
MODULE_NOT_AVAILABLE | 404 | One of the modules is unknown or unpublished. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
| toModulerequired | string | API name of the module on the FAR side of the association. |
| toIdrequired | string | Id of the record on the far side. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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: 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. 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
| 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
- An API key. It has to be allowed to create and edit records — the
crm.{module}.writescope. A key without it gets403 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
FORBIDDEN | 403 | Missing the write scope for the far side. | |
OBJECT_NOT_FOUND | 404 | No association found between these records. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| idrequired | string | The record's unique id. When `id_property` is also sent, this is that property's value instead. |
| toModulerequired | string | API name of the module on the FAR side of the association. |
| toIdrequired | string | Id of the record on the far side. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Key | string | Makes 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
| Status | What 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. 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
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.
Fields Metadata
Get Fields
- An API key. It has to be allowed to read field definitions — the
crm.schema.readscope. A key without it gets403 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 = falseare filtered out entirely - they will never appear here, and never in a record'sproperties. optionsisnullfor every type exceptpick_list,picklist,multi_selectanddropdown.- 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
MISSING_SCOPE | 403 | The key lacks crm.schema.read. | This is an org-level scope, not per module. |
MODULE_NOT_AVAILABLE | 404 | Unknown, de-activated or unpublished module. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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
| Status | What 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. 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 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/properties/contacts" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
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.
| 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
- An API key. It has to be allowed to read field definitions — the
crm.schema.readscope. A key without it gets403 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 asname. - Hidden fields are invisible here just as they are in the list.
Possible Errors
| Code | HTTP | Description | Resolution |
|---|---|---|---|
INVALID_PROPERTY | 404 | The 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_AVAILABLE | 404 | Unknown, de-activated or unpublished module. |
Path parameters
| Name | Type | Description |
|---|---|---|
| modulerequired | string | API 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. |
| propertyrequired | string | The field's public name, as returned by `GET /properties/{module}`. |
Responses and errors
| Status | What 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. 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 ( 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/properties/contacts/email" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
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.
| 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 | } |
List From Addresses
- An API key. It has to be allowed to read your from addresses — the
email.from_addresses.readscope. A key without it gets403 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: falseaddresses are listed, not hidden. An address that sends over its own SMTP server gets no delivery, open or click callbacks, soPOST /campaign/sendrefuses 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
UNAUTHORIZED | 401 | Token missing, malformed or revoked. | Check the Authorization header. |
MISSING_SCOPE | 403 | The key lacks email.from_addresses.read. | Re-issue the key with that scope ticked. |
RATE_LIMITED | 429 | Per-window limit hit. | Wait Retry-After seconds. |
Responses and errors
| Status | What 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. 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/email/from-addresses" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
| 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
- An API key. It has to be allowed to send email — the
email.messages.sendscope. A key without it gets403 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.
ScopeThis can deliver real mail.
test_modedefaults to true, which validates everything and sends nothing. You must pass"test_mode": falseto actually deliver. Pressing Send on this page with the default body is safe.
email.messages.send
Org-wide. Granted to a key whose creating user has the Email Channel feature permission. Parameters
| Name | In | Required | Description |
|---|---|---|---|
from_account_id | body | yes | An id from GET /email/from-addresses. Must be trackable. |
to | body | yes | One recipient address. |
subject | body | yes | Subject line. |
body_html | body | yes | HTML body, up to 256,000 bytes. |
body_text | body | no | Plain-text alternative. Derived from the HTML when omitted. |
test_mode | body | no | Defaults 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_idis that log and is the same on every response;recipient_ididentifies 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_modedefaults 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-Keyis 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_idand 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | A field is missing or malformed. | errors names the field. |
IDEMPOTENCY_KEY_REQUIRED | 400 | No Idempotency-Key header. | Send one. |
UNAUTHORIZED | 401 | Token missing, malformed or revoked. | Check the Authorization header. |
MISSING_SCOPE | 403 | The key lacks email.messages.send. | Re-issue the key with that scope. |
IDEMPOTENCY_KEY_CONFLICT | 409 | Same key reused with a different body. | Use a fresh key for a new message. |
SEND_NOT_ALLOWED | 422 | The 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_LIMITED | 429 | 5/minute or 500/day exceeded. | Wait Retry-After seconds. |
SEND_FAILED | 502 | The provider refused the message. | The message carries the provider's reason. Safe to retry with the same key. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyrequired | string | REQUIRED 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
| Status | What 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: 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. 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 |
| 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 |
| 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"
} |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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 }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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)
- An API key. It has to be allowed to send email — the
email.transactional.sendscope. A key without it gets403 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_modedefaults to true, which validates everything and sends nothing. You must pass"test_mode": falseto 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
| Name | In | Required | Description |
|---|---|---|---|
from | body | yes\ | The address to send from, e.g. billing@yourdomain.com. Must be one your organization has verified. |
from_account_id | body | yes\ | An id from GET /email/from-addresses - the older way of naming the same address. |
to | body | yes | The primary recipient. |
cc | body | no | One address, or an array of them. Visible to every recipient. |
bcc | body | no | One address, or an array of them. Hidden from the others. |
reply_to | body | no | Overrides the from-address's own reply-to. |
subject | body | yes | Subject line. |
body_text | body | yes | Plain-text body, up to 256,000 bytes. |
test_mode | body | no | Defaults 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
trackingobject, so you do not have to remember it. - One credit per call, however many people you reach. A message with one
toand threecccosts exactly what one with no copies costs. What limits your reach is the ceiling below, not the price. - At most 50 addresses across
to,ccandbcctogether. - Duplicates are removed, not refused. An address already in
tois dropped fromccandbcc; one in bothccandbcckeeps itsccplace. The response listsccandbccexactly 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 theccline 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-Keyis 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_idis that log;recipient_ididentifies 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
| Code | HTTP | Description | Resolution |
|---|---|---|---|
VALIDATION_ERROR | 400 | A field is missing or malformed, or body_html was sent. | errors names the field. |
IDEMPOTENCY_KEY_REQUIRED | 400 | No Idempotency-Key header. | Send one. |
UNAUTHORIZED | 401 | Token missing, malformed or revoked. | Check the Authorization header. |
MISSING_SCOPE | 403 | The key lacks email.transactional.send. | Re-issue the key with that scope ticked. Holding email.messages.send is not enough. |
IDEMPOTENCY_KEY_CONFLICT | 409 | Same key reused with a different body. | Use a fresh key for a new message. |
SEND_NOT_ALLOWED | 422 | A 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_LIMITED | 429 | 15/hour or 360/day exceeded. | Wait Retry-After seconds. |
SEND_FAILED | 502 | The provider refused the message. | The message carries the reason. Safe to retry with the same key. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyrequired | string | REQUIRED 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
| Status | What 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: 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. 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 |
| 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 |
| 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"
} |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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 }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to send email — the
email.messages.sendscope. A key without it gets403 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.
ScopeThis can deliver real mail.
test_modedefaults to true, which validates everything, reports what it would do, and changes nothing — no message, and no contact. You must pass"test_mode": falseto actually send. Pressing Send on this page with the default body is safe.
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_action | What happened |
|---|---|
matched | They were already in the CRM, and nothing about them changed. |
updated | They were already there, and the fields you sent in contact were written. Fields you did not send are untouched. |
created | They were not there, so a contact was made. |
unavailable | There 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
| Name | In | Required | Description |
|---|---|---|---|
from_account_id | body | yes | An organization address, from GET /email/from-addresses. |
to | body | yes | The recipient. This is also what identifies the contact. |
subject | body | yes | Subject line. Merge fields resolve against the contact. |
body_html | body | yes | HTML body. Merge fields resolve here too. |
body_text | body | no | Plain-text alternative. Derived from the HTML when omitted. |
contact | body | no | Contact fields to create the record with, or update it with. |
test_mode | body | no | Defaults 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
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyrequired | string | REQUIRED 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
| Status | What 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: 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. 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 |
| 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 |
| 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"
} |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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 }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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 | } |
List Templates
- An API key. It has to be allowed to read WhatsApp templates — the
whatsapp.templates.readscope. A key without it gets403 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:
| Shape | Looks like | Means |
|---|---|---|
| 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
| Status | What 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. 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
| 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
- An API key. It has to be allowed to read WhatsApp templates — the
whatsapp.templates.readscope. A key without it gets403 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
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The template id, from List Templates. |
Path parameters
| Name | Type | Description |
|---|---|---|
| idrequired | string | The template's `id`, as List Templates returns it. |
Responses and errors
| Status | What 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. 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 |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "https://app.aiengagecrm.com/cback/api/public/v1/whatsapp/templates/6ae06ed29fe2c3647a017c74" \ |
| 2 | -H "Authorization: Bearer YOUR_API_TOKEN" |
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.
| 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
- An API key. It has to be allowed to send WhatsApp templates — the
whatsapp.templates.sendscope. A key without it gets403 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.
ScopeThis delivers real messages and spends WhatsApp credits. There is no
test_modeon this endpoint, and no dry run. Every accepted call reaches the recipient.
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
- the opt-in / unsubscribe rules for this template and sender
- a price estimate for this destination
- your WhatsApp credit balance
- the deduction, and only then the provider call
A failure at any gate returns before the message leaves, and nothing is charged. Parameters
| Name | In | Required | Description |
|---|---|---|---|
id | path | yes | The template to send, from List Templates. |
phone | body | yes | Recipient with country code. Non-digits are stripped; 10 digits must remain. |
template_language | body | no | Language code. Defaults to the template's own. |
placeholders | body | no | The values for {{1}}, {{2}}, … in order. |
header_placeholder | body | no | The value for a media or text header, when the template has one. |
sender_id | body | no | Only for a template bound to no sender. |
Path parameters
| Name | Type | Description |
|---|---|---|
| idrequired | string | The template to send, as List Templates returns it. |
Responses and errors
| Status | What 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 ( 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. 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. 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 |
| 500 | The send failed unexpectedly. Quote 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"
} |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" ] }' |
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.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
| 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
- An API key. It has to be allowed to send WhatsApp templates — the
whatsapp.templates.sendscope. A key without it gets403 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.
ScopeThis delivers real messages and spends WhatsApp credits. There is no
test_modeon either WhatsApp endpoint, and no dry run. Every accepted call reaches the recipient.
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_action | What happened |
|---|---|
matched | They were already in the CRM, and nothing about them changed. |
updated | They were already there, and the fields you sent in contact were written. Fields you did not send are untouched. |
created | They were not there, so a contact was made. |
unavailable | There 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.
ParametersOnly this endpoint fills from a contact.
POST /whatsapp/templates/{id}/sendis given a phone number and nothing else, so it has no contact to read and sends exactly theplaceholdersyou pass it.
| Name | In | Required | Description |
|---|---|---|---|
phone | body | yes | Recipient with country code. Non-digits are stripped; 10 digits must remain. |
template_id | body | yes | The template to send, from GET /whatsapp/templates. |
template_language | body | no | Language code. Defaults to the template's own. |
placeholders | body | no | The 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_placeholder | body | no | The value for a media or text header, when the template has one. |
sender_id | body | no | Only for a template bound to no sender. |
contact | body | no | Contact fields to create the record with, or update it with. |
Headers
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyrequired | string | REQUIRED 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
| Status | What 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 ( 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. 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 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 |
| 422 | A gate refused the send, and nothing was charged. The same set the template endpoint returns: 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 |
| 500 | The send failed unexpectedly. Quote 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"
} |
https://app.aiengagecrm.com/cback/api/public/v1Production - the live AiEngage CRM API
Pasted once, it is used by every sample on this page and by Send. Stored in this browser only.
| 1 | curl "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" } }' |
Reuse the same value to retry a send you are unsure of; a new one means a new message.
Edit this and the samples above update with it, so Copy gives you the request you actually sent.
Paste your key and press Load templates. WhatsApp only sends approved templates — there is no free text.
| 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.
| Method | What it does | |
|---|---|---|
| GET | Get Records | |
| POST | Search Records | |
| POST | Insert Records (batch) | |
| GET | Get Associations | |
| GET | Get Fields | |
| GET | List From Addresses | |
| GET | List 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
GETonly reads, but aPOST,PUT,PATCHorDELETEchanges your data. The console says which it is about to do before you press Send. The two email send endpoints default totest_mode, so pressing Send validates and reports rather than delivering — but the two WhatsApp ones have notest_modeand 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.
| Mode | Token | Who uses it |
|---|---|---|
| 1 | cak_live_<32 chars> | External integrations. Settings → API Keys. |
| 2 | Purpose-scoped user JWT | The in-app CRM agent. |
| 3 | Dashboard login JWT | A signed-in person using their own session. |
| 4 | cak_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:
| Family | Covers |
|---|---|
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.
| Scope | Granted when the token's user has |
|---|---|
crm.{module}.read | view permission on that module |
crm.{module}.write | create AND edit permission |
crm.{module}.delete | delete permission |
crm.schema.read | the 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_urlpoints 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.
| Category | HTTP | Description | Resolution |
|---|---|---|---|
UNAUTHORIZED | 401 | Token missing, malformed, unknown, revoked or expired. | Check the Authorization: Bearer header. |
MISSING_SCOPE | 403 | Authenticated, but the token lacks this route's scope. | The message names the scope. Re-issue the key with it. |
FORBIDDEN | 403 | Scoped, 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_ERROR | 400 | Body 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_PROPERTY | 400 | A property name does not exist on this module, or more than 5 include values. | Call GET /properties/{module} for the real names. |
INVALID_FILTER | 400 | Unknown operator, more than 5 filter groups, or more than 6 filters in a group. | Check the operator table in the search guide. |
INVALID_CURSOR | 400 | The after cursor is malformed. | Pass paging.next.after back verbatim. |
OBJECT_NOT_FOUND | 404 | No such record, or it is outside the acting user's visibility. | The two are deliberately indistinguishable so existence never leaks. |
MODULE_NOT_AVAILABLE | 404 | No module matches that name, it is de-activated, or unpublished. | Holding the scope does not override publication. |
ENDPOINT_NOT_FOUND | 404 | The 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_AVAILABLE | 404 | The first path segment is not a version this host serves. | available_versions in the body lists the ones it does. |
CONFLICT | 409 | An id_property or matching_property on a non-unique field matched more than one record. | Use a field marked unique. |
IDEMPOTENCY_KEY_CONFLICT | 409 | The same key was reused with a different body. | Use a fresh key per operation. |
RATE_LIMITED | 429 | Per-window limit hit. | Wait Retry-After seconds. |
RATE_LIMITED_DAILY | 429 | Daily quota spent. | Retry-After counts to end of day. |
RATE_LIMITED_MONTHLY | 429 | Monthly quota spent. | Retry-After counts to end of month. |
INTERNAL_ERROR | 500 | Unexpected 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.
| Bucket | Rate | Daily cap | Applies to |
|---|---|---|---|
general | 100 per 10s | 250,000 | 19 of the 24 endpoints |
search | 5 per 1s | 50,000 | /objects/{module}/search and /objects/{module}/batch/read |
email_send | 5 per 60s | 500 | POST /campaign/send and POST /email/send |
contact_email_send | 15 per 1h | 360 | POST /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.