Data push API
One address your systems send to in near real time: what happened (events), who your customers are (customers) and what else you keep (records). Safe to send again.
This page is written for the developer who connects those systems. It lists every field, every answer and every code, with examples you can send as they are.
What it is, and when to use it
Your systems post JSON to one address. One request can carry five lists:
- events: what happened, such as a payment, an order, a sign-up or a renewed subscription;
- customers: who your customers are, with their consent to marketing, a block when they must not be contacted, and fields of your own;
- records: anything else you keep, such as a product, a store or a subscription;
- plans and actuals: your budget, forecast and target, and the figures only your own accounting knows (see Connecting your data).
Every list is keyed: an event by its event_id, a customer by
customer_id or email, a record by its type and id. Sending the same
request again never doubles anything.
Use the push when your system knows the moment something happens: an order system, a billing system, a job that runs every few minutes. Two other ways in suit other cases:
- A file suits a nightly export. A roster file makes a contact per row (by e-mail, else by its id) with the consent its columns state; a flag column in a file blocks nobody. Send blocks through this API, or connect the database they live in.
- A connected database suits data that sits in a table we can read on a schedule.
This API and a connected database follow one rule for people: what your own system says about a person is the truth, in both directions. A no to marketing withdraws it, a later yes gives back what that same source withdrew, a block is added and lifted by what your system states, and a changed e-mail, phone or name sent with your id for the person replaces the one the contact held. What the person did themselves (an unsubscribe, a STOP, a bounce, a complaint) and what your team did by hand always stand.
Before the first call
-
Issue a key. On Data → Push, under the address, Issue a key. Name it after the system that will use it. The key is issued for the brand open on the page, and the key list says which brand each key is for. It is shown once: copy it into your system's secret store. If it goes missing, revoke it and issue another. You can pin a key to the fixed IP addresses your systems send from and give it an expiry.
-
Copy the address. The card shows the full address for the brand:
texthttps://api.theaicmo.com/api/warehouse/ingest/<organisation id>?client_id=<brand id> -
Send a first request. Save this body as
body.json:json{ "events": [ { "event_type": "payment", "event_id": "payment:90071", "event_time": "2026-11-13T10:00:00Z", "customer_id": "C-20418", "amount": 49.90, "currency": "EUR" } ], "customers": [ { "customer_id": "C-20418", "email": "anna.novak@example.com", "first_name": "Anna", "last_name": "Novak", "email_consent": true } ] }Send it as a dry run first:
dry_run=1reads and judges everything and stores nothing.bashcurl -X POST "https://api.theaicmo.com/api/warehouse/ingest/<organisation id>?client_id=<brand id>&dry_run=1" \ -H "Authorization: Bearer $PUSH_KEY" \ -H "Content-Type: application/json" \ --data @body.jsonThe answer names the brand it would store under, and counts what each row would do. Send this sample as a dry run only: sent for real, it would add a sample customer to your brand. When it reads right, send your own data without
dry_run=1.
A key can only send data in. It cannot list or export your customers and
cannot erase a brand's data. It replaces the brand's event stored under an
event_id it sends, updates the customers and records it sends, and adds
or lifts entries on the brand's push block lists, which every key of the
brand shares. Keys from Settings → API keys are for
the rest of the API and cannot send data in.
The request
POST to the address with a JSON body and Content-Type: application/json. A body sent with another text type is read as JSON
too; a form-encoded body answers 400 body_shape. Any other method
answers 405. Every answer is JSON, the 405 included.
The key goes in a header, either one:
Authorization: Bearer aicmo_wh_...
X-Api-Key: aicmo_wh_...
Never put a key in the address: such a request is refused with 401.
(A connection set up long ago with a key in the address keeps working,
limited to 120 requests a minute and 10,000 a day, and every answer it
gets carries a notice to issue a key on Data → Push.)
The brand. Every request stores under one brand, and the answer
always names it in brand. It is worked out in this order:
- The key was issued for a brand: that brand. A request that names
another brand is refused with
403 wrong_profile. - The request names a brand:
?client_id=<brand id>in the address, the headerX-Client-Id, or"client_id"at the top of the body. Two that differ:400 client_id_conflict. An id that is not a brand of your organisation:404 unknown_brand. - Nothing names one and your organisation has exactly one brand: that brand.
- Otherwise
400 client_id_required, with your brands listed inbrands. An organisation with no brand yet answers400 no_brand.
{
"error": "client_id_required",
"message": "This organisation has several brands, so say which one this data is for. Add ?client_id=<brand id> to the address. The brands are listed in \"brands\".",
"brands": [
{ "id": "6f1c2a9e-0b7d-4c1e-9a55-2f3d8c7b1e40", "name": "Northwind EU" },
{ "id": "0d4b7a12-93e1-4c55-b0f8-6a2e1c9d7b34", "name": "Northwind US" }
]
}
A client_id inside a row is not read: on an event it is kept as a
field, with a hint.
The body is one JSON object:
{
"time_zone": "Europe/Prague", optional: for times sent without a zone
"client_id": "<brand id>", optional: see the brand above
"events": [ ... ],
"customers": [ ... ],
"records": [ ... ],
"plans": [ ... ],
"actuals": [ ... ]
}
- Send any of the lists, in any combination, and at least one row.
- A bare list or a single event without the object around it answers
400 body_shape. Any other key at the top answers400 unknown_list, naming the key and the list it most likely means (contactsandusersmeancustomers), with the allowed names inallowed. - A list that is not a JSON list answers
400 list_not_array; no row in any list,400 empty_request. time_zonemust be a time zone name such asEurope/PragueorAmerica/New_York, else400 time_zone_unknown. It is used only for times sent without a zone (see Times).?dry_run=1(ortrue) in the address makes the request a dry run. Besidesclient_idanddry_run, nothing in the address is read.
Sizes. A list holds at most 1,000 rows (plans 2,000, actuals 5,000);
more answers 413 too_many_rows and nothing is stored. A request is at
most 4 MB, else 413 body_too_large. One row is at most 64 KB as JSON;
a larger row is refused on its own (row_too_large) and the rest of the
request goes on. Every limit is in the table under
Limits and sending in real time.
Events
An event is something that happened, at a moment. A payment:
{
"events": [
{
"event_type": "payment",
"event_id": "payment:90071",
"event_time": "2026-11-13T10:00:00Z",
"customer_id": "C-20418",
"customer_email": "anna.novak@example.com",
"amount": 49.90,
"currency": "EUR",
"channel": "web",
"properties": { "method": "card", "invoice_number": "INV-2026-1187" }
}
]
}
| Field | Type | Required | How it is read |
|---|---|---|---|
event_type | text | yes | What happened: payment, signup, subscription_renewed. Stored in lower case, spaces become underscores, and only letters a to z, digits, _, : and - are kept; other letters are dropped, and a type with none of these is refused. At most 60 characters. A hint says when the stored name differs from the one you sent. order is stored as purchase, the platform's name for a sale. suppress and unsuppress are block operations (Blocking a person). |
event_id | text or number | yes | Your own id of this event, at most 200 characters. Put the type in front: payment:90071. A number above 9007199254740991 cannot be exact and is refused: send long ids as text. A step may leave it out (A record that changes). |
event_time | time | no | When it happened (Times). Left out, null or empty: the moment it arrived, counted in without_time, with a hint. |
customer_id | text or number | no | Your id of the person, at most 200 characters. 0, empty text and null mean no customer. |
customer_email | text | no | The person's e-mail. Trimmed and lower-cased; it must hold an @ with a dot after it, else the row is refused. |
amount | number or text | no | The event's money (Numbers and money). Negative amounts are allowed. |
currency | text | no | Three letters, such as EUR, USD or CZK, stored in upper case. Anything else refuses the row. |
channel | text | no | Where it happened, one of the platform's channels, such as web, email or sms. Left out: other. A value the platform does not know is stored as other, and what you sent is kept as a field named channel, with a hint. |
campaign_id, campaign_name | text | no | The campaign it belongs to, as you name it. |
properties | object | no | The event's own fields. Anything but an object refuses the row. |
step_of | object | no | This event is a step of a record: { "event_type": ..., "event_id": ... } (A record that changes). |
step | text | no | The step's plain name, such as Activated. Longer than 60 characters is cut. |
| any other name | any JSON | no | Kept as a field of the event, as if it were inside properties. A field at the top wins over the same name inside properties. |
Every pushed event is stored with the source webhook and with the
request id of the request that stored it.
The id rule
event_idis required. It is what makes sending again safe.- Use your own id with the type in front:
payment:90071,refund:90071,signup:C-20418. - One id names one event per brand, across all event types.
- The same id and type sent again replaces the stored event: what the new copy does not carry is gone. An identical copy writes nothing.
- The same id twice in one request under one type: the later row is kept
and the earlier is counted in
repeated, with a hint. - The same id in one request under two types: every row of that id is
refused (
id_twice_with_two_types). - An id already stored for the brand under another type: the row is
refused (
id_used_by_another_type). The answer names the stored type.
{
"events": [
{
"event_type": "payment",
"event_id": "1002",
"event_time": "2026-11-13T10:00:00Z",
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
},
{
"event_type": "refund",
"event_id": "1002",
"event_time": "2026-11-13T10:30:00Z",
"customer_id": "C-20418",
"amount": -25,
"currency": "EUR"
}
]
}
{
"events": [
{
"event_type": "payment",
"id": "90071",
"event_time": "2026-11-13T10:00:00Z",
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
}
]
}
Who the event is about
customer_idonly: the event is filed under that id.customer_emailonly: the event is filed under the e-mail.- Both: they are one person, and the platform keeps them together.
- Neither: the event is stored and counted in
without_customer. It is on nobody's timeline and starts no journey. When the row carries a field that looks like a person's id (user_id,member_id,account_id,person_id,customerId,userId,uid) or e-mail (email,email_address,user_email), a hint names it.
Every person an event names becomes a contact of the brand, known by the id and, when you send it, the e-mail. Nothing is assumed about their consent: a new address starts Not granted for marketing. Consent and the person's details are sent in the customers list.
What is not read on an event
These are kept as plain fields of the event, each with a hint, and change
nothing about the person: email_consent, sms_consent, block,
phone, first_name, last_name, email, external_id,
visitor_id, client_id. Send consent, blocks and the person's details
in the customers list, and the person's id as customer_id.
The platform writes some fields itself, and drops your copy of them with
a hint: _step_of, _step_of_event_id, _step, _batch_id, any name
starting with _written: or _read_as:, and step_time on a step. Other
names starting with an underscore are kept as sent.
Examples
An order. order is stored as purchase, and the answer carries a hint
saying so:
{
"events": [
{
"event_type": "order",
"event_id": "order:A-7733",
"event_time": "2026-11-13T09:41:07Z",
"customer_id": "C-20418",
"amount": 129.00,
"currency": "EUR",
"channel": "web",
"properties": {
"items": [ { "sku": "SKU-1042", "quantity": 1, "price": 129.00 } ],
"store_id": "ST-07",
"shipping": "courier"
}
}
]
}
A sign-up, with what your own system knows about how the person came:
acquisition_source, affiliate_id, affiliate_tag and promo_code.
The customer's page reads them for How they came when signup is
your sign-up conversion (Data → Events → Conversions).
{
"events": [
{
"event_type": "signup",
"event_id": "signup:C-20418",
"event_time": "2026-11-13T09:58:12Z",
"customer_id": "C-20418",
"customer_email": "anna.novak@example.com",
"acquisition_source": "newsletter",
"affiliate_id": "aff-771",
"affiliate_tag": "b_771_nov",
"promo_code": "WELCOME10"
}
]
}
A record that changes
Some things have a life of their own: a voucher is given, activated, used, then cancelled or expired; a subscription starts, pauses and ends. Send one event for the record, and one event for each step, and say on each step whose step it is.
- The record is an ordinary event.
event_typeis the kind of record (voucher),event_idis its id (voucher:3001), andevent_timeis when it began, the same on every send. Send it again under the same id when its own fields change. A field calledname(ortitle, orlabel) is what the timeline shows after the status. - A step is an event of its own type (
voucher_activated), withevent_time= when the step happened, the samecustomer_idas the record, and"step_of": { "event_type": "voucher", "event_id": "voucher:3001" }.stepgives it a plain name ("Used up"); left out, the name is read from the type (voucher_activatedreads as Activated).event_idmay be left out: it is then<record id>#<step type>(voucher:3001#voucher_activated), so a step is safe to send again and a record has one step of each type. - Put the record's name on its steps too: a step that arrives before its record still shows a line of its own, from its own fields.
- Put the amount on the record; on a step only when the step itself moved money.
{
"events": [
{
"event_type": "voucher",
"event_id": "voucher:3001",
"event_time": "2026-11-01T09:00:00Z",
"customer_id": "C-20418",
"name": "Welcome pack"
},
{
"event_type": "voucher_activated",
"event_time": "2026-11-02T08:00:00Z",
"customer_id": "C-20418",
"name": "Welcome pack",
"step_of": { "event_type": "voucher", "event_id": "voucher:3001" }
},
{
"event_type": "voucher_used",
"event_time": "2026-11-05T08:00:00Z",
"customer_id": "C-20418",
"name": "Welcome pack",
"step": "Used up",
"step_of": { "event_type": "voucher", "event_id": "voucher:3001" }
},
{
"event_type": "voucher_cancelled",
"event_time": "2026-11-06T08:00:00Z",
"customer_id": "C-20418",
"name": "Welcome pack",
"step_of": { "event_type": "voucher", "event_id": "voucher:3001" }
}
]
}
The customer's timeline shows this as one line, Voucher cancelled ·
Welcome pack, with its steps under it: when it was given, Activated,
Used up and Cancelled, each with its time. Each step is also an ordinary
event of its own type, so a journey that waits for voucher_activated
starts on it.
A step whose event_type is the record's own type is refused
(step_of_itself), and so is a step_of without both parts
(step_of_incomplete). The push API does not check that the record exists:
a step may arrive first.
{
"events": [
{
"event_type": "voucher_activated",
"event_id": "voucher:3001#voucher_activated",
"event_time": "2026-11-02T08:00:00Z",
"customer_id": "C-20418",
"step_of": { "event_type": "voucher" }
}
]
}
One limit: a timeline page that holds only the record, such as the
timeline filtered to the type voucher, or a search, shows the record
without its status.
Customers
A customers row says who a person is. Send what you know; on a later request, send only what changed.
{
"customers": [
{
"customer_id": "C-20418",
"email": "anna.novak@example.com",
"phone": "+1 415 555 0123",
"first_name": "Anna",
"last_name": "Novak",
"status": "active",
"lifetime_value": 1280.40,
"created_at": "2025-06-02T08:15:00Z",
"email_consent": true,
"sms_consent": false,
"attributes": {
"plan": "gold",
"orders_count": 14,
"favourite_category": "running",
"store_id": "ST-07"
}
}
]
}
The fields are exactly these. Any other name refuses the row
(unknown_field, naming the field you most likely meant), so a mistyped
email_consent can never become a profile value in silence. Your own
fields go inside attributes.
| Field | Type | Required | How it is read |
|---|---|---|---|
customer_id | text or number | customer_id or email | The person's id in your system, at most 200 characters. It is kept on the contact beside the e-mail. An id that is an e-mail address is read as that e-mail. |
email | text | customer_id or email | Lower-cased; it must be an e-mail address. |
phone | text | no | International form only: + or 00, then 8 to 15 digits; spaces, dots, dashes and brackets are ignored. Stored as + and the digits. A national number is refused, never guessed (phone_unreadable). |
first_name, last_name | text | no | At most 200 characters each. |
status | text | no | The customer's status in your system, lower-cased, at most 200 characters. |
lifetime_value | number or text | no | Read as an amount is. A value that cannot be read is stored empty with your text kept, and counted in values_unread. Never 0. |
created_at | time | no | Customer since (Times). It only ever moves earlier. |
email_consent | true or false | no | Marketing e-mail. |
sms_consent | true or false | no | Marketing texts: SMS and WhatsApp. |
block | text | no | all, marketing or none (Blocking a person). |
block_reason | text | no | Kept on the block entry. Longer than 500 characters is cut. |
attributes | object | no | Your own fields about the person. |
A row with neither customer_id nor email is refused
(customer_identity_missing): a phone alone does not identify a
customer here.
Which identifier to send
Send customer_id, your own id, on every row, and email whenever you
have it. The same customer_id then ties the person's events, records
and customer row together.
One e-mail is one person. A row whose e-mail another customer_id
of the brand already holds, in any letter case, is refused
(email_of_another_customer) and nothing of it is merged into either
person. A block on that row is still
recorded against the row's own identifiers, and the refusal says so. A
false on it still applies to the e-mail and phone the contact of its
own customer_id holds, never to the other customer's.
The same customer twice in one request is applied in order as one, the
later row winning for each field it names and attributes merging name
by name. It is counted in merged, with a hint. Rows are grouped by
customer_id; a row with only an e-mail joins the group that carries
that e-mail.
Sending only what changed
- A field left out is kept as it is.
attributesmerge name by name.nullfor one attribute empties that value; the others stay.email_consent,sms_consentandblockleft out, ornull, change nothing.statusandlifetime_value: the newest value you send wins. They cannot be emptied by a push.emailandphoneare never emptied:nullleaves them as they are.
{
"customers": [
{
"customer_id": "C-20418",
"attributes": { "plan": "platinum", "store_id": null }
},
{ "customer_id": "C-30077", "email_consent": false }
]
}
The first row changes the plan and empties store_id; everything else
about C-20418 stays. The second withdraws marketing e-mail for C-30077.
A changed e-mail, phone or name
When a row names the customer by customer_id and carries an e-mail, a
phone, a first name or a last name that differs from what their contact
holds for this brand, the contact takes the new value. A row found by
e-mail alone can change the phone and the names, not the e-mail.
Only a customers row changes what a contact holds. The e-mail an event
or a record names (an event's customer_email, or a customer_id that
is an e-mail address) never replaces the e-mail a contact holds: it only
fills an empty one. Send a changed e-mail in the customers list.
- Only a value that reads as one replaces what a contact holds: an
e-mail address, a phone in international form, a name with at least
one letter. A first or last name such as
-,?orn/aleaves the held name as it is, and the row counts inkept_fields. An e-mail or a phone that cannot be read refuses the row (Customers). - A new e-mail or phone starts as any new address starts: it takes the
consent the same row states (
email_consentorsms_consent, true or false), and otherwise it is Not granted, unless the person opted out themselves at the one it replaces (the next two points). It never takes over a yes, a bounce or a withdrawal your team made by hand at the address it replaces. - If the person unsubscribed or complained at the e-mail address it
replaces, the new address is unsubscribed too, whatever the row
states; a
trueon that row, or in a later request, is counted inconsent.kept. - If the person sent STOP or complained at the phone it replaces, the new
phone carries the same opt-out, whatever the row states; a
trueon that row, or in a later request, is counted inconsent.kept. - If that cannot be checked just now, the contact keeps the e-mail or
phone it held and the request is answered
consent_not_recorded(503); send it again. - A
falseon that row reaches the old address too: nobody who said no is reachable for marketing at either. - A block keeps following the person. A block recorded against the
customer_idapplies to the new address, because every send checks the person's id beside the address; a block that names the old address stays. - When the new e-mail already belongs to another customer of the brand,
in any letter case, the row is refused (
email_of_another_customer) and nothing is merged. That includes a contact made earlier from an event or a form that carried that e-mail and nocustomer_id: the row is refused until the two contacts are merged on the Customers page. A row refused because its e-mail belongs to another customer changes no contact, but itsfalsestill applies to the e-mail and phone the contact of its owncustomer_idholds; it never reaches the other customer's contact. Ablockon that row is still recorded against what the row names, that e-mail included (Blocking a person, below).
{
"customers": [
{
"customer_id": "C-20418",
"email": "anna@newdomain.example",
"email_consent": true
}
]
}
The answer counts what was replaced in updated_fields.
The customer's record always takes the newest values. Its name is set
when a row carries both first_name and last_name; a row with only one
of them stores it as a field of the record and leaves the name as it
was.
Phones
Send phones in international form with the country code:
+14155550123, +1 (415) 555-0123 and 0014155550123 are the same
number. A number without its country code is refused, because guessing
the country could put another person's real number on a list.
{
"customers": [
{ "customer_id": "C-20418", "phone": "0777 123 456" }
]
}
Attributes
Attributes are your own fields about the person: a plan, a tier, a favourite store, a count.
- A name holds letters, digits, underscores and dashes, at most 60 characters, and starts with a letter or a digit.
- A value is text, a number,
true,falseornull. A list or an object refuses the row (attribute_value_unreadable). - Values are stored as you send them: a JSON number is a number and text
stays text. Send counts and amounts as JSON numbers, and yes or no as
trueandfalse. - A few names are kept by the profile for itself. An attribute with one
of them is stored as
customer_<name>, with a hint:email,external_id,first_name,last_name,company,phone,status,timezone,id,user_id,client_id,source,created_at,updated_at,attributes,is_test,external_id_client,visitor_id,visitor_id_client,visitor_ids,visitor_ids_by_client,customer_ids,sources,email_client,email_source,sid_client,sid_source. - An attribute whose name reads like consent (
newsletter_opt_in) or like a block (blocked,unsubscribed,do_not_contact) is stored as a profile value and changes nobody's consent or block; a hint says so. Useemail_consent,sms_consentandblock. - A value that changes with every transaction (a balance, a last order date) belongs on the event, not in an attribute: on the built-in warehouse every change of an attribute is also kept on the person's history as an event and counts toward your plan's events (What counts toward your plan's volume).
{
"customers": [
{
"customer_id": "C-20418",
"attributes": { "favourite_stores": ["ST-07", "ST-11"] }
}
]
}
Consent
Your system is the source of truth for the marketing consent it sends, in both directions, as a connected database is.
| You send | Someone new to the brand | Someone already on the brand |
|---|---|---|
true | Granted | Granted, unless something stands in the way (below) |
false | Not granted | Marketing on that channel is withdrawn, for the address on the row and the address their contact holds |
left out or null | Not granted | Nothing changes |
email_consent and sms_consent take true, false, 1, 0,
"true", "false", "yes", "no", "1" and "0". Anything else
refuses the row (consent_unreadable).
- A later true gives back what this API withdrew, whichever of the brand's keys sent the no.
- What the person did themselves always stands. An unsubscribe, a
STOP, a bounce or a complaint is never overridden, and neither is a
withdrawal your team made by hand: such a
trueis counted inconsent.kept. A no that came another way (a connected database, a file) is not given back by this API either. - Not granted stops marketing only. Service messages still reach the person.
- Consent sent for a person with no e-mail (or no phone, for
sms_consent), on the row or on record, changes nothing and is counted inconsent.no_address, with a hint. - A
truenever lifts a block.
{
"customers": [
{ "customer_id": "C-20418", "email_consent": "subscribed" }
]
}
Blocking a person
There are two ways to block a person through this API, and each is lifted its own way. Blocks are per brand.
In the customers list
block states whether your system blocks the person. It is the truth in
both directions.
block | What it does |
|---|---|
"all" | Nothing is sent to the person: the Blacklist's Blocks everything. |
"marketing" | No marketing is sent; service messages still go: Suppresses marketing. |
"none" | Lifts what the customers list of this brand put on this customer. |
left out or null | Says nothing and changes nothing. |
true, 1, "1", "true", "yes" and "y" read as "all";
false, 0, "0", "false", "no", "n" and "" read as "none".
Any other value reads as "all", the safe side, with a hint. Case does
not matter. block_reason is kept on the entry.
{
"customers": [
{
"customer_id": "C-30077",
"block": "all",
"block_reason": "Asked not to be contacted"
},
{ "customer_id": "C-41150", "block": "marketing" },
{ "customer_id": "C-52203", "block": "none" }
]
}
- A block is recorded against every identifier on the row (the
customer_id, the e-mail, and the phone in every form a send may hold it, or as written when it is not in international form) and against the e-mails, phones and ids the brand's own contacts carry with any of them. Two kinds of row are the exception: a row whose e-mail belongs to another customer of the brand (email_of_another_customer), and a refused row that names both acustomer_idand an e-mail. That e-mail may be another customer's, so the row's block goes on what the row names and is not followed through the contacts: nothing another customer's contact carries is added. Every block goes on the brand's lists "Suppression feed (customers list)" (all) and "Marketing opt-out feed (customers list)" (marketing). - Blocks are recorded before anything else of the request. A row refused
for another reason still has its block recorded when it carries an
identifier that can be read, and the refusal says so, unless a later
row for the same customer in the request is accepted with a looser
block (
"marketing"after"all", or"none"): the later row wins, and the refusal does not say the block was recorded. - A refused row never moves a person from one list to the other and
never lifts or weakens a block: its block is added under its own
identifiers, and a
"none"on it lifts nothing. - A change from
alltomarketing, or back, moves the person from one list to the other. A move from"marketing"to"all"lets nobody back in, so it never trips the brake (below). When a move cannot be made just now, an"all"row leaves the person on both lists, blocked from everything as the row says, and is not refused; a"marketing"row leaves the person on the list that blocks everything and is refused (lift_not_recorded): send it again. - Each block is kept under the
customer_idit was sent with, else under the e-mail, and"none"lifts what was kept under the same one. A"none"with only an e-mail, for a person blocked under theircustomer_id, lifts nothing, and the answer says so with a hint: send it with thecustomer_id. The hintblock_noneis given only when such a"none"lifted nothing and the customers list of the brand holds a block for that e-mail under acustomer_id. "none"lifts the entries the customers list of this brand added under this customer, including the ones it found through the brand's contacts. An identifier that another customer's block also put there stays blocked.
What a push never lifts: a block your team added on the Blacklist page, the person's own unsubscribe, STOP or complaint, entries added by suppress events (an unsuppress event lifts those), entries of another brand or of another source (a connected database's lists, a file), and anything about a person erased on request.
A large lift is held. The brake is judged per request: if one
request would let more than 25 people back in from a list, and they are
more than 10% of the people on that list, nobody is let back in from
that list by that request, and the answer says so. Blocks added by the
same request still apply. Each such row is refused with lift_held
(counted in lifts_held), and the rest of each row was applied, so such
a request is answered 200 with partly_stored, never 422. Requests
of 25 people or fewer are not held: an export that sends "not blocked"
for many people in requests that small is not stopped by the brake. If a
large lift is right, a person lifts it on the Blacklist page. Only
what lets a person back in counts: a "none", and the move off the list
that blocks everything that comes with "marketing". When the brake
holds the marketing list, a person moving from "marketing" to "all"
stays on both lists, blocked from everything, and that row is not
refused. A dry run judges the brake as the real request does.
A lift that fails leaves the person blocked, and that row is refused
(lift_not_recorded); the rest of the row was applied, as with
lift_held. Send it again. A block that cannot be recorded stops the
whole request (503 blocks_not_recorded): blocks recorded before it
stand, and nothing else of the request is written.
Suppress and unsuppress events
An event with event_type suppress or unsuppress is an operation,
not an event: it is not stored as an event and is counted in
block_operations.
{
"events": [
{
"event_type": "suppress",
"event_id": "suppress:7781",
"customer_id": "C-30077",
"customer_email": "j.doe@example.com",
"phone": "+44 20 7946 0958",
"enforcement": "block_all",
"reason": "Requested by phone"
},
{
"event_type": "unsuppress",
"event_id": "unsuppress:7790",
"customer_id": "C-61092"
}
]
}
- Name the person by
customer_id,customer_emailorphone, any or all of them; with none, the row is refused (block_without_person).event_idmay be left out. enforcementisblock_all(the default),suppress_marketingorflag_only. Any other value reads asblock_all, with a hint.phone,enforcementandreasonmay also sit insideproperties.- A suppress records every identifier it names, a phone in international form in every form a send may hold it (a phone in another form as written), on the brand's lists "Suppression feed (webhook)", "Marketing opt-out feed (webhook)" and "Watch list feed (webhook)", by enforcement.
- An unsuppress lifts what suppress events put on this brand's "(webhook)" lists, for the identifiers it names, and nothing else.
- The same identifier suppressed and unsuppressed in one request stays blocked, with a hint.
Events marked as a suppression event
An event whose type the brand marked as a suppression event on
Data → Events is stored as an event and blocks its person as a
suppress with block_all does, with a hint. It counts under accepted
and in blocks.added, not in block_operations.
How each block is lifted
| Block | Lists | Lifted by |
|---|---|---|
block in the customers list | "Suppression feed (customers list)", "Marketing opt-out feed (customers list)" | "block": "none" for the same customer, from the same brand; or a person on the Blacklist page |
| A suppress event, or a marked suppression event | "Suppression feed (webhook)", "Marketing opt-out feed (webhook)", "Watch list feed (webhook)" | An unsuppress event naming the identifier; or a person on the Blacklist page |
| Added by your team, or the person's own unsubscribe, STOP or complaint | Never by a push |
The Blacklist page is under Audience → Retention → Blacklist. More on the levels in Unsubscribes, opt-outs, and the blacklist.
Records
A record is anything else you keep: a product, a store, a subscription.
{
"records": [
{
"record_type": "product",
"record_id": "SKU-1042",
"name": "Trail running shoe",
"status": "active",
"properties": { "category": "footwear", "price": 129.00, "in_stock": true }
},
{
"record_type": "store",
"record_id": "ST-07",
"name": "Riverside",
"properties": { "city": "Lyon", "opened_on": "2024-03-01" }
},
{
"record_type": "subscription",
"record_id": "SUB-5531",
"status": "active",
"customer_id": "C-20418",
"created_at": "2026-01-15T08:00:00Z",
"properties": { "plan": "annual", "seats": 3 }
}
]
}
The fields are exactly these; any other name refuses the row
(unknown_field). Your own fields go inside properties.
| Field | Type | Required | How it is read |
|---|---|---|---|
record_type | text | yes | What kind of thing this is: product, store, subscription. Cleaned as event_type is, at most 60 characters. customer is refused: customers go in the customers list. A type starting with item: is refused for now (catalog_not_open): send catalogs as a file on the Data page. |
record_id | text or number | yes | Your own id of it, at most 200 characters. |
name | text | no | At most 200 characters. |
status | text | no | Lower-cased, at most 200 characters. |
customer_id | text or number | no | Whose record it is. That person becomes a contact of the brand with nothing assumed about consent, as an event's person does. |
created_at | time | no | It only ever moves earlier. |
properties | object | no | The record's fields. Names may not start with an underscore (property_name_unreadable). |
propertiesmerge name by name;nullempties one value. A field left out is kept.- The same record twice in one request is applied in order as one,
counted in
merged. - One request may carry records of several types.
- A record's fields are never copied to a person: a value about a person
goes in the customer's
attributes.
{
"records": [
{ "record_type": "customer", "record_id": "C-20418", "name": "Anna Novak" }
]
}
Times
event_time and created_at are read strictly by their shape:
- ISO 8601 with a zone:
2026-11-13T10:00:00Zor2026-11-13T11:00:00+01:00, with or without fractions of a second, with aTor a space. Read exactly. - A time without a zone:
2026-11-13 10:00:00,2026-11-13T10:00, or a date alone,2026-11-13. It is read in the request'stime_zone; without one, the row is refused (time_without_zone). - Unix time, as a JSON number or as text of digits only: 10 digits
are seconds (
1794564000), 13 digits are milliseconds (1794564000000). Any other number of digits is refused (time_not_unix). - Anything else is refused (
time_unreadable), and so is a time without a zone whose date does not exist, such as2026-02-31 10:00.
Stored times are UTC. An event dated more than a day ahead of its arrival gets a hint.
Name the zone once for the whole request when your system writes local times:
{
"time_zone": "Europe/Prague",
"events": [
{
"event_type": "payment",
"event_id": "payment:90074",
"event_time": "2026-11-13 11:00:00",
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
}
]
}
{
"events": [
{
"event_type": "payment",
"event_id": "payment:90072",
"event_time": "2026-11-13 10:00:00",
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
}
]
}
{
"events": [
{
"event_type": "payment",
"event_id": "payment:90073",
"event_time": 17945640000,
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
}
]
}
{
"events": [
{
"event_type": "payment",
"event_id": "payment:90075",
"event_time": "13/11/2026 10:00",
"customer_id": "C-20418",
"amount": 25,
"currency": "EUR"
}
]
}
Numbers and money
amountis the event's money. Send it as a JSON number (49.90) where you can; it may be negative. Text is read too: machine text such as"1299.00"reads its dot as a decimal point, and text written for people, such as"1 250,50", is read by what it says, then by this connection's earlier values, then by how your brand writes numbers.- An amount that cannot be read never refuses the event. The event is
stored with no amount, your text is kept, and the answer counts it in
amounts_unread, with a line inamounts_note. It is never stored as 0. currencyis three letters, stored in upper case. Left out, the event takes the currency the amount's own text names ("100 EUR"), else none; a currency is never filled in for you.- Only
amountis money. An event with noamountthat carriesvalue,price,total,revenue,sumorcostgets a hint. - An event's other fields that hold text with a digit are read as
numbers when their writing is certain, as described in
Connecting your data;
the answer counts what was not read in
properties_unreadandproperties_not_read, with a line inproperties_note. - Customers'
attributesand records'propertiesare stored as sent. Send counts and amounts as JSON numbers, and yes or no astrueandfalse.
{
"events": [
{
"event_type": "payment",
"event_id": "payment:90076",
"event_time": "2026-11-13T10:00:00Z",
"customer_id": "C-20418",
"amount": 25,
"currency": "euro"
}
]
}
The answer
Every answer is JSON. A request that was read answers 200 with what
happened to each row:
{
"result": "stored",
"dry_run": false,
"request_id": "webhook_1794564251000418273650912",
"brand": {
"client_id": "6f1c2a9e-0b7d-4c1e-9a55-2f3d8c7b1e40",
"name": "Northwind EU"
},
"events": {
"received": 3, "accepted": 3, "new": 2, "replaced": 1, "unchanged": 0,
"refused": 0, "refused_rows": [], "repeated": 0, "erased": 0, "erased_rows": [],
"block_operations": 0,
"blocks": { "added": 0, "already_blocked": 0, "lifted": 0 },
"without_customer": 0, "without_time": 0
},
"customers": {
"received": 1, "accepted": 1, "merged": 0, "refused": 0, "refused_rows": [],
"erased": 0, "erased_rows": [], "created": 1, "updated": 0,
"updated_fields": { "email": 0, "phone": 0, "first_name": 0, "last_name": 0 },
"values_unread": 0,
"consent": { "granted": 1, "withdrawn": 0, "kept": 0, "no_address": 0 },
"blocks": { "added": 0, "already_blocked": 0, "lifted": 0, "none_sent": 0 },
"lifts_held": 0, "kept_fields": 0, "held_by_another_brand": []
},
"records": {
"received": 2, "accepted": 2, "merged": 0, "refused": 0, "refused_rows": [],
"erased": 0, "erased_rows": [], "held_by_another_brand": []
},
"hints": []
}
Some rows refused, the rest stored, still 200:
{
"result": "partly_stored",
"dry_run": false,
"request_id": "webhook_1794564252113418273651184",
"brand": {
"client_id": "6f1c2a9e-0b7d-4c1e-9a55-2f3d8c7b1e40",
"name": "Northwind EU"
},
"events": {
"received": 5, "accepted": 2, "new": 2, "replaced": 0, "unchanged": 0,
"refused": 2, "repeated": 1, "erased": 0, "erased_rows": [],
"block_operations": 0,
"blocks": { "added": 0, "already_blocked": 0, "lifted": 0 },
"without_customer": 1, "without_time": 0,
"refused_rows": [
{
"index": 1,
"id": "1002",
"code": "id_used_by_another_type",
"field": "event_id",
"message": "event_id \"1002\" is already stored for this brand as a \"payment\" event, and this row is \"refund\". One id names one event across all event types of a brand. Put the type in the id, for example \"refund:1002\"."
},
{
"index": 3,
"id": "purchase:A-7733",
"code": "time_without_zone",
"field": "event_time",
"message": "event_time \"2026-11-13 10:00:00\" has no time zone. Send 2026-11-13T10:00:00Z or 2026-11-13T11:00:00+01:00, or name the zone once for the whole request: \"time_zone\": \"Europe/Prague\"."
}
]
},
"hints": [
{
"list": "events",
"code": "customer_field_not_read",
"field": "user_id",
"rows": 1,
"message": "1 event names no customer but carries \"user_id\". If that is your customer's id, send it as customer_id. An event without a customer is stored, but it is on nobody's timeline and starts no journey."
},
{
"list": "events",
"code": "repeated_in_request",
"field": "event_id",
"rows": 1,
"message": "1 row repeated an event_id that comes again later in the same request. The later row was kept."
}
]
}
The top level.
result:storedwhen rows were accepted and none was refused, erased or over a limit;partly_storedwhen rows were accepted and others were not;nothing_storedwhen no row was accepted. A customers row refused only for its lift (lift_heldorlift_not_recorded) had the rest of it applied: it is listed inrefused_rowsand counted inrefusedlike any refused row, and it counts as stored work forresultand the status, so such a request ispartly_stored.dry_run:trueon a dry run, with anotebeside it.request_id:webhook_followed by 25 digits. Every event row the request stored carries it, it is what Remove a push takes, and Activity shows the first and last request id of each line: keep each answer'srequest_id. For the requests in between, an owner or admin can remove what a brand received in a time window (Taking a push back). Every answer once the key is accepted carries it in theX-Request-Idheader, the address pin's403and the limits'429and503included.brand: the brand the request stored under.- One object for each list the request carried, and only those.
hints: what was stored but may not be what you meant.notice: only for a connection that still uses a key in the address.
Every list of events, customers and records has received,
accepted, refused with refused_rows (every refused row, not a
sample), and erased with erased_rows ([{ "index", "id" }]).
events adds new (stored for the first time), replaced (a stored
event that changed), unchanged (identical to the stored one: nothing
was written), repeated, block_operations (suppress and unsuppress
rows), blocks (added, already_blocked, lifted),
without_customer, without_time, and when they apply
amounts_unread, amounts_note, properties_unread,
properties_not_read, properties_note, over_limit and limit_note.
customers adds merged, created and updated (contacts),
updated_fields (how many e-mails, phones, first and last names
replaced what a contact held), values_unread, consent (granted,
withdrawn, kept: a true that a person's own no outranked,
no_address), blocks (added, already_blocked, lifted,
none_sent), lifts_held, kept_fields (customers whose contact kept
a value the row differed on), held_by_another_brand
([{ "index", "id" }]), and when they apply over_limit,
records_not_stored (customer records the plan had no room for: their
contacts were made, and the result is partly_stored) and
limit_note.
records adds merged, held_by_another_brand, and when they apply
over_limit and limit_note.
plans and actuals have received, accepted, cleared,
refused and refused_rows.
The arithmetic always holds:
- events:
received=accepted+block_operations+refused+repeated+erased+over_limit, andaccepted=new+replaced+unchanged; - customers:
received=accepted+merged+refused+erased+over_limit.
A refused row is
{ "index", "id", "code", "field", "message" }: index is its position
in its list as you sent it, from 0; id is its event_id, its
customer_id or e-mail, or record_type:record_id, else null;
field names the field at fault, or null.
A hint is { "list", "code", "field", "rows", "message" }, one for
each code and field, with how many rows it is about. A hint about values
that were changed names up to three of them.
When nothing was accepted and rows were refused, the answer has the
same shape with the status 422, and error and message beside
result, unless a customers row was refused only for its lift: that
request is 200 with partly_stored (above). When only refusals
happened, the message is "Every row of this request was refused, so
nothing was stored. Each refused row says why. Correct them and send the
request again." When rows were also over what the plan keeps or the most
the built-in warehouse keeps for one account, about people erased on
request, or carried a block or a no to marketing that was recorded, it
reads "Nothing of this request was stored whole: <n> rows refused (each
says why), <n> rows over what this account's plan keeps, <n> rows over
the most the built-in warehouse keeps for one account and <n> rows about
people erased on request. The blocks and the no to marketing on the
refused rows were recorded (the no for the contacts of their
customer_id); nothing else was stored. Correct the refused rows and send
them again.", each part said only when it applies. With only blocks
recorded, the sentence about them reads "The blocks on the refused rows
were recorded; nothing else was stored."; with only a no recorded (a
false on a row refused because its e-mail belongs to another
customer), "The no to marketing on the refused rows was recorded for the
contacts of their customer_id; nothing else was stored." A dry run
records nothing, so it never says either:
{
"error": "nothing_stored",
"message": "Every row of this request was refused, so nothing was stored. Each refused row says why. Correct them and send the request again.",
"result": "nothing_stored",
"dry_run": false,
"request_id": "webhook_1794564253420418273650377",
"brand": {
"client_id": "6f1c2a9e-0b7d-4c1e-9a55-2f3d8c7b1e40",
"name": "Northwind EU"
},
"events": {
"received": 1, "accepted": 0, "new": 0, "replaced": 0, "unchanged": 0,
"refused": 1, "repeated": 0, "erased": 0, "erased_rows": [],
"block_operations": 0,
"blocks": { "added": 0, "already_blocked": 0, "lifted": 0 },
"without_customer": 0, "without_time": 0,
"refused_rows": [
{
"index": 0,
"id": "payment:90072",
"code": "time_without_zone",
"field": "event_time",
"message": "event_time \"2026-11-13 10:00:00\" has no time zone. Send 2026-11-13T10:00:00Z or 2026-11-13T11:00:00+01:00, or name the zone once for the whole request: \"time_zone\": \"Europe/Prague\"."
}
]
},
"hints": []
}
A request that could not be read at all answers
{ "error": "<code>", "message": "<sentence>" } with its status, plus
allowed for unknown_list and brands for client_id_required. No
answer ever carries a database's own error text.
A dry run
?dry_run=1 reads and judges everything a real request would: every
field of every row, the look for stored ids (so new, replaced,
unchanged and id_used_by_another_type are true), the check for
people erased on request, the plan's room for events, an e-mail that
belongs to another customer, records another brand holds, and the brake
on a large lift (lift_held rows and lifts_held come back as the real
request would give them). It stores nothing: no event, record, contact,
consent, block, link between identifiers or Activity line. It counts
against the rate limit.
The answer has the same shape, with "dry_run": true and
"note": "This was a dry run. Nothing was stored.".
customers.created, customers.updated, customers.kept_fields and
customers.updated_fields are null. A dry run does not judge which
values a contact keeps or takes, whether the plan has room for more
contacts and records, whether a lift fails to land, or anything another
request changes in between; the consent and blocks counts say only
what the rows ask for. For example, a false for someone new to the
brand counts in consent.withdrawn on a dry run, while the real request
counts 0 there, because a new person's no starts as Not granted.
Plans and actuals are read and judged only.
When something goes wrong
Every refused request answers JSON with error (the code) and
message (what to do). Retry-After comes with every 429 and every
503.
| Code | Status | When | What to do |
|---|---|---|---|
invalid_organization | 400 | The address does not end with your organisation id | Fix it: copy the address from Data → Push |
body_shape | 400 | The body is not one JSON object with a list, or it is form-encoded | Fix it |
unknown_list | 400 | A key at the top is not one of the lists | Fix it: allowed lists the names |
list_not_array | 400 | A list is not a JSON list | Fix it |
empty_request | 400 | No row in any list | Fix it |
client_id_required | 400 | Several brands and none named | Fix it: name one from brands |
client_id_conflict | 400 | Two different brands named | Fix it: name one |
no_brand | 400 | The organisation has no brand | Create one, then send again |
time_zone_unknown | 400 | time_zone is not a time zone name | Fix it |
unauthorized | 401 | No key, a key in the address, or a key that is wrong, expired, revoked or of another kind | Fix it: issue a key on Data → Push |
allowance_reached | 402 | The request carried only events, and the plan holds all the events it keeps | Not until the plan changes on the Billing page; at the most the built-in warehouse keeps for one account, we will be in touch about a dedicated warehouse |
wrong_organization | 403 | The key belongs to another organisation | Fix it |
missing_scope | 403 | The key cannot send data in | Fix it: issue a key on Data → Push |
ip_not_permitted | 403 | The key is pinned to other addresses | Fix it: send from a pinned address, or change the pin |
wrong_profile | 403 | The key is for another brand | Fix it: leave client_id out, or use the key's own brand |
unknown_brand | 404 | client_id is not a brand of your organisation | Fix it |
method_not_allowed | 405 | Not a POST | Fix it |
too_many_rows | 413 | A list holds more rows than it may | Split it and send the parts |
body_too_large | 413 | The request is over 4 MB | Split it and send the parts |
nothing_stored | 422 | Nothing was accepted and rows were refused, none of them only for its lift | Fix the refused rows, then send them again |
rate_limited | 429 | Too many requests for this key, or too many rows for this key or for your organisation's keys together | Send it again after Retry-After seconds; higher limits are set on request through support@theaicmo.com |
not_finished | 500 | Something failed on our side; part may be stored | Send it again: stored rows are replaced, never doubled |
blocks_not_recorded | 503 | A block could not be recorded; blocks recorded before it stand, and nothing else was stored | Send it again after Retry-After seconds |
consent_not_recorded | 503 | A consent decision, a customer's new e-mail or phone, or a new contact could not be recorded; no event was stored | Send it again after Retry-After seconds |
erasure_check_unavailable | 503 | The check for people erased on request could not run; nothing was stored | Send it again after Retry-After seconds |
rate_limit_unavailable | 503 | The limits could not be checked; nothing was stored | Send it again after Retry-After seconds |
brand_lookup_failed | 503 | The brand could not be checked; nothing was stored | Send it again after Retry-After seconds |
unavailable | 503 | Temporarily unavailable; the message says what, if anything, was stored | Send it again after Retry-After seconds |
When a plan with a fixed number of events has no room left, events that
would pass it are not stored: the events list counts them in
over_limit, with limit_note, and the request's customers, records
and blocks are stored as usual. Only a request that carried nothing but
events (and suppress or unsuppress events) answers 402. An account on
the built-in warehouse that holds the most it keeps for one account,
2,000,000 events, is told so in the 402 (or in the events list's
limit_note), with no Billing step: we will be in touch about a
dedicated warehouse.
Refused rows. These codes refuse one row; the rest of the request goes on. Each message says what to change.
| Code | List | What is wrong |
|---|---|---|
row_not_object | any | The row is not a JSON object |
row_too_large | any | The row is over 64 KB as JSON |
row_too_large_for_plan | events | On the smallest plan, the event's own fields are over 32 KB |
id_too_long | any | An id is over 200 characters |
id_unsafe_number | any | An id is a number too large to be exact |
id_unreadable | any | An id or a text field is an object, a list, or true or false; or an id holds a character that cannot be stored |
value_too_long | any | A text is longer than it may be: a name or a status over 200 characters, an e-mail or a phone over 200 |
value_unreadable | any | A field holds a character that cannot be stored (a NUL character or half of an emoji); the message names the field |
time_without_zone | any | A time without a zone, and no time_zone |
time_unreadable | any | A time that cannot be read |
time_not_unix | any | A number that is not 10 or 13 digits |
changed_meanwhile | events | The stored event changed while the request was stored |
properties_not_object | events, records | properties is not an object |
event_type_missing | events | No event_type |
event_type_unreadable | events | event_type is empty once cleaned, or too long |
event_id_missing | events | No event_id |
id_used_by_another_type | events | The id is stored under another type |
id_twice_with_two_types | events | The id comes twice under two types |
customer_email_unreadable | events | customer_email is not an e-mail address |
currency_unreadable | events | currency is not three letters |
step_of_incomplete | events | step_of lacks a part |
step_of_itself | events | A step has its record's type |
block_without_person | events | A suppress or unsuppress names nobody |
lift_not_recorded | events, customers | A lift could not be recorded; the person stays blocked |
lift_held | customers | A lift was held, because the request would let in too many at once |
customer_identity_missing | customers | No customer_id and no email |
email_unreadable | customers | email is not an e-mail address |
phone_unreadable | customers | phone is not in international form |
unknown_field | customers, records | A field that is not in the list |
consent_unreadable | customers | A consent value that is not true or false |
email_of_another_customer | customers | The e-mail belongs to another customer of the brand |
attributes_not_object | customers | attributes is not an object |
attribute_name_unreadable | customers | An attribute name that cannot be stored |
attribute_value_unreadable | customers | An attribute holds a list or an object |
record_type_missing | records | No record_type |
record_type_unreadable | records | record_type is empty once cleaned, or too long |
record_type_is_customer | records | record_type is customer |
record_id_missing | records | No record_id |
property_name_unreadable | records | A property name starts with an underscore |
catalog_not_open | records | A type starting with item: |
plan_row_refused | plans, actuals | A plan or reported figure the reader cannot store; the message says why |
What a request does, in order. This tells you what was stored when something failed part way:
- The key, its address pin and the rate limits. Every request counts, refused ones too.
- The body's shape and size, the rows a minute, the brand and
time_zone. - Every row of every list is read and judged. Nothing is written yet.
- One check for people erased on request, over every identifier.
- Blocks: customers rows with a block, suppress events and marked
suppression events. Then lifts:
"block": "none"and unsuppress events. - Customers, records and the contacts of everyone the events name, with their consent.
- Events: compared with what is stored, then new ones written and changed ones updated.
- Plans and actuals, then the answer.
Limits and sending in real time
Send as things happen, in small requests: a request every second or so, or every few hundred rows, rather than one large request a day.
| Limit | Value |
|---|---|
| Rows in each of events, customers and records | 1,000 a request |
| Plans | 2,000 a request |
| Actuals | 5,000 a request |
| A request | 4 MB |
| A row | 64 KB as JSON |
| An event's own fields, on the smallest plan | 32 KB |
event_id, customer_id, record_id | 200 characters |
event_type, record_type, an attribute name | 60 characters |
first_name, last_name, name, status | 200 characters |
step | 60 characters, longer is cut |
block_reason, reason | 500 characters, longer is cut |
| Requests for one key, by default | 600 a minute, 900,000 a day |
| Rows for your organisation, all its keys together, by default | 60,000 a minute |
| Requests for a connection with an old key in the address | 120 a minute, 10,000 a day |
Requests per key, rows per organisation. Requests a minute and a day are counted for each key. Rows a minute are counted for your organisation, across all its keys, so a second key does not add rows. A key is issued with the default limits above. Higher limits are set on request: write to support@theaicmo.com, naming the key. A raised key raises the rows a minute of your whole organisation, and each key still sends no more than its own. A new key starts at the default limits, also one that replaces a raised key: name the new key when you write.
An older key keeps the 100,000 requests a day it was issued with, and
X-RateLimit-Limit-Day says which a key has: issue a new key on Data →
Push for the higher limit. A connection still using an old key in the
address (an old connector key) has 120 requests a minute and 10,000 a
day; a key issued on Data → Push lifts them. Its rows count toward
your organisation's rows a minute, as every key's do.
Every answer after the rate limit check carries X-RateLimit-Limit-Minute,
X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day and
X-RateLimit-Remaining-Day. They always state the key's own requests a
minute and a day, a raised key's included. Over a limit, the answer is
429 with Retry-After:
{
"error": "rate_limited",
"message": "Too many requests for this key. Wait retry_after_seconds, then send the same request again.",
"retry_after_seconds": 12,
"limit": "requests_per_minute",
"remaining": { "minute": 0, "day": 871240 }
}
limit is requests_per_minute, requests_per_day or
rows_per_minute. Wait the seconds it says, then send the same request
again. Over the rows a minute, the message says which was reached, the
key's own rows a minute or your organisation's, all its keys together,
and names that number:
{
"error": "rate_limited",
"message": "This key sent more than 60,000 rows in a minute. Wait retry_after_seconds, then send the same request again.",
"retry_after_seconds": 21,
"limit": "rows_per_minute",
"remaining": { "minute": 542, "day": 871240 }
}
{
"error": "rate_limited",
"message": "Your organisation's keys together sent more than 60,000 rows in a minute. Rows a minute are counted for the organisation, across all its keys. Wait retry_after_seconds, then send the same request again.",
"retry_after_seconds": 18,
"limit": "rows_per_minute",
"remaining": { "minute": 571, "day": 893115 }
}
Sending again, and order
No idempotency key is needed: every list is keyed (events by
event_id, customers by customer_id or email, records by type and
id, plans and actuals by line and period). After a timeout, a 429, a
500 or a 503, send the same request again, whole.
A request refused with 429 stored nothing, the opt-outs and blocks it
carried included: wait Retry-After seconds and send the same request
again. A 400, 401, 403, 404, 405 or 413 stored nothing either.
A 500 or a 503 can come after part of the request was stored, blocks
first (see What a request does, in order); sending the same request
again doubles nothing. Send a refused request again before any newer
request about the same people. The last request to arrive wins, and a
smaller request can pass while a larger one waits out its Retry-After,
so an older request sent last puts back an older consent or lifts a newer
block.
Allow each request up to 300 seconds before treating it as timed out. A request that timed out on your side may still be finishing, so wait that long before sending it again. Small requests answer in seconds.
- A re-sent event keeps its first arrival: it never starts a journey again and never counts twice, and an identical one writes nothing.
- A re-sent event without
event_timekeeps the time stored the first time, so a retry never moves an event. - A retry is safe; a replay out of order is not. The last request to arrive wins, so an old request sent after a newer one puts the old values and the old consent back.
- Do not send the same customer in two requests at the same moment.
Continuing data that came in another way. An event replaces a stored
one only under the same event_id in the same brand. Rows a file or a
connected database stored carry ids of their own: to carry on from them,
send those same ids, or agree a moment from which your system pushes and
the old way stops.
What counts toward your plan's volume
- Every stored event counts once, when it first arrives, whatever date it carries. A re-sent event does not count again.
- On the built-in warehouse, each change to a customer's e-mail, phone, names or attributes is kept on their history as an event, and it counts toward your plan's events like any other event. Resending values that did not change counts nothing. A first customers push that changes many people can use a large part of a plan with a fixed number of events.
- Records, blocks, plans and actuals are not events.
- A value about a person that changes with every transaction (a balance, a last order date) belongs on the event, not in an attribute.
- An account with a contract number is never refused; its owner is told at 80% and at 100%.
- On a plan with a fixed number of events, events that would pass it are
not stored, and the answer says so (
over_limit,limit_note, or402when the request carried only events).
One customer across your brands
A customer_id is one customer across all brands of your organisation,
and so is a record's type and id. Contacts, consent, blocks and
attributes are per brand.
The customers and records lists never write into a record another brand
of your organisation holds: the row is listed in held_by_another_brand,
and the contact, consent, blocks and attributes it carries for your
brand are stored. If your brands number their own customers
independently, put the brand in the id (EU-20418, US-20418).
People erased on request
People erased on request stay erased. Each request checks every
identifier it carries (an event's customer_id, customer_email and a
customer_email inside properties; a customer's customer_id and
email; a record's record_id and customer_id) against the people
erased on request. A row about an erased person is not stored, records
no block, and is listed in erased_rows and counted in erased. A
request whose only rows were about erased people answers 200 with
nothing_stored. When the check cannot run, the answer is 503 erasure_check_unavailable and nothing of the request was stored: send it
again.
Taking a push back
Every answer once the key is accepted carries its request id (request_id). On Data → Push, Remove a
push takes a request id and removes the event rows that request stored
or changed; an owner or admin can also remove what a brand received in a
time window, from every key or from one. Check counts the rows
first; Remove removes them.
- It removes event rows only. A row the request changed does not go back to its earlier version: send the earlier one again.
- Customers, records, consent and blocks of the same request are not undone.
- Requests whose id is not
webhook_followed by 25 digits were made before this way existed, and cannot be taken back this way. - It is done by a person signed in to the product. A key can never delete.
Checking that it arrived
- The answer says what happened to every row.
- Data → Activity shows the pushes. Every request is added up into one line per key and brand, written within minutes after the requests stop and at least every hour; a key's first request of the day for a brand (and its first after one of our updates), and a request with refused rows or a failure, also get a line of their own at once. Each line shows its first and last request id.
- Customers: search the
customer_idor the e-mail. The person's page shows the details and consent you sent, and their events on its Activity tab. - Data → Warehouse lists every event type as it arrives.
Plans and reported figures
plans (your budget, forecast and target) and actuals (the figures
only your accounting knows) go to the same address with the same key and
brand, on their own or beside the other lists. Their fields are in
Connecting your data.
Before you go live
- A dry run of a real request comes back clean: no refused rows, and every hint read.
- Every
event_idis your own id with the type in front. - Every time carries a zone, or the request names its
time_zone. - The answer's
brandis the brand you mean. - Consent and blocks are sent in the customers list before the first message goes out.
- Phones are in international form, and numbers are JSON numbers.
- Your system allows each request up to 300 seconds, and retries on a
timeout, a
429, a500and a503, with the same request.