Documentation overview

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

  1. 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.

  2. Copy the address. The card shows the full address for the brand:

    text
    https://api.theaicmo.com/api/warehouse/ingest/<organisation id>?client_id=<brand id>
    
  3. 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=1 reads and judges everything and stores nothing.

    bash
    curl -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.json
    

    The 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:

text
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:

  1. The key was issued for a brand: that brand. A request that names another brand is refused with 403 wrong_profile.
  2. The request names a brand: ?client_id=<brand id> in the address, the header X-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.
  3. Nothing names one and your organisation has exactly one brand: that brand.
  4. Otherwise 400 client_id_required, with your brands listed in brands. An organisation with no brand yet answers 400 no_brand.
json
{
  "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:

json
{
  "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 answers 400 unknown_list, naming the key and the list it most likely means (contacts and users mean customers), with the allowed names in allowed.
  • A list that is not a JSON list answers 400 list_not_array; no row in any list, 400 empty_request.
  • time_zone must be a time zone name such as Europe/Prague or America/New_York, else 400 time_zone_unknown. It is used only for times sent without a zone (see Times).
  • ?dry_run=1 (or true) in the address makes the request a dry run. Besides client_id and dry_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:

json
{
  "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" }
    }
  ]
}
FieldTypeRequiredHow it is read
event_typetextyesWhat 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_idtext or numberyesYour 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_timetimenoWhen it happened (Times). Left out, null or empty: the moment it arrived, counted in without_time, with a hint.
customer_idtext or numbernoYour id of the person, at most 200 characters. 0, empty text and null mean no customer.
customer_emailtextnoThe person's e-mail. Trimmed and lower-cased; it must hold an @ with a dot after it, else the row is refused.
amountnumber or textnoThe event's money (Numbers and money). Negative amounts are allowed.
currencytextnoThree letters, such as EUR, USD or CZK, stored in upper case. Anything else refuses the row.
channeltextnoWhere 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_nametextnoThe campaign it belongs to, as you name it.
propertiesobjectnoThe event's own fields. Anything but an object refuses the row.
step_ofobjectnoThis event is a step of a record: { "event_type": ..., "event_id": ... } (A record that changes).
steptextnoThe step's plain name, such as Activated. Longer than 60 characters is cut.
any other nameany JSONnoKept 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_id is 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.
json
{
  "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"
    }
  ]
}
json
{
  "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_id only: the event is filed under that id.
  • customer_email only: 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:

json
{
  "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).

json
{
  "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_type is the kind of record (voucher), event_id is its id (voucher:3001), and event_time is when it began, the same on every send. Send it again under the same id when its own fields change. A field called name (or title, or label) is what the timeline shows after the status.
  • A step is an event of its own type (voucher_activated), with event_time = when the step happened, the same customer_id as the record, and "step_of": { "event_type": "voucher", "event_id": "voucher:3001" }. step gives it a plain name ("Used up"); left out, the name is read from the type (voucher_activated reads as Activated). event_id may 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.
json
{
  "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.

json
{
  "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.

json
{
  "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.

FieldTypeRequiredHow it is read
customer_idtext or numbercustomer_id or emailThe 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.
emailtextcustomer_id or emailLower-cased; it must be an e-mail address.
phonetextnoInternational 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_nametextnoAt most 200 characters each.
statustextnoThe customer's status in your system, lower-cased, at most 200 characters.
lifetime_valuenumber or textnoRead 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_attimenoCustomer since (Times). It only ever moves earlier.
email_consenttrue or falsenoMarketing e-mail.
sms_consenttrue or falsenoMarketing texts: SMS and WhatsApp.
blocktextnoall, marketing or none (Blocking a person).
block_reasontextnoKept on the block entry. Longer than 500 characters is cut.
attributesobjectnoYour 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.
  • attributes merge name by name. null for one attribute empties that value; the others stay.
  • email_consent, sms_consent and block left out, or null, change nothing.
  • status and lifetime_value: the newest value you send wins. They cannot be emptied by a push.
  • email and phone are never emptied: null leaves them as they are.
json
{
  "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 -, ? or n/a leaves the held name as it is, and the row counts in kept_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_consent or sms_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 true on that row, or in a later request, is counted in consent.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 true on that row, or in a later request, is counted in consent.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 false on 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_id applies 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 no customer_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 its false still applies to the e-mail and phone the contact of its own customer_id holds; it never reaches the other customer's contact. A block on that row is still recorded against what the row names, that e-mail included (Blocking a person, below).
json
{
  "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.

json
{
  "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, false or null. 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 true and false.
  • 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. Use email_consent, sms_consent and block.
  • 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).
json
{
  "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 sendSomeone new to the brandSomeone already on the brand
trueGrantedGranted, unless something stands in the way (below)
falseNot grantedMarketing on that channel is withdrawn, for the address on the row and the address their contact holds
left out or nullNot grantedNothing 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 true is counted in consent.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 in consent.no_address, with a hint.
  • A true never lifts a block.
json
{
  "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.

blockWhat 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 nullSays 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.

json
{
  "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 a customer_id and 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 all to marketing, 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_id it 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 their customer_id, lifts nothing, and the answer says so with a hint: send it with the customer_id. The hint block_none is given only when such a "none" lifted nothing and the customers list of the brand holds a block for that e-mail under a customer_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.

json
{
  "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_email or phone, any or all of them; with none, the row is refused (block_without_person). event_id may be left out.
  • enforcement is block_all (the default), suppress_marketing or flag_only. Any other value reads as block_all, with a hint. phone, enforcement and reason may also sit inside properties.
  • 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

BlockListsLifted 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 complaintNever 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.

json
{
  "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.

FieldTypeRequiredHow it is read
record_typetextyesWhat 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_idtext or numberyesYour own id of it, at most 200 characters.
nametextnoAt most 200 characters.
statustextnoLower-cased, at most 200 characters.
customer_idtext or numbernoWhose record it is. That person becomes a contact of the brand with nothing assumed about consent, as an event's person does.
created_attimenoIt only ever moves earlier.
propertiesobjectnoThe record's fields. Names may not start with an underscore (property_name_unreadable).
  • properties merge name by name; null empties 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.
json
{
  "records": [
    { "record_type": "customer", "record_id": "C-20418", "name": "Anna Novak" }
  ]
}

Times

event_time and created_at are read strictly by their shape:

  1. ISO 8601 with a zone: 2026-11-13T10:00:00Z or 2026-11-13T11:00:00+01:00, with or without fractions of a second, with a T or a space. Read exactly.
  2. 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's time_zone; without one, the row is refused (time_without_zone).
  3. 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).
  4. Anything else is refused (time_unreadable), and so is a time without a zone whose date does not exist, such as 2026-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:

json
{
  "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"
    }
  ]
}
json
{
  "events": [
    {
      "event_type": "payment",
      "event_id": "payment:90072",
      "event_time": "2026-11-13 10:00:00",
      "customer_id": "C-20418",
      "amount": 25,
      "currency": "EUR"
    }
  ]
}
json
{
  "events": [
    {
      "event_type": "payment",
      "event_id": "payment:90073",
      "event_time": 17945640000,
      "customer_id": "C-20418",
      "amount": 25,
      "currency": "EUR"
    }
  ]
}
json
{
  "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

  • amount is 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 in amounts_note. It is never stored as 0.
  • currency is 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 amount is money. An event with no amount that carries value, price, total, revenue, sum or cost gets 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_unread and properties_not_read, with a line in properties_note.
  • Customers' attributes and records' properties are stored as sent. Send counts and amounts as JSON numbers, and yes or no as true and false.
json
{
  "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:

json
{
  "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:

json
{
  "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: stored when rows were accepted and none was refused, erased or over a limit; partly_stored when rows were accepted and others were not; nothing_stored when no row was accepted. A customers row refused only for its lift (lift_held or lift_not_recorded) had the rest of it applied: it is listed in refused_rows and counted in refused like any refused row, and it counts as stored work for result and the status, so such a request is partly_stored.
  • dry_run: true on a dry run, with a note beside 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's request_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 the X-Request-Id header, the address pin's 403 and the limits' 429 and 503 included.
  • 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, and accepted = 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:

json
{
  "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.

CodeStatusWhenWhat to do
invalid_organization400The address does not end with your organisation idFix it: copy the address from Data → Push
body_shape400The body is not one JSON object with a list, or it is form-encodedFix it
unknown_list400A key at the top is not one of the listsFix it: allowed lists the names
list_not_array400A list is not a JSON listFix it
empty_request400No row in any listFix it
client_id_required400Several brands and none namedFix it: name one from brands
client_id_conflict400Two different brands namedFix it: name one
no_brand400The organisation has no brandCreate one, then send again
time_zone_unknown400time_zone is not a time zone nameFix it
unauthorized401No key, a key in the address, or a key that is wrong, expired, revoked or of another kindFix it: issue a key on Data → Push
allowance_reached402The request carried only events, and the plan holds all the events it keepsNot 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_organization403The key belongs to another organisationFix it
missing_scope403The key cannot send data inFix it: issue a key on Data → Push
ip_not_permitted403The key is pinned to other addressesFix it: send from a pinned address, or change the pin
wrong_profile403The key is for another brandFix it: leave client_id out, or use the key's own brand
unknown_brand404client_id is not a brand of your organisationFix it
method_not_allowed405Not a POSTFix it
too_many_rows413A list holds more rows than it maySplit it and send the parts
body_too_large413The request is over 4 MBSplit it and send the parts
nothing_stored422Nothing was accepted and rows were refused, none of them only for its liftFix the refused rows, then send them again
rate_limited429Too many requests for this key, or too many rows for this key or for your organisation's keys togetherSend it again after Retry-After seconds; higher limits are set on request through support@theaicmo.com
not_finished500Something failed on our side; part may be storedSend it again: stored rows are replaced, never doubled
blocks_not_recorded503A block could not be recorded; blocks recorded before it stand, and nothing else was storedSend it again after Retry-After seconds
consent_not_recorded503A consent decision, a customer's new e-mail or phone, or a new contact could not be recorded; no event was storedSend it again after Retry-After seconds
erasure_check_unavailable503The check for people erased on request could not run; nothing was storedSend it again after Retry-After seconds
rate_limit_unavailable503The limits could not be checked; nothing was storedSend it again after Retry-After seconds
brand_lookup_failed503The brand could not be checked; nothing was storedSend it again after Retry-After seconds
unavailable503Temporarily unavailable; the message says what, if anything, was storedSend 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.

CodeListWhat is wrong
row_not_objectanyThe row is not a JSON object
row_too_largeanyThe row is over 64 KB as JSON
row_too_large_for_planeventsOn the smallest plan, the event's own fields are over 32 KB
id_too_longanyAn id is over 200 characters
id_unsafe_numberanyAn id is a number too large to be exact
id_unreadableanyAn 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_longanyA text is longer than it may be: a name or a status over 200 characters, an e-mail or a phone over 200
value_unreadableanyA field holds a character that cannot be stored (a NUL character or half of an emoji); the message names the field
time_without_zoneanyA time without a zone, and no time_zone
time_unreadableanyA time that cannot be read
time_not_unixanyA number that is not 10 or 13 digits
changed_meanwhileeventsThe stored event changed while the request was stored
properties_not_objectevents, recordsproperties is not an object
event_type_missingeventsNo event_type
event_type_unreadableeventsevent_type is empty once cleaned, or too long
event_id_missingeventsNo event_id
id_used_by_another_typeeventsThe id is stored under another type
id_twice_with_two_typeseventsThe id comes twice under two types
customer_email_unreadableeventscustomer_email is not an e-mail address
currency_unreadableeventscurrency is not three letters
step_of_incompleteeventsstep_of lacks a part
step_of_itselfeventsA step has its record's type
block_without_personeventsA suppress or unsuppress names nobody
lift_not_recordedevents, customersA lift could not be recorded; the person stays blocked
lift_heldcustomersA lift was held, because the request would let in too many at once
customer_identity_missingcustomersNo customer_id and no email
email_unreadablecustomersemail is not an e-mail address
phone_unreadablecustomersphone is not in international form
unknown_fieldcustomers, recordsA field that is not in the list
consent_unreadablecustomersA consent value that is not true or false
email_of_another_customercustomersThe e-mail belongs to another customer of the brand
attributes_not_objectcustomersattributes is not an object
attribute_name_unreadablecustomersAn attribute name that cannot be stored
attribute_value_unreadablecustomersAn attribute holds a list or an object
record_type_missingrecordsNo record_type
record_type_unreadablerecordsrecord_type is empty once cleaned, or too long
record_type_is_customerrecordsrecord_type is customer
record_id_missingrecordsNo record_id
property_name_unreadablerecordsA property name starts with an underscore
catalog_not_openrecordsA type starting with item:
plan_row_refusedplans, actualsA 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:

  1. The key, its address pin and the rate limits. Every request counts, refused ones too.
  2. The body's shape and size, the rows a minute, the brand and time_zone.
  3. Every row of every list is read and judged. Nothing is written yet.
  4. One check for people erased on request, over every identifier.
  5. Blocks: customers rows with a block, suppress events and marked suppression events. Then lifts: "block": "none" and unsuppress events.
  6. Customers, records and the contacts of everyone the events name, with their consent.
  7. Events: compared with what is stored, then new ones written and changed ones updated.
  8. 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.

LimitValue
Rows in each of events, customers and records1,000 a request
Plans2,000 a request
Actuals5,000 a request
A request4 MB
A row64 KB as JSON
An event's own fields, on the smallest plan32 KB
event_id, customer_id, record_id200 characters
event_type, record_type, an attribute name60 characters
first_name, last_name, name, status200 characters
step60 characters, longer is cut
block_reason, reason500 characters, longer is cut
Requests for one key, by default600 a minute, 900,000 a day
Rows for your organisation, all its keys together, by default60,000 a minute
Requests for a connection with an old key in the address120 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:

json
{
  "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:

json
{
  "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 }
}
json
{
  "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_time keeps 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, or 402 when 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_id or 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_id is your own id with the type in front.
  • Every time carries a zone, or the request names its time_zone.
  • The answer's brand is 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, a 500 and a 503, with the same request.