Developers

API reference

Your own tools work with APAS® Cloud in two directions. Each has its own address and its own credential, and both answer in JSON.

  • Send data in. Your systems send each form submission, quiz and booking they capture, as a record, what happens in them, as an event for your analytics, each stage a lead reaches, as a conversion, what they know about a person, as a fact, the tags a person holds, as a tag, who is on your lists, as a list they are put on or taken off, who is in your audiences, as someone added to an audience or removed from one, who unsubscribed from your email, as an unsubscribe, and who asked not to have their data shared with advertisers, as an opt-out, with your account's webhook secret.
  • Read data out. Your tools read your account's details, your persons (each person once, across every device, email and phone they used), your records (every capture, such as a form submission, a booking or a call), your conversions (each one APAS® Cloud received in the last 90 days, with what every ad platform it was sent to answered), your audiences (what each one asks for, how many people it holds and who they are), your lists (who is on each) and your ad clicks (each one's campaign, tracking template values and click IDs), who gets the credit for each lead, your events (what each visitor did, by name or by person), your Call Center (its numbers and every call, answered or missed, with what made the phone ring) and your Email Center (whether it can send, who can be emailed, and every email sent or held back), with an API key.

The webhook secret only sends and an API key only reads, so neither can do the other's work. Both are included in every plan.

Send data to
https://ingest.apascloud.com
Read data from
https://api.apascloud.com/api/v1
Send data

Authentication

Sending uses your account's webhook secret, as a Bearer token: Authorization: Bearer <your webhook secret>. It is not an API key: an API key reads, and is refused here.

An Admin of your account generates the secret in the app, under Ingestion → Webhooks. Sign in to get yours. Each address ends in your client slug, which the account object answers as slug. The app shows your addresses whole, with your client slug in them, on that same screen. In the examples it is acme, the reference's example account.

  • The secret only sends. All it reads back is what an answer says about what you sent: the ID it is kept under, the person's APAS® Person ID where what you sent is a person's, after a tag request the tags they hold, after a list request the lists they are on, after an audience request which audiences changed, after an unsubscribe whether they were unsubscribed already, and after an opt-out whether they had opted out already.
  • One secret serves your whole account, for records, events, conversions, facts, tags, lists, audiences, unsubscribes and opt-outs alike. When an Admin rotates it, the one before keeps working until the next rotation, so you can update your systems without losing a delivery.
  • Keep it on a server. Anyone who holds it can send into your account.
  • Deliveries are counted: Ingestion → Webhooks shows what was accepted and what was refused over the last 7 days.
  • Any other address answers a 404, except /forms/<your client slug>, which still takes the form submissions sent to it before records had an address of their own: send new ones to the records address.
Addresses and headers
POST https://ingest.apascloud.com/records/acme
POST https://ingest.apascloud.com/analytics/acme
POST https://ingest.apascloud.com/conversions/acme
POST https://ingest.apascloud.com/facts/acme
POST https://ingest.apascloud.com/tags/acme
POST https://ingest.apascloud.com/lists/acme
POST https://ingest.apascloud.com/audiences/acme
POST https://ingest.apascloud.com/unsubscribes/acme
POST https://ingest.apascloud.com/consent/acme

Authorization: Bearer <your webhook secret>
Content-Type: application/json

Send a record

POSTingest.apascloud.com/records/<your client slug>

A lead one of your own forms, quizzes or calendars captured: who they are, their own privacy choice, and whatever else it collected. APAS® Cloud keeps it as a record like the ones it captures itself: it finds or makes the person, recovers where they came from and starts your flows. If your account's New leads setting is on (Conversions → Settings; it is for a new account), a person's first record makes them a new lead, unless it is dated more than a week before it arrives or before the setting was turned on.

It is one address for forms, quizzes and bookings, and source says which. A stage that lead reaches later is a conversion, with an address of its own, below: Send a conversion.

Sources

form

A form submission.

quiz

A quiz submission.

scheduler

A booking.

calculator

A calculator: your Quizzes module keeps it, since a quiz takes a value for each question. It is stored, read back and starts your flows as a quiz.

survey

A survey: your Quizzes module keeps it too, since a quiz keeps an answer for each question and needs no score. It is stored, read back and starts your flows as a quiz.

The body is JSON, one record in a request, 128 KB at most. It is sent with your webhook secret. Under Webhooks → Records the app writes the body out for each source, ready to copy into your system, below Fill in the APAS® IDs, which has your website fill the apasid and apasclid hidden fields of any form on it.

Attributes

sourcestringRequired

What the record came from: form, quiz (or calculator or survey, each kept as a quiz), or scheduler for a booking. It is the source Get a record returns, and it decides which of your flows the record starts: Form Submitted, Quiz Submitted or Scheduler Submitted.

sourceNamestringOptional

Your own name for that form, quiz or calendar, such as contact-us, so several of them stay easy to tell apart. A form's record shows it, followed by (external); a quiz's or a booking's name reaches your flows and its notification. It runs to 120 characters.

occurredAttimestampOptional

When it was submitted, in ISO 8601 or as a Unix time in seconds or milliseconds. Leave it out when your system posts the moment it happens: it is then when APAS® Cloud receives it; a time that cannot be read takes that too, and the answer says so. A record dated more than 24 hours before it arrives is kept as history: it shows on its date and starts none of your flows.

firstNamestringOptional

The lead's first name, exactly as submitted.

lastNamestringOptional

The lead's last name, exactly as submitted.

emailstringOne of the two

The lead's email, exactly as submitted. Send it, or phone: one of the two is required, since a record is a lead your team can reach. A record with neither is refused: what a visitor who is not a lead did goes to Send an event.

phonestringOne of the two

The lead's phone number, exactly as submitted. Send it, or email: one of the two is required.

countryCodestringOptional

The two-letter country of the phone number, such as us, so it normalizes correctly in your records.

consentbooleanOptional

A boolean reflecting the visitor's actual privacy choice under applicable law. Every downstream APAS® Cloud process respects this value, so it must come from the visitor, never a constant. false keeps this person out of every ad-platform upload, on every record of theirs. Leave it out when your form has no consent field: missing is recorded as not provided, and their conversions are then sent as with true.

strictModebooleanOptional

true puts this record under Strict Mode even when your account is not: the ad platforms are then sent no contact details for this lead. Left out, the record takes your account setting. It only ever tightens: false never switches your account Strict Mode off.

gpcbooleanOptional

true when the visitor sent Global Privacy Control, which only your page can see: a delivery between servers carries no browser. That person is then left out of what your audiences send to ad platforms. Leave it out when your form does not read it: missing is recorded as not known.

apasidstringOptional

The APAS® ID, from the hidden field your website fills in: the key that resolves the journey captured when the visitor arrived, with its landing page and its source. Send it exactly as your form holds it, even when empty.

apasclidstringOptional

The APAS® Click ID, from the other hidden field: the key that resolves the ad click. Send it exactly as your form holds it, even when empty.

apaspidstringOptional

The APAS® Person ID of the person the record is of, as Get a person answers it, for a system that already knows who they are. A record is placed by its own details first: its APAS® ID, its APAS® Click ID, its email and its phone. When they match nobody, the record joins the person apaspid names, where it would have made a new person. It never stands in for an email or a phone: a record still needs one of them. apaspid never merges two people: when the record's details match someone else, they decide, and the answer says so. A website's form has none to send: leave it out.

customFieldsobjectOptional

Anything else your form, quiz or calendar collects, as names and values, as many as you need, kept exactly as you send them.

A quiz, in customFields

A quiz's result rides in customFields, under the names a quiz taken with APAS® Cloud keeps it by. Each that is what its name says goes where a quiz's own result goes; anything else stays exactly as you sent it.

scorenumberOptional

The score they reached, a whole number: a decimal is rounded, and the answer says so.

maxScorenumberOptional

The most the quiz gives, a whole number likewise.

passedbooleanOptional

Whether they passed.

answersarrayOptional

Their answers, one item for each question, each with questionName (or questionId) and answer: the names your flows read them by.

A booking, in customFields

A booking's time rides in customFields too, under the names a booking made with APAS® Cloud keeps it by. A booking made elsewhere holds no slot of your schedulers, the booker is emailed nothing from APAS® Cloud and no calendar event is made. Your team's New booking notification goes out as for any booking, when it is dated no more than 24 hours before it arrives.

startTimetimestampRequired

When it starts, in ISO 8601 or as a Unix time. A booking is refused without it.

endTimetimestampOptional

When it ends. Send this or durationMinutes: a booking is refused without its length.

durationMinutesnumberOptional

How long it is, in whole minutes: a decimal is rounded, and the answer says so. When both are sent and disagree, this one decides.

timezonestringOptional

The time zone it was booked in, such as America/New_York. Left out, its times are kept in UTC.

commentsstringOptional

What they wrote when booking.

What it does not carry

No attribution: click IDs, UTM parameters, the landing page, the referrer and the device are recovered from the APAS® ID and the APAS® Click ID, the same way for every record, and are ignored if sent. A record with neither of the two IDs is still kept, as long as it has an email or a phone: it just has no visit to look up. An IP address is never kept.

What happens next

  • The record shows in APAS® 360 within seconds, under Records and on its person, with where they came from once it is recovered.
  • It starts your published flows that listen for its source, set to every form, quiz or scheduler (one set to particular ones is not started), when it is dated no more than 24 hours before it arrives. An older one is history: it shows on its date, starts nothing and notifies no one.
  • You can read it back: Get a record takes the id the answer gives, and List records returns it with the rest.
Request
curl -X POST \
  "https://ingest.apascloud.com/records/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "form",
    "sourceName": "Contact form",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "2015550123",
    "countryCode": "us",
    "consent": true,
    "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
    "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
    "customFields": {
      "company": "Example Inc",
      "message": "Please call me about the annual plan."
    }
  }'
Response · 200
{
  "success": true,
  "id": "cmhi3x9qk0007l508a1b2c3d4"
}

Record answers and errors

A record is refused only without a source, with one this endpoint does not take, with neither an email nor a phone, or, for a booking, without a start or a length. A field it takes that cannot be used is left off or read another way, the record is kept, and the answer's notes say what happened, one plain sentence each. A field it does not take is ignored without a note, and so is a consent, strictMode or gpc that is not true or false: it counts as not sent.

The note shown answers a record sent with a time that cannot be read. The error shown answers one sent without a source.

Returns

successboolean

true: the record is stored.

idstringSometimes

The ID of the record: the one Get a record takes. Left out on the rare answer whose record row could not be written yet.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left off or read another way. A field it does not take is ignored without a note, and so is a consent, strictMode or gpc that is not true or false: it counts as not sent. The record is stored all the same.

Status codes

200

Stored. Every delivery becomes a record: a lead who submits five times is five records, exactly as it happened.

400

The record cannot be stored: it has no source, its source is not form, quiz, calculator, survey or scheduler, it has neither an email nor a phone, a booking has no start or no length that can be read, or the body is not a JSON object. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

413

The body is over 128 KB.

503

It may not have been stored. Send the same request again, after the seconds its Retry-After header says: a record carries no ID of yours, so in the rare case the first one was stored after all, it is kept twice. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "id": "cmhi3x9qk0007l508a1b2c3d4",
  "notes": [
    "occurredAt \"yesterday\" could not be read as a time, so the record takes the time it arrived"
  ]
}
Error response · 400
{
  "success": false,
  "error": "source is required - what this record came from: form, quiz, calculator, survey or scheduler (a booking)",
  "traceId": "4e8a1c6d92b7"
}

Send an event

POSTingest.apascloud.com/analytics/<your client slug>

An event for APAS® Analytics: something a person did that one of your own systems saw, such as a video watched in your app, a plan upgraded or an invoice paid. You send it, and it is kept with the page views and the other events APAS® Analytics records on your website, under the person it happened to: their APAS® Person ID, or, for a visitor not captured yet, the APAS® ID of their browser.

Analytics is all this address takes. An event that is about a person, which you want kept on their record and counted there, such as a deal lost or an appointment missed, is a fact: Send a fact takes it, as a fact of the kind event. A stage a lead reaches is a conversion: Send a conversion. An event sent here never goes to an ad platform, and it never changes the person's record: it is no fact, stage or field of theirs, only an event on their journey.

Stores one event, sent as JSON with the attributes below. To send more than one in a request, see Send several events.

Attributes

apaspidstringOne of the three

Whose event it is, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Send it, or apasid, or apasclid: one of the three is enough, and this is the one to send for something your own systems saw, which happened to a person rather than on a browser. The event is kept under that person, and stays theirs if they are later merged with another person. One that matches no person of your account is named in the answer's notes, and the event is kept on the apasid sent with it, or under the person its apasclid belongs to; with neither, it is refused.

apasidstringOne of the three

Whose event it is, by the APAS® ID of the browser it happened on, a UUID: the one to send for a visitor APAS® Cloud has not captured yet, who has no APAS® Person ID. Sent alone, it keeps the event on that browser, as a page view is kept: it belongs to whoever that browser's visitor is, or becomes once captured. Take it from what your system kept from the browser, or from a record the API returns (its apasid: the browser that capture came from). Sent with an apaspid, it is kept with the event as well. Anything else in its place, such as your own ID for the visitor, is left off when an apaspid or apasclid was sent with it, and the answer says so; sent alone, it refuses the event.

apasclidstringOne of the three

Whose event it is, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID. Sent alone, it finds the person who arrived with that click, and so it does beside an apaspid that matches no one; beside an apasid, or an apaspid that matched, it is kept with the event as sent. Something that is not an APAS® Click ID is left off when another of the three was sent, and the answer says so; sent alone, it refuses the event.

eventstringRequired

The name of what happened, such as video_watched. Any name of yours, kept as you send it. A name APAS® Cloud records itself is refused: the list is below.

eventIdstring or numberOptional

Your own ID of this occurrence, as text or a number. An ID names one event: sent again under it, for the same day, it is counted once and the first one stored is kept, so sending again after a timeout is safe. Send occurredAt with it, so a resend lands on the same day. Without it APAS® Cloud makes one, and the answer gives it to you.

occurredAttimestampOptional

When it happened: ISO 8601, or a Unix time in seconds or milliseconds. Left out, it is the moment the event arrives. Any time is kept, however long ago; one more than an hour ahead is kept too, and the answer says it shows only from that time on.

valuenumber or stringOptional

What it was worth: a number, or text such as "$49.99". A number with more than 6 decimals or more than 15 digits before the point, or written with an exponent, is left off, and the answer says so.

currencystringOptional

The currency of the value: any three letters, upper-cased, such as USD. Left out, a code written beside the value is used. Anything else is kept as you send it.

propertiesobjectOptional

Anything else about the event, as names and values. Kept exactly as you send them: any name, any value, and as many as you like.

What it does not carry

Only apaspid, apasid and apasclid say whose event it is. If you also send email or phone as a field of the event, it is left off and the answer says so: the event is kept. Inside properties everything is kept as sent.

Names you cannot use

APAS® Cloud records these itself, so an event of yours cannot take one of them, in any capitals: pageview, pageleave, engaged, click_to_call, click_to_sms, click_to_email, form_submitted, quiz_submitted, quiz_ended_early, scheduler_submitted, rag_submitted, banner_shown, banner_clicked, banner_dismissed, banner_submitted, phone_call, red, orange, yellow, white and green. The five colours are conversions, which go to their own address.

What happens next

  • Dated now, it shows in Analytics → Real-Time Events the moment it arrives, marked as sent by your systems; dated earlier, it shows under its own date.
  • It shows on the journey of the person it belongs to in APAS® 360, marked as sent by your systems.
  • A published flow whose Analytics Event trigger listens for its name starts, when the event is dated no more than 24 hours before it arrives, with the person's APAS® Person ID in {{ trigger.apaspid }}: the person you sent it for, or the person its browser belongs to. An older one is history: it is stored on its own date and starts nothing.
  • It carries no bot score, and it never counts as a visit to your website.

Sending again

Give each event an eventId and occurredAt, and sending it twice counts it once, so sending again after a timeout is always safe: the first one stored is kept, and a resend never changes it. An ID names one event, so two events of a day never share one. Without an eventId, an event that carries occurredAt is still counted once, since the same request makes the same ID. With neither, an event sent twice can count twice.

Request
curl -X POST \
  "https://ingest.apascloud.com/analytics/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "event": "video_watched",
    "eventId": "vw-8812",
    "occurredAt": "2026-11-02T14:10:00Z",
    "value": 49,
    "currency": "USD",
    "properties": {
      "plan": "pro",
      "video": "onboarding-2"
    }
  }'
Response · 200
{
  "success": true,
  "eventId": "vw-8812",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Send several events

POSTingest.apascloud.com/analytics/<your client slug>

The same address takes a list: up to 50 events in one request, 64 KB at most. The body is a JSON list of events, each as Send an event describes it.

Each event is looked at on its own, so one that cannot be stored does not hold the others back: the answer is a 200 that says what became of each. Only when an event could not be stored this time, or was stored but your flows could not start for it, is the whole list a 503: send the list again, and the events sent with an eventId or an occurredAt are kept once.

Returns

successboolean

true when every event of the list was stored, false when at least one was refused.

acceptedinteger

How many were stored.

refusedinteger

How many could not be stored.

resultsarray of objects

One entry for each event, in the order you sent them: its index in the list and its status (accepted, refused, or failed on a 503). A stored event has its eventId, the apaspid it is kept under when it names a person, and any notes. A refused one has the error that says why and a code: invalid for an event that cannot be stored, no_person for one sent without an apasid whose apaspid or apasclid matches no person of your account, no_analytics when your account has no analytics table yet. A failed one was not stored this time: send it again.

Request
curl -X POST \
  "https://ingest.apascloud.com/analytics/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "event": "video_watched",
      "eventId": "vw-8812",
      "occurredAt": "2026-11-02T14:10:00Z",
      "value": 49,
      "currency": "USD",
      "properties": {
        "plan": "pro",
        "video": "onboarding-2"
      }
    },
    {
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "event": "plan_upgraded",
      "eventId": "up-2204",
      "occurredAt": "2026-11-03T09:20:00Z",
      "properties": {
        "plan": "annual"
      }
    }
  ]'
Response · 200
{
  "success": true,
  "accepted": 2,
  "refused": 0,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "eventId": "vw-8812",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    },
    {
      "index": 1,
      "status": "accepted",
      "eventId": "up-2204",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    }
  ]
}

Event answers and errors

An event is refused only without a name, with a name APAS® Cloud records itself, without one of the three IDs, when it names by apaspid or apasclid alone someone who is not a person in your account, or while your account has no analytics table. Anything else it cannot use as sent is left off or read another way, the event is kept, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers an event that was sent with an email too. The list answer shown is for a list whose second event was sent without any of the three IDs, and the error for one event sent alone without them.

Returns

successboolean

true: the event is stored.

eventIdstring

The ID the event is kept under: yours, or the one APAS® Cloud made when you sent none.

apaspidstringSometimes

The APAS® Person ID the event is kept under: the person your apaspid or apasclid found, as they are now, which a merge may have changed from the one you sent. Not there when the event is kept on a browser alone: sent with an apasid only, it belongs to whoever that browser's visitor is or becomes.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left off or read another way. A field it does not take, such as a misspelt name, is ignored without a note. The event is stored all the same.

Status codes

200

Stored. For a list, every event was looked at and results says what became of each: a list answers 200 even when some of its events were refused, and an empty list answers 200 with nothing stored and a note that says so.

400

One event sent alone cannot be stored: it has no event name, a name APAS® Cloud records itself, none of apaspid, apasid and apasclid, or only an apasid or an apasclid that is not one. Or the body is not an event or a list of events, or the list holds more than 50. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

One event sent alone names no one: it carries no apasid, and its apaspid or apasclid matches no person of your account. An event without a browser has to belong to a person of your account, captured by APAS® Cloud or imported: for a visitor of your website who never filled in a form, booked or called, send the apasid.

409

Your account has no analytics table yet, so there is nowhere to store the event.

413

The body is over 64 KB.

503

It could not be stored this time, or it was stored but the flows that listen for it could not start. Send the same request again, after the seconds its Retry-After header says: an event sent with an eventId or an occurredAt is kept once. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "eventId": "up-2204",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "email was not kept: an analytics event finds its person by apaspid, apasid or apasclid"
  ]
}
Response · 200, one event of a list refused
{
  "success": false,
  "accepted": 1,
  "refused": 1,
  "results": [
    {
      "index": 0,
      "status": "accepted",
      "eventId": "vw-8812",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    },
    {
      "index": 1,
      "status": "refused",
      "code": "invalid",
      "error": "One of apaspid, apasid or apasclid is required: it says whose event this is"
    }
  ]
}
Error response · 400
{
  "success": false,
  "error": "One of apaspid, apasid or apasclid is required: it says whose event this is",
  "traceId": "7c1e9a4b2d6f"
}

Send a conversion

POSTingest.apascloud.com/conversions/<your client slug>

Tells APAS® Cloud that one of your records reached a stage: a new lead, a customer, or a stage between. Your CRM or your own system sends it when the stage is reached. APAS® Cloud ties it to the person and to the ad that brought them, and sends it on to your ad platforms.

Three shapes by design: red, a new lead, needs no time, since APAS® Cloud dates it from when it first captured them; orange to white add the moment the stage happened; and green, your customer stage, adds the real deal value too. Keeping the value on that one stage is what makes your revenue reporting mean won revenue.

The body is JSON, one conversion in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a fact and a tag are sent with. Under Webhooks → Conversions the app writes each stage's body out for you, with your client slug in it, ready to copy into your system.

The examples are of an account whose client slug is acme, the one the account object's example shows: it is in the address and in the body, which must agree.

Attributes

apaspidstringOptional

Who the conversion belongs to, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. The same on every stage. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. The conversion is credited with every ad click of theirs, on any of their devices, in the 90 days before they became a lead. When you send more than one, send IDs of one person: the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID. A conversion sent with none of them is kept, but it belongs to no person and goes to no ad platform.

apasidstringOptional

Who the conversion belongs to, by an APAS® ID of theirs, a UUID: the ID of a browser they used, the one your CRM keeps from the lead's form. For a system that holds that and not their APAS® Person ID.

apasclidstringOptional

Who the conversion belongs to, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

clientSlugstringRequired

Your client slug. It must match the slug in the address, which is what routes the conversion to your account.

eventstringRequired

The stage the conversion reports: red, orange, yellow, white or green. Always the colour, never your own name for the stage. The colours are the values the whole platform runs on; your own stage names take over everywhere your reports show them.

eventIdstring or numberOptional

Which occurrence of the stage this is, as text or a number. On green it is which sale: the ID of the record the sale is, such as the opportunity, deal, order, invoice or appointment, not the customer's. Green counts once per sale, so this is what lets the same customer buy again and have it count again, instead of merging into their first purchase. On red to white send the record's own ID, the same as recordId, or leave it out: the stage then counts once per record.

occurredAttimestampOptional

The moment the stage happened, as an ISO 8601 timestamp (one without an offset is read as UTC) or a Unix epoch in seconds or milliseconds (convertedAt, its earlier name, works too). Leave it out only if your system sends the conversion at that moment: the time it arrives is then the same thing. If it runs on a schedule, in batches or after the fact, send it: this is the time your ad platforms receive as the conversion, the day your reports count it on (the reports that count each lead's stages on the day they became a lead, as MER and ROAS do, count it there), and the point it appears on the person's journey. A time that cannot be read never stops the conversion: it is dated as if you had sent none, and the answer says so. Red needs none: becoming a lead is the conversion, and APAS® Cloud dates a red sent without one from the moment it first captured that person, or from its arrival when it captured none. A conversion dated more than 90 days ago is stored and counts in your reports, but no ad platform is sent it, and List conversions does not return it.

recordIdstring or numberRequired

The record's ID in your system, as text or a number: the deal's identity, the same on every stage. Each stage counts once per record: the first send owns the conversion and fixes its date, and a retry or an update only refreshes its details, never the count or the date. Always send the same ID for the same deal.

valuenumber or stringGreen only

On green only: the real deal amount, the number your revenue reporting is built from. A number, or written like money, "$4,200.00" or "4.200,00 €". A value that cannot be read never stops the conversion: it still counts, your reports at the revenue per customer set in Conversions → Settings and your ad platforms at the bidding value of the stage, and the answer says so. No other stage carries a value, so that your revenue reporting means won revenue: sent on one, it is left off, and the answer says so.

currencystringGreen only

On green only, and optional: the three-letter code of the value's currency, like USD. A code written beside the value ("4200 EUR") counts too. Nothing is converted: your reports and your ad platforms take every amount as your account's currency, so send it in that currency.

propertiesobjectOptional

Your segment fields, as names and values: extra fields about the deal, with the same names on every stage that knows them. The ones set as report segments for your account, three at most, are the dropdowns your reports break down by.

What it does not carry

No name, email or phone goes in any of them: one ID is enough, since APAS® Cloud already holds what it captured for them. Their APAS® Person ID, an APAS® ID of theirs (a browser they used) or an APAS® Click ID of theirs: any one of the three finds the same person. A conversion is never refused for its IDs: an APAS® ID that nobody in your account holds yet adds that person to APAS® 360, and an APAS® Person ID that nobody holds is not used.

How a conversion counts

Each stage counts once per record, and green once per sale, however many times it is sent: sending a conversion again is always safe. One sent again brings what the first lacked, such as an ID your system learned later, and its properties take the place of the earlier ones. Its time stays the first one sent.

Every sale counts with its own amount: a green with another eventId is another sale. A sale sent again with the same eventId stays one sale, and your reports take the last amount you sent: after a refund or a discount, send the sale again with its new amount. What an ad platform was already sent does not change: Conversions → Health, and the conversion you read back, keep the amount first sent.

A person reaches red, orange, yellow and white once. When two of your records are one person, the second record's conversion of a stage an ad platform already accepted for them is kept, and goes to no ad platform. Green is different: every sale is sent, so a returning customer counts each time.

When a person reaches a stage without the ones before it that Conversions → Settings shows, APAS® Cloud records the skipped ones itself, so your stages always run in order, and sends them to your ad platforms. One of them your system sends later counts once.

What happens next

  • It shows under Conversions → Health within seconds, as Accepted, with exactly what your system sent (Refresh brings the list up to date). One that cannot be stored shows there too, as Refused, with the reason; a request refused for its secret or its size leaves no line there.
  • Usually within the hour, and within about two and a half while a new lead is still being scored for bots, APAS® Cloud sends it to the ad platforms that Conversions → Settings names for its stage, or holds it back and says why when you read it back, as it does a conversion with no ad click. One dated more than 90 days ago counts in your reports but is sent to no ad platform.
  • You can read it back within about 15 minutes of its arrival: List conversions returns it as a conversion object, with its status and what every ad platform answered, unless it is dated more than 90 days ago.
Request · a new lead
curl -X POST \
  "https://ingest.apascloud.com/conversions/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "clientSlug": "acme",
    "event": "red",
    "eventId": "006Qy00000ABC12",
    "recordId": "006Qy00000ABC12",
    "properties": {
      "plan": "annual"
    }
  }'
Request · a sale
curl -X POST \
  "https://ingest.apascloud.com/conversions/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "clientSlug": "acme",
    "event": "green",
    "eventId": "INV-1042",
    "occurredAt": "2026-11-02T14:03:11Z",
    "recordId": "006Qy00000ABC12",
    "value": 4200,
    "properties": {
      "plan": "annual"
    }
  }'
Response · 200
{
  "success": true,
  "messageId": "13047219385610042",
  "requestId": "req_1793628199512_9f2c41ab"
}

Conversion answers and errors

A conversion is refused only when it cannot be stored. A field it takes that cannot be used is left off or read another way, the conversion is kept, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers a conversion of a stage before green that was sent with a value: only green carries one. The error shown answers one whose event was the stage's own name, where its colour belongs.

Returns

successboolean

true: the conversion is stored.

messageIdstringSometimes

The ID of this delivery in our queue, to quote with requestId: not the conversion's id. Left out when deduplicated is true.

deduplicatedbooleanSometimes

true when this conversion, unchanged, was the last one stored for its stage and record, so nothing was written again. Any other repeat is stored again, and still counts once. Left out otherwise.

requestIdstring

The ID of your request, to quote if you contact us about a delivery.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left off or read another way. A field it does not take, such as a misspelt name, is ignored without a note. The conversion is stored all the same.

Status codes

200

Stored. Also the answer when this conversion, unchanged, was the last one stored for its stage and record: deduplicated then says so.

400

The conversion cannot be stored: the body is not a JSON object, clientSlug does not match the slug in the address, event is not one of the five colours, or there is no recordId. errors says which. Sending it again unchanged gets the same answer.

401

The webhook secret is missing, or is not a secret of the account in the address.

413

The body is over 128 KB.

503

It could not be stored this time. Send the same request again, after the seconds its Retry-After header says: a conversion sent twice counts once. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

errorsarray of stringsSometimes

On a 400 only: each reason the conversion cannot be stored, one sentence each.

retryablebooleanSometimes

true when sending the same request again will work, as on a 503.

requestIdstring

The ID of your request, to quote if you contact us about a delivery.

Response · 200, with a note
{
  "success": true,
  "messageId": "13047300112908771",
  "requestId": "req_1793697604118_4be07d15",
  "notes": [
    "value was left off: only a won deal (green) carries one"
  ]
}
Response · 200, already stored
{
  "success": true,
  "deduplicated": true,
  "requestId": "req_1793628263077_71d0b3ce"
}
Error response · 400
{
  "success": false,
  "error": "Invalid payload (quarantined for review - do not retry unchanged)",
  "errors": [
    "event must be one of: red, orange, yellow, white, green (any capitalization)"
  ],
  "requestId": "req_1793697767903_c2a9e630"
}

Send a fact

POSTingest.apascloud.com/facts/<your client slug>

Attaches your own information to a person: kept on their record, and there to analyse against everything else you know about them, such as where they came from, what they did and what they are worth.

A fact is not a conversion and not an analytics event: it is never sent to an ad platform as a conversion, and it moves no colour stage. Those two have addresses of their own, above: Send a conversion and Send an event.

Two kinds

event

Something that happened to them at a moment: an appointment missed, a deal that fell through. It can happen again: each time counts on its own when it carries its own eventId.

attribute

Something true of them right now: their tier, their account owner. When it changes you send the new value, and the one dated latest is the one their record shows.

One shape for both kinds: the key names the kind, the name is yours, and the value and properties carry what you want to count and group by later.

The body is JSON, one fact in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a conversion and a tag are sent with. Under Webhooks → Facts the app writes the body out for you, ready to copy into your system.

Attributes

apaspidstringOne of the three

Who this is about, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. When you send more than one of the three, the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID. A fact attaches to a person, so APAS® Cloud needs to recognise them: for someone who is not a person in your account yet, the send is refused rather than filed against nobody. Someone is a person once APAS® Cloud has captured them, or they were imported.

apasidstringOne of the three

Who this is about, by an APAS® ID of theirs: the ID of a browser they used, a UUID. For a system that holds that and not their APAS® Person ID.

apasclidstringOne of the three

Who this is about, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

eventstringOne of the two

What happened, in your own words, such as lost_deal. The key itself says this is an event, so there is no separate field to set. This name is what you will group and count by later, so keep it consistent. Send event or attribute, never both: one payload describes one fact.

attributestringOne of the two

What you are recording about them, in your own words, such as tier. The key itself says this is an attribute, so there is no separate field to set. This name is what you will group and count by later, so keep it consistent.

eventIdstring or numberEvent only

Which occurrence of the event this is, as text or a number, so a second lost deal counts as its own rather than being taken for the first. Leave it out and the event counts once per person. An attribute takes none.

occurredAttimestampOptional

When it happened, or when the attribute became true, in ISO 8601 or as a Unix time in seconds or milliseconds. Leave it out and it is when APAS® Cloud receives it; a time that cannot be read takes that too, and the answer says so. A fact dated more than 24 hours before it arrives is kept as history: it shows on its date and starts none of your flows.

valuestring or numberOptional

On an attribute, what it is set to, like gold for a tier, kept as you send it, trimmed. Sending the same attribute and value again marks it current, so a retry is free and a customer who returns to a previous tier reads correctly. Sent empty, the attribute is recorded as having no value, as when a field is cleared. On an event it is optional: what it was worth, if the event has an amount, as a number or written like money, "$4,200.00", and kept as you send it when it is not an amount.

currencystringOptional

The three-letter code of the value's currency, like USD, in any capitals. It wins over a code written beside the value ("4200 EUR"), which counts when it is sent alone, and anything else is kept as you send it.

propertiesobjectOptional

The detail you want to group by later, kept exactly as you send it. Reuse the same handful of values across everyone, the way a dropdown would: a reason of price, timing or competitor, not a different phrase for each person.

What it does not carry

Only apaspid, apasid and apasclid say whose fact it is. If you also send email or phone, it is left off and the answer says so: the fact is kept.

What happens next

  • It shows on the person's page in APAS® 360 within seconds, under Custom Facts, where your team can also add and remove entries by hand.
  • A published flow that listens for Custom Fact Recorded starts, and so do your Email Center automations that start on Custom fact recorded, for a new event or an attribute that takes a new value, when the fact is dated no more than 24 hours before it arrives. An older one is history: it shows on its date and starts nothing.
  • An event named Lost stage, in any capitals, marks the person Lost on APAS® 360 → Stages, with its properties.reason as the reason, and, dated within 24 hours, starts your flows that listen for Stage Changed and your Email Center automations that start on Stage changed, unless they were Lost already.
  • You can read it back: Get a person returns their facts, each attribute at its current value and their latest 50 events.
Request · an event
curl -X POST \
  "https://ingest.apascloud.com/facts/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "event": "quote_sent",
    "eventId": "Q-1042",
    "occurredAt": "2026-10-28T10:12:00Z",
    "value": 4200,
    "currency": "USD",
    "properties": {
      "plan": "annual"
    }
  }'
Request · an attribute
curl -X POST \
  "https://ingest.apascloud.com/facts/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "attribute": "tier",
    "occurredAt": "2026-11-03T15:00:00Z",
    "value": "gold"
  }'
Response · 200
{
  "success": true,
  "status": "created",
  "id": "cmhk6t2pw000al508d4n7x1yz",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Fact answers and errors

A fact is refused only when it cannot be stored: without one of the three IDs, for someone who is not a person in your account yet, without an event or attribute name, with both, or with a name over 500 characters. A field it takes that cannot be used is left off or read another way, the fact is kept, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers a fact that was sent with an email too. The error shown answers one sent for someone who is not a person in your account yet.

Returns

successboolean

true: the fact is stored.

statusstring

created or duplicate.

idstring

The ID the fact is kept under.

apaspidstring

The APAS® Person ID of the person it was attached to: the apaspid Get a person takes.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left off or read another way. A field it does not take, such as a misspelt name, is ignored without a note. The fact is stored all the same.

Statuses of a stored fact

created

The fact is new, and is now on the person.

duplicate

It was already on them, whoever recorded it: the same event again, under the same eventId or with none, or an attribute with a value it already held, which is marked current again.

Status codes

200

Stored, or already held: status says which.

400

The fact cannot be stored: it names nobody (none of apaspid, apasid and apasclid), it names neither an event nor an attribute, it names both, its name is over 500 characters, or the body is not a JSON object. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

No person of your account matches the ID you sent: someone has to be a person in your account, captured by APAS® Cloud or imported, before a fact can be attached to them. A visitor of your website who never filled in a form, booked or called is not a person yet.

413

The body is over 128 KB.

503

It could not be stored this time. Send the same request again, after the seconds its Retry-After header says: a fact sent twice is kept once. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "status": "created",
  "id": "cmhk6t2pw000al508d4n7x1yz",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "email was not kept: a fact finds its person by apaspid, apasid or apasclid"
  ]
}
Response · 200, sent again
{
  "success": true,
  "status": "duplicate",
  "id": "cmhk6t2pw000al508d4n7x1yz",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}
Error response · 404
{
  "success": false,
  "error": "No person of this account matches the apaspid you sent. A fact attaches to a person, so they must have been captured by APAS® Cloud first.",
  "traceId": "4e8a1c6d92b7"
}

Send a tag

POSTingest.apascloud.com/tags/<your client slug>

Puts tags on a person, or takes them off: the tags of APAS® 360, the same ones your team puts on by hand and your flows with Add Tag and Remove Tag. Your system keeps them in step with its own.

A tag is not a fact: it carries no value and no date, only its name. What you know about a person, with a value, goes to Send a fact, above.

Two things it does

add

Puts the tags on them. A tag your account does not have yet is made, and one they hold already is left as it is.

remove

Takes the tags off them. One they do not hold is named in the answer, and nothing else changes.

One shape for both: the key says whether the tags go on or come off, and its value names them.

The body is JSON, one person in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a conversion and a fact are sent with. Under Webhooks → Tags the app writes the body out for you, ready to copy into your system.

Attributes

apaspidstringOne of the three

Who this is about, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. When you send more than one of the three, the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID. A tag goes on a person, so APAS® Cloud needs to recognise them: for someone who is not a person in your account yet, the send is refused rather than filed against nobody. Someone is a person once APAS® Cloud has captured them, or they were imported.

apasidstringOne of the three

Who this is about, by an APAS® ID of theirs: the ID of a browser they used, a UUID. For a system that holds that and not their APAS® Person ID.

apasclidstringOne of the three

Who this is about, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

addstring or array of stringsOne of the two

The tags to put on them, by name: one, or several as a list or split by commas. A tag your account does not have yet is made, and one they hold already is left as it is. Capitals and extra spaces do not make a new tag: VIP and vip are one. Send add or remove, never both: one payload does one thing.

removestring or array of stringsOne of the two

The tags to take off them, by name: one, or several as a list or split by commas. A tag they do not hold is named in the answer, and nothing else changes.

What a tag is

  • A name, of 40 characters at most: a longer one is kept as its first 40, and the answer says so.
  • One tag per account however it is written: capitals and extra spaces do not make a new one, and the answer names each tag as your account spells it (notOn names them as you sent them).
  • A person holds 50 tags at most, and an account keeps 500: a request that would take either past it is refused, and changes nothing.

What it does not carry

Only apaspid, apasid and apasclid say whose tags they are. If you also send email or phone, it is not used and the answer says so: the rest is done.

What happens next

  • The tag shows on the person's page in APAS® 360 within seconds, beside the tags your team puts on by hand, and in the Tags column of Persons.
  • A tag put on starts your published flows that listen for Tag Added, and your Email Center automations that start on Tag added. One they held already starts nothing; one taken off and put on again starts them again.
  • You can read them back: Get a person returns them as their tags.
Request · add
curl -X POST \
  "https://ingest.apascloud.com/tags/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "add": "VIP"
  }'
Response · 200
{
  "success": true,
  "added": [
    "VIP"
  ],
  "already": [],
  "tags": [
    "VIP"
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Remove a tag

POSTingest.apascloud.com/tags/<your client slug>

The same address and the same body as Send a tag, with the tags under remove: they come off the person, and the tag stays on your account, on anyone else who holds it, until you delete it in APAS® 360.

A tag they do not hold comes back under notOn, and nothing else changes, so taking a tag off twice is safe. The answer's tags are the ones they still hold: in the example, none. A tag taken off starts nothing: no flow listens for it.

Request · remove
curl -X POST \
  "https://ingest.apascloud.com/tags/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "remove": "VIP"
  }'
Response · 200
{
  "success": true,
  "removed": [
    "VIP"
  ],
  "notOn": [],
  "tags": [],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Tag answers and errors

A request is refused only when it cannot be done: without one of the three IDs, without a tag, with both add and remove, for someone who is not a person in your account yet, or when it would take the person past 50 tags or need a new tag when your account already keeps 500. A refused request changes nothing. A field it takes that cannot be used is left out or read another way, the rest is done, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers an add that was sent with an email too. The second answer is the same add sent again, right after: nothing changes. The error shown answers one sent for someone who is not a person in your account yet.

Returns

successboolean

true: it is done.

addedarray of stringsAfter an add

After an add: the tags put on them now, by name, as your account spells them.

alreadyarray of stringsAfter an add

After an add: the tags they held already, left as they were.

removedarray of stringsAfter a remove

After a remove: the tags taken off them, by name, as your account spells them.

notOnarray of stringsAfter a remove

After a remove: the tags they did not hold.

tagsarray of strings

Every tag they hold now, by name, A to Z: the tags Get a person lists.

apaspidstring

The APAS® Person ID of the person: the apaspid Get a person takes.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left out or read another way. A field it does not take, such as a misspelt name, is ignored without a note. The rest is done all the same.

Status codes

200

Done: the answer says which tags were put on or taken off, and which were left as they were.

400

It cannot be done: it names nobody (none of apaspid, apasid and apasclid), it names no tag, it carries both add and remove, the body is not a JSON object, or it would take the person past 50 tags or need a new tag when your account already keeps 500. A refused request changes nothing. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

No person of your account matches the ID you sent: someone has to be a person in your account, captured by APAS® Cloud or imported, before a tag can go on them. A visitor of your website who never filled in a form, booked or called is not a person yet.

413

The body is over 128 KB.

503

It could not be done this time. Send the same request again, after the seconds its Retry-After header says: sent twice, it changes nothing the second time. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "added": [
    "VIP"
  ],
  "already": [],
  "tags": [
    "VIP"
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "email was not used: tags find their person by apaspid, apasid or apasclid"
  ]
}
Response · 200, sent again
{
  "success": true,
  "added": [],
  "already": [
    "VIP"
  ],
  "tags": [
    "VIP"
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}
Error response · 404
{
  "success": false,
  "error": "No person of this account matches the apaspid you sent. A tag goes on a person, so they must have been captured by APAS® Cloud first.",
  "traceId": "4e8a1c6d92b7"
}

Add to a list

POSTingest.apascloud.com/lists/<your client slug>

Puts a person on one of your lists, or takes them off: the lists of Email Center → Lists, the same ones your team adds people to by hand and your flows with Add to Email List and Remove from Email List. Being put on a list starts the email automations that begin when someone is added to it, so it is how your own system starts a sequence.

A list holds people; a tag is something a person holds. An automation can start on either, and a list can be emailed as one.

Two things it does

add

Puts them on the lists, and starts the automations that begin when someone is added to each. A list they are on already is left as it is.

remove

Takes them off the lists. A list they are not on is named in the answer, and nothing else changes.

One shape for both: the key says whether they go on the list or come off it, and its value names the list.

The body is JSON, one person in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a conversion, a fact and a tag are sent with. Under Webhooks → Lists the app writes the body out for you, with the list you pick, ready to copy into your system.

Attributes

apaspidstringOne of the three

Who this is about, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. When you send more than one of the three, the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID. A list holds people, so APAS® Cloud needs to recognise them: for someone who is not a person in your account yet, the send is refused rather than filed against nobody. Someone is a person once APAS® Cloud has captured them, or they were imported.

apasidstringOne of the three

Who this is about, by an APAS® ID of theirs: the ID of a browser they used, a UUID. For a system that holds that and not their APAS® Person ID.

apasclidstringOne of the three

Who this is about, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

addstring or array of stringsOne of the two

The lists to put them on, by ID, as List lists answers it: one, or several as a list or split by commas. Being put on a list starts the automations that begin when someone is added to it, as when a teammate adds them; a list they are on already is left as it is and starts nothing. Each must be a static list: one that updates itself from its conditions decides who is on it. Send add or remove, never both: one payload does one thing.

removestring or array of stringsOne of the two

The lists to take them off, by ID: one, or several as a list or split by commas. A list they are not on is named in the answer, and nothing else changes.

What a list is

  • A list of your account's, named by its ID: List lists answers every list's ID, and Webhooks → Lists writes it in for the list you pick. Its name can change; its ID does not.
  • A static list holds the people put on it: by your team, an automation, a flow, an import, or your system through this address. One that updates itself from its conditions holds whoever they match, and is refused here.
  • One request names 50 lists at most.

What it does not carry

Only apaspid, apasid and apasclid say who goes on the list. If you also send email or phone, it is not used and the answer says so: the rest is done.

What happens next

  • The person is on the list in Email Center → Lists within seconds, as put on by your system.
  • Being put on a list starts your Email Center automations that start on Added to a list for that list, and counts in every automation that asks whether someone is on it. A list they are on already starts nothing; one they were taken off and put on again starts them again.
  • You can read it back: List a list's members returns everyone on it.
Request · add
curl -X POST \
  "https://ingest.apascloud.com/lists/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "add": "cm4r7t2kq0001x9l3v8b6n5wz"
  }'
Response · 200
{
  "success": true,
  "added": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "already": [],
  "lists": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Remove from a list

POSTingest.apascloud.com/lists/<your client slug>

The same address and the same body as Add to a list, with the list under remove: the person comes off it, and the list stays as it is for everyone else on it.

A list they are not on comes back under notOn, and nothing else changes, so taking someone off twice is safe. The answer's lists are the ones they are still on: in the example, none. Being taken off starts nothing, and an automation that asks whether someone is on the list sees the change, as when your team takes them off.

Request · remove
curl -X POST \
  "https://ingest.apascloud.com/lists/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "remove": "cm4r7t2kq0001x9l3v8b6n5wz"
  }'
Response · 200
{
  "success": true,
  "removed": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "notOn": [],
  "lists": [],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

List answers and errors

A request is refused only when it cannot be done: without one of the three IDs, without a list or with more than 50, with both add and remove, for someone who is not a person in your account yet, or for a list your account does not have or one that updates itself from its conditions. A refused request changes nothing. A field it takes that cannot be used is left out, the rest is done, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers an add that was sent with an email too. The second answer is the same add sent again, right after: nothing changes, and nothing starts again. The error shown answers one sent for someone who is not a person in your account yet.

Returns

successboolean

true: it is done.

addedarray of objectsAfter an add

After an add: the lists they were put on now.

alreadyarray of objectsAfter an add

After an add: the lists they were on already, left as they were.

removedarray of objectsAfter a remove

After a remove: the lists they were taken off.

notOnarray of objectsAfter a remove

After a remove: the lists they were not on.

listsarray of objects

Every list they are on now, A to Z by name: the lists people are put on, and those that update themselves from their conditions.

apaspidstring

The APAS® Person ID of the person: the apaspid Get a person takes.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left out. A field it does not take, such as a misspelt name, is ignored without a note. The rest is done all the same.

Each list in them is an object:

idstring

The list’s ID: the one List lists answers, and the one a request names it by.

namestring

Its name, as your account spells it.

Status codes

200

Done: the answer says which lists they were put on or taken off, and which were left as they were.

400

It cannot be done: it names nobody (none of apaspid, apasid and apasclid), it names no list or more than 50, it carries both add and remove, the body is not a JSON object, or a list it names updates itself from its conditions. A refused request changes nothing. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

No person of your account matches the ID you sent, or a list it names is not one of your account’s lists (or it is archived). Someone has to be a person in your account, captured by APAS® Cloud or imported, before they can go on a list: a visitor of your website who never filled in a form, booked or called is not a person yet. A refused request changes nothing.

413

The body is over 128 KB.

503

It could not be done this time. Send the same request again, after the seconds its Retry-After header says: sent twice, it changes nothing the second time. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "added": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "already": [],
  "lists": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "email was not used: lists find their person by apaspid, apasid or apasclid"
  ]
}
Response · 200, sent again
{
  "success": true,
  "added": [],
  "already": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "lists": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter"
    }
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}
Error response · 404
{
  "success": false,
  "error": "No person of this account matches the apaspid you sent. A list holds people, so they must have been captured by APAS® Cloud first.",
  "traceId": "7d2b9e4a1c6f"
}

Add to an audience

POSTingest.apascloud.com/audiences/<your client slug>

Adds a person to one of your audiences, or removes them: the audiences of Audiences, the same ones your team adds people to by hand on an audience's People card. Someone added is in the audience whatever its conditions say; someone removed stays out of it even when they match, until they are added again. Your audience can then hold the people your own system picks, beside or instead of the ones its conditions match.

Consent still applies to everyone: a person you add who gave no consent for ad platforms, or who opted out, stays out of the audience's ad-platform files and synced lists, exactly as a person who matches does.

Two things it does

add

Adds them to the audiences: they are in each whatever its conditions say, someone removed before included. An audience they were added to already is left as it is.

remove

Removes them from the audiences: they stay out of each even when they match its conditions, until they are added again. An audience they were removed from already is named in the answer, and nothing else changes.

One shape for both: the key says whether they are added to the audience or removed from it, and its value names it.

The body is JSON, one person in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a conversion, a fact, a tag and a list are sent with. Under Webhooks → Audiences the app writes the body out for you, with the audience you pick, ready to copy into your system.

Attributes

apaspidstringOne of the three

Who this is about, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. When you send more than one of the three, the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID. An audience holds people, so APAS® Cloud needs to recognise them: for someone who is not a person in your account yet, the send is refused rather than filed against nobody. Someone is a person once APAS® Cloud has captured them, or they were imported.

apasidstringOne of the three

Who this is about, by an APAS® ID of theirs: the ID of a browser they used, a UUID. For a system that holds that and not their APAS® Person ID.

apasclidstringOne of the three

Who this is about, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

addstring or array of stringsOne of the two

The audiences to add them to, by ID, as List audiences answers it: one, or several as a list or split by commas. Added, they are in each audience whatever its conditions say, and stay in until they are removed; someone removed before is back in. An audience they were added to already is left as it is. Send add or remove, never both: one payload does one thing.

removestring or array of stringsOne of the two

The audiences to remove them from, by ID: one, or several as a list or split by commas. Removed, they stay out of each audience even when they match its conditions, until they are added again. An audience they were removed from already is named in the answer, and nothing else changes.

What an audience is

  • An audience of your account's, named by its ID: List audiences answers every audience's ID, and Webhooks → Audiences writes it in for the audience you pick. Its name can change; its ID does not.
  • It holds everyone its conditions match, while they are on, and the people added to it, less the people removed from it. An audience whose conditions are off holds only the people added to it.
  • One request names 50 audiences at most.

What it does not carry

Only apaspid, apasid and apasclid say who is added. If you also send email or phone, it is not used and the answer says so: the rest is done.

What happens next

  • The person is in the audience on its People card within seconds, as added by your system, and in every count, file and sync that follows.
  • A synced audience starts its sync at once, so its list on your ad platform follows soon after.
  • You can read it back: List an audience's members returns them, with addedBy saying your system added them.
Request · add
curl -X POST \
  "https://ingest.apascloud.com/audiences/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "add": "cmhk7r2ab0003l508p9q8r7s6"
  }'
Response · 200
{
  "success": true,
  "added": [
    {
      "id": "cmhk7r2ab0003l508p9q8r7s6",
      "name": "VIP leads with a quote"
    }
  ],
  "already": [],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Remove from an audience

POSTingest.apascloud.com/audiences/<your client slug>

The same address and the same body as Add to an audience, with the audience under remove: the person stays out of it even when they match its conditions, until they are added again, and the audience stays as it is for everyone else in it.

An audience they were removed from already comes back under notIn, and nothing else changes, so removing someone twice is safe. A synced audience starts its sync at once, which takes them out of its list.

Request · remove
curl -X POST \
  "https://ingest.apascloud.com/audiences/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
    "remove": "cmhk7r2ab0003l508p9q8r7s6"
  }'
Response · 200
{
  "success": true,
  "removed": [
    {
      "id": "cmhk7r2ab0003l508p9q8r7s6",
      "name": "VIP leads with a quote"
    }
  ],
  "notIn": [],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Audience answers and errors

A request is refused only when it cannot be done: without one of the three IDs, without an audience or with more than 50, with both add and remove, for someone who is not a person in your account yet, or for an audience your account does not have. A refused request changes nothing. A field it takes that cannot be used is left out, the rest is done, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The note shown answers an add that was sent with an email too. The second answer is the same add sent again, right after: nothing changes. The error shown answers one sent for someone who is not a person in your account yet.

Returns

successboolean

true: it is done.

addedarray of objectsAfter an add

After an add: the audiences they were added to now.

alreadyarray of objectsAfter an add

After an add: the audiences they had been added to already, left as they were.

removedarray of objectsAfter a remove

After a remove: the audiences they were removed from now.

notInarray of objectsAfter a remove

After a remove: the audiences they had been removed from already, left as they were.

apaspidstring

The APAS® Person ID of the person: the apaspid Get a person takes.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left out. A field it does not take, such as a misspelt name, is ignored without a note. The rest is done all the same.

Each audience in them is an object:

idstring

The audience’s ID: the one List audiences answers, and the one a request names it by.

namestring

Its name, as your account spells it.

Status codes

200

Done: the answer says which audiences they were added to or removed from, and which were left as they were.

400

It cannot be done: it names nobody (none of apaspid, apasid and apasclid), it names no audience or more than 50, it carries both add and remove, or the body is not a JSON object. A refused request changes nothing. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

No person of your account matches the ID you sent, or an audience it names is not one of your account’s audiences (or it is archived). Someone has to be a person in your account, captured by APAS® Cloud or imported, before they can be added to an audience: a visitor of your website who never filled in a form, booked or called is not a person yet. A refused request changes nothing.

413

The body is over 128 KB.

503

It could not be done this time. Send the same request again, after the seconds its Retry-After header says: sent twice, it changes nothing the second time. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, with a note
{
  "success": true,
  "added": [
    {
      "id": "cmhk7r2ab0003l508p9q8r7s6",
      "name": "VIP leads with a quote"
    }
  ],
  "already": [],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "email was not used: audiences find their person by apaspid, apasid or apasclid"
  ]
}
Response · 200, sent again
{
  "success": true,
  "added": [],
  "already": [
    {
      "id": "cmhk7r2ab0003l508p9q8r7s6",
      "name": "VIP leads with a quote"
    }
  ],
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}
Error response · 404
{
  "success": false,
  "error": "No person of this account matches the apaspid you sent. An audience holds people, so they must have been captured by APAS® Cloud first.",
  "traceId": "7d2b9e4a1c6f"
}

Unsubscribe someone

POSTingest.apascloud.com/unsubscribes/<your client slug>

Unsubscribes someone from your Email Center email when they unsubscribe in your own system, such as your CRM. Email Center stops emailing them at once: no automation email and no broadcast, at any address of theirs, as when they unsubscribe from one of your emails. It is how your system's unsubscribes reach Email Center, as a person's email status takes Email Center's to your system.

It only unsubscribes. Only the person can subscribe again, from one of your emails: neither your system nor your team can do it for them.

The body is JSON, one person in a request, 128 KB at most. It is sent with your webhook secret, the same one a record, an event, a conversion, a fact, a tag and a list are sent with. Under Webhooks → Unsubscribes the app writes the body out for you, with your merge fields, ready to copy into your system. The two requests shown are the same unsubscribe: by the person's ID, and by their email alone.

Attributes

apaspidstringOne of the four

Who unsubscribed, by their APAS® Person ID, as Get a person answers it: the person, whichever browsers they used. Every email address your account holds for them is unsubscribed. Send it, or apasid, or apasclid: any one of the three finds the person, since all three are theirs. When you send more than one of the three, the APAS® Person ID is tried first, then the APAS® ID, then the APAS® Click ID.

apasidstringOne of the four

Who unsubscribed, by an APAS® ID of theirs: the ID of a browser they used, a UUID. For a system that holds that and not their APAS® Person ID.

apasclidstringOne of the four

Who unsubscribed, by an APAS® Click ID they arrived with: for a system that holds a click and neither ID.

emailstringOne of the four

Their email address, as your system holds it. It is unsubscribed itself, whether or not a person of your account holds it yet, so someone APAS® Cloud has not captured is kept from your emails from the moment they are. On its own it is enough. Sent with an ID, it is unsubscribed as well as every address of the person the ID finds; and when the ID finds nobody, the email is unsubscribed all the same.

Who it unsubscribes

  • With an ID: the person it finds, at every email address your account holds for them.
  • With an email: that address, whether or not a person of your account holds it yet. Someone your system knows and APAS® Cloud has not captured is kept from your emails from the moment they are.
  • With both: every address of the person the ID finds, and the email as well. An ID that finds nobody leaves the email to do it, and the answer says so.

What it does not carry

Only apaspid, apasid, apasclid and email say who unsubscribed. If you also send phone, it is not used and the answer says so: the rest is done.

It never subscribes anyone again. A request that asks it to is refused with a 400 and changes nothing: one carrying subscribe, subscribed or resubscribe with any value but false, or unsubscribe or unsubscribed set to false.

What happens next

  • Email Center sends them none of your emails from then on, and they leave the automations they are in, as when they unsubscribe from one of your emails.
  • In APAS® 360 their Email Status says Unsubscribed within seconds, and Get a person's email status answers unsubscribed, recorded by your_system, unless a bounce or a spam report already holds them.
  • An address that bounced stays bounced, with the unsubscribe kept beside it.
Request
curl -X POST \
  "https://ingest.apascloud.com/unsubscribes/acme" \
  -H "Authorization: Bearer <your webhook secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
  }'
Response · 200
{
  "success": true,
  "already": false,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Unsubscribe answers and errors

A request is refused only when it cannot be done: when it names nobody, when no person of your account matches the ID it sends and no email came with it, or when it asks to subscribe someone again. A refused request changes nothing. A field it takes that cannot be used is left out, the rest is done, and the answer's notes say what happened, one plain sentence each. A field it does not take, such as a misspelt name, is ignored without a note.

The first answer is to an email no person of your account holds yet: the unsubscribe is kept on the address. The second is the request shown sent again, right after: nothing changes. The note shown answers one sent with a phone too. The error shown answers one sent for someone who is not a person in your account yet, with no email.

Returns

successboolean

true: it is done. Email Center sends them none of your emails from now on.

alreadyboolean

true when nothing changed, because every address was kept from your emails already, by an unsubscribe or a spam report. Sending the same request again is safe.

apaspidstring or null

The APAS® Person ID of the person: the apaspid Get a person takes. null when no person of your account holds the email you sent yet: the unsubscribe is kept on the address, and holds once they are captured.

notesarray of stringsSometimes

Only when a field the endpoint takes could not be used as sent: one plain sentence for each that was left out. A field it does not take, such as a misspelt name, is ignored without a note. The rest is done all the same.

Status codes

200

Done: they are unsubscribed from your Email Center email, and already says whether they were before.

400

It cannot be done: it names nobody (none of apaspid, apasid, apasclid and email), its email is not an email address and no ID came with it, it asks to subscribe someone again, or the body is not a JSON object. A refused request changes nothing. error says which; a body that cannot be read as JSON at all is answered with the reason in message instead.

401

The webhook secret is missing, or is not a secret of the account in the address.

404

No person of your account matches the ID you sent and no email came with it, or the person it finds has no email address in your account and none came with it. Send their email too: it is unsubscribed whether or not they are a person in your account yet. A refused request changes nothing.

413

The body is over 128 KB.

503

It could not be done this time. Send the same request again, after the seconds its Retry-After header says: sent twice, it changes nothing the second time. Treat any status of 500 or above the same way.

Error body

successboolean

false.

errorstring

Why, in words. Written for a person to read, and its wording can change: have your system act on the status.

retryablebooleanSometimes

true on a 503: sending the same request again will work. Any status of 500 or above is safe to send again too.

requestId or traceIdstring

The ID of your request, to quote if you contact us about a delivery. It is named requestId on a 401 or a 413, and on a 503 when your request could not be passed on; traceId on every other answer.

Response · 200, not yet a person
{
  "success": true,
  "already": false,
  "apaspid": null
}
Response · 200, sent again
{
  "success": true,
  "already": true,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}
Response · 200, with a note
{
  "success": true,
  "already": false,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "notes": [
    "phone was not used: an unsubscribe finds who it is for by apaspid, apasid, apasclid or email"
  ]
}
Error response · 404
{
  "success": false,
  "error": "No person of this account matches the apaspid you sent. Send their email too, and the address is unsubscribed even if they are not a person in your account yet.",
  "traceId": "a41c7e93b2d5"
}
Read data

Authentication

Reading uses an API key, as a Bearer token on every request: Authorization: Bearer <your API key>. It is not your webhook secret: that one sends, and is refused here.

An Admin of your account creates a key in the app, under Integrations → Credentials → API Keys: name it and pick when it expires. The key is shown once. Sign in to create one.

  • A key reads everything in your account, with every read call on this page: there is nothing to switch on.
  • A key only reads. Nothing in your account can be changed with one.
  • A key expires after 90 days unless you pick another date, 365 days at most.
  • An Admin can revoke a key at any time, and it stops working at once.
  • Write Bearer as shown, with a capital B. A tool that cannot set that header can send the key in an X-API-Key header instead.
  • API keys are for server-side use only. Never put a key in a web page or an app. Anyone who opens a page can read the key in it, so a request that carries an Origin header, as every request from a web page does, is refused with a 403, on every call, and a browser is never allowed to call the API.
Addresses and headers
GET  https://api.apascloud.com/api/v1/account
GET  https://api.apascloud.com/api/v1/persons/<apaspid>
POST https://api.apascloud.com/api/v1/persons/search
GET  https://api.apascloud.com/api/v1/records
GET  https://api.apascloud.com/api/v1/conversions
GET  https://api.apascloud.com/api/v1/audiences
GET  https://api.apascloud.com/api/v1/lists
GET  https://api.apascloud.com/api/v1/clicks/<apasclid>
GET  https://api.apascloud.com/api/v1/persons/<apaspid>/credit
GET  https://api.apascloud.com/api/v1/events
GET  https://api.apascloud.com/api/v1/calls
GET  https://api.apascloud.com/api/v1/emails

Authorization: Bearer <your API key>

Errors

When a request is refused, the answer carries an HTTP status and a body that says why. The body has the same attributes on every call; its message says what was wrong. Every answer, a 200 included, carries its trace ID in an X-Trace-Id header: quote it if an answer looks wrong.

Status codes

400

Something in the request is not valid: a parameter the call does not take (a misspelt one included: the message names it) or one sent with no value, an ID that is too long, a field, a source or an event that does not exist, a search with no identifier or with more than one, a search body that is not a JSON object, an email or a phone in an address, dates that do not make a period, a limit that is not a whole number of 1 or more, a cursor that is not one a page gave, a value that is not text, or an audience that can no longer be read as it was saved (open it in the app and save it again). The message says which.

401

The key is missing, wrong, revoked or expired, or your account is no longer active. The answer does not say which.

403

The request carries an Origin header, as every request from a web page does: a key is for server-side use only.

404

No person, record, conversion, audience or list of your account has that ID, an archived audience or list included, or the address is not a call of the API. A search or a list that finds nothing is not an error: it answers an empty list.

413

The body of a search is over 64 KB.

429

The key, or your account across all its keys, is past its limit for the minute, or so many requests came from one IP address that it is held back for the minute. A read of your warehouse (the clicks, a person's credit, the events) also answers 429 once your account's reads have reached the day's limit, until midnight UTC.

500

Something failed on our side. Try again shortly; if it keeps failing, send us the traceId.

Error body

messagestring

Why the request was refused, in words. It names what was wrong, so it differs from one call to another. It is written for a person to read and its wording can change: have your tool act on the status.

errorstring

The name of the status, such as Not Found or Too Many Requests.

statusCodeinteger

The HTTP status as a number, the same as the status of the answer itself.

traceIdstring

The ID of your request. Give it to us if you contact us about a call.

Error response · 429
{
  "message": "Rate limit exceeded",
  "error": "Too Many Requests",
  "statusCode": 429,
  "traceId": "9f2c6e1ab47d"
}

Rate limits

Each key can make 60 requests a minute, unless we set another limit for it (its X-RateLimit-Limit says which), and all the keys of your account 600 a minute together, each minute counted from its first request. A refused request counts too, toward both. Past either limit the answer is 429: wait for X-RateLimit-Reset before trying again. Requests from one IP address are also held back when more than 300 arrive in a minute, whatever key they carry: that 429 carries a Retry-After header, the seconds to wait, in place of the X-RateLimit headers.

Headers

X-RateLimit-Limitinteger

Requests the key may make in a minute.

X-RateLimit-Remaininginteger

Requests left in the current minute: the fewer of your key's and your account's.

X-RateLimit-Resetinteger

When the current minute ends, as Unix time in milliseconds: the later of your key's and your account's.

Response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1794649260000

Versioning

The version is in the address: /api/v1. Version 1 only grows: calls and fields are added, and a field that is there keeps its name and its meaning. A change that would break what you built would come as a new version, under /api/v2. The addresses you send to carry no version.

Choosing fields

Every call answers with whole objects: the account, a person, a record, a conversion, an audience, a list or a click, and in a list each item. To get only some fields, name them in fields, separated by commas: ?fields=email,stage,firstTouch. In a search it goes in the JSON body, beside the identifier.

Query parameters

fieldsstringOptional

The fields you want, by name, separated by commas. Only those come back, with the ID, which always does: a person's apaspid, a record's, a conversion's, an audience's, a list's or the account's id. Leave it out to get every field. Use the top-level names: a field that is an object comes whole.

A name that is not a field is refused with a 400 that lists the fields, so a typing mistake never looks like an object without that value. The fields come back in the object's own order.

Request
curl -G \
  "https://api.apascloud.com/api/v1/persons/<apaspid>" \
  -d "fields=email,stage,firstTouch" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "email": "[email protected]",
  "stage": "green",
  "firstTouch": {
    "channel": "Organic Search",
    "platform": null,
    "referringDomain": "google.com",
    "at": "2026-10-02T16:45:00Z"
  }
}

The account object

Your account's own settings. They help you read everything else: every timestamp is in UTC while your reports count days in your time zone, values are in your currency, and each stage comes by its colour and has the name you gave it. Every attribute always holds a value but three: your website and your Edge Domain, until you set them, and your agreement, when an agency partner runs your account.

Attributes

idstring

Your account's ID. It never changes.

slugstring

Your client slug: the short name of your account, shown under Settings → Account. It is part of the addresses you send data to.

namestring

Your account's name.

statusstring

The status of your account: active, or onboarding while it is being set up.

createdAttimestamp

When your account was created.

websitestring or null

The domain your website runs on, as set under Settings → Account. null until you set one.

edgeDomainstring or null

Your Edge Domain: the subdomain of your own domain that your Edge URLs and the APAS® Analytics script run on. null until you connect one.

timeZonestring

The time zone of your account, as an IANA name. Every timestamp from the API is in UTC; your reports count days in this time zone.

currencystring

The currency of the values in your account, as an ISO 4217 code.

businessTypestring

Whom you sell to: b2c for consumers, b2b for businesses or for both.

hipaaboolean

Whether HIPAA compliance is on for your account.

agreementobject or null

Your service agreement with APAS® Cloud: whether it is signed, when and by whom, and what it includes. null when an agency partner runs your account, since its agreement covers yours.

Child attributes
agreement.statusstring

Where it stands: signed, new_signature_needed when the agreement was updated since you signed it, or when turning HIPAA compliance on or off since means another edition applies, or signature_needed when it has not been signed yet.

agreement.signedAttimestamp or null

When it was last signed, which is also the date it took effect. null until it is signed.

agreement.signedBystring or null

The name of the person who signed it. null until it is signed.

agreement.versionstring or null

The version that was signed, a whole number as text. null until it is signed.

agreement.baaboolean

Whether what you signed includes the HIPAA Business Associate Agreement. It is part of the agreement when HIPAA compliance is on, and is signed with it.

agreement.dpaboolean

Whether what you signed includes the Data Processing Agreement, for personal data under the GDPR and similar laws. It is part of every agreement from version 3, and is signed with it.

strictModeboolean

Whether Strict Mode is on. With it, ad platforms are sent no contact details.

consentModelstring

How consent is asked on your forms: opt-in, where someone must agree first, or opt-out, where they are counted in unless they decline.

stagesobject

Your own name for each of the five stages, or its default name (New lead, Qualified lead, Opportunity, Advanced stage, Customer) for a stage you have not named. A person and a record give their stage by its colour.

Child attributes
stages.redstring

Your name for the red stage, the first.

stages.orangestring

Your name for the orange stage.

stages.yellowstring

Your name for the yellow stage.

stages.whitestring

Your name for the white stage.

stages.greenstring

Your name for the green stage, the last: a customer.

analyticsScriptobject

The APAS® Analytics script APAS® Cloud serves your site.

Child attributes
analyticsScript.versionstring

The version APAS® Cloud serves, a whole number as text. Your site takes each new version by itself, unless something on it keeps its own copy, as a caching plugin can: the app flags that.

The account object
{
  "id": "cmf9k2d1w0003jv08x7b4q6ne",
  "slug": "acme",
  "name": "Acme Inc",
  "status": "active",
  "createdAt": "2026-10-01T15:04:11Z",
  "website": "example.com",
  "edgeDomain": "go.example.com",
  "timeZone": "America/New_York",
  "currency": "USD",
  "businessType": "b2b",
  "hipaa": false,
  "agreement": {
    "status": "signed",
    "signedAt": "2026-10-01T15:20:44Z",
    "signedBy": "Sam Rivera",
    "version": "3",
    "baa": false,
    "dpa": true
  },
  "strictMode": false,
  "consentModel": "opt-out",
  "stages": {
    "red": "Lead",
    "orange": "Qualified",
    "yellow": "Proposal sent",
    "white": "Negotiation",
    "green": "Customer"
  },
  "analyticsScript": {
    "version": "32"
  }
}

Get the account

GET/api/v1/account

Returns your account's details.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The account object.

Request
curl "https://api.apascloud.com/api/v1/account" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cmf9k2d1w0003jv08x7b4q6ne",
  "slug": "acme",
  "name": "Acme Inc",
  "status": "active",
  "createdAt": "2026-10-01T15:04:11Z",
  "website": "example.com",
  "edgeDomain": "go.example.com",
  "timeZone": "America/New_York",
  "currency": "USD",
  "businessType": "b2b",
  "hipaa": false,
  "agreement": {
    "status": "signed",
    "signedAt": "2026-10-01T15:20:44Z",
    "signedBy": "Sam Rivera",
    "version": "3",
    "baa": false,
    "dpa": true
  },
  "strictMode": false,
  "consentModel": "opt-out",
  "stages": {
    "red": "Lead",
    "orange": "Qualified",
    "yellow": "Proposal sent",
    "white": "Negotiation",
    "green": "Customer"
  },
  "analyticsScript": {
    "version": "32"
  }
}

The person object

One person of your account, as their APAS® 360 page shows them. Every attribute is always there: a value your account does not have is null, an empty list is [], and every timestamp is ISO 8601 in UTC.

Attributes

apaspidstring

Their APAS® Person ID: one per person, across every device, email and phone they used. If two persons were merged, the old ID still works and returns the merged person.

firstNamestring or null

Their first name.

lastNamestring or null

Their last name.

emailstring or null

Their email now: the newest they gave, or the one your team set.

phonestring or null

Their phone now, as they gave it or your team typed it.

consentboolean or null

Whether they consented: false when they declined on any record of theirs, or declined marketing cookies on the consent banner of any device of theirs; true when they agreed on a record and never declined; null when they were never asked.

strictModeboolean

Whether a record of theirs was captured under Strict Mode, your account setting that sends ad platforms no contact details.

stagestring or null

The furthest stage they have reached: red, orange, yellow, white or green.

stageAttimestamp or null

When they reached that stage.

firstCapturedAttimestamp

When they were first captured.

lastCapturedAttimestamp

When they were last captured.

tagsarray of strings

Their tags, by name, A to Z.

factsarray of objects

Their facts, newest first: every attribute your systems or your team set on them, at its current value, and their latest 50 events.

Child attributes
facts[].kindstring

What the fact is: attribute, for something true of the person, or event, for something that happened.

facts[].namestring

The name you gave it.

facts[].valuestring or null

An attribute's value, or the amount an event was worth, as text.

facts[].currencystring or null

The currency of the amount, when one was sent.

facts[].eventIdstring or null

The ID an event was sent with. An attribute has none.

facts[].propertiesobject or null

The names and values sent with it.

facts[].occurredAttimestamp

When it happened, or when the attribute took this value.

leadScoreinteger or null

Their lead score, once a flow has scored them.

apasidsarray of strings

Every APAS® ID of theirs: one for each device they used.

apasclidsarray of strings

Every APAS® Click ID they arrived with.

firstTouchobject

The visit First touch credits them to, as your reports do. Each of its fields is null when it credits no visit, and for up to about 15 minutes after a first capture, until their visits are read.

Child attributes
firstTouch.channelstring or null

The visit's channel, as Web Analytics names it: Paid Search, Organic Search, Direct and so on.

firstTouch.platformstring or null

The ad platform, when an ad brought the visit: Google Ads, for one, or Unknown platform when the ad named none.

firstTouch.referringDomainstring or null

The site the visit came from.

firstTouch.attimestamp or null

When the visit began.

lastTouchobject

The visit Last touch credits them to, as your reports do. Each of its fields is null when it credits no visit, likewise.

Child attributes
lastTouch.channelstring or null

The visit's channel, as Web Analytics names it: Paid Search, Organic Search, Direct and so on.

lastTouch.platformstring or null

The ad platform, when an ad brought the visit: Google Ads, for one, or Unknown platform when the ad named none.

lastTouch.referringDomainstring or null

The site the visit came from.

lastTouch.attimestamp or null

When the visit began.

initialAttributionobject

What their first capture carried.

Child attributes
initialAttribution.utmobject

The UTM tags: source, medium, campaign, term and content. Holds source, medium, campaign, term and content, each a string or null.

initialAttribution.clickIdsobject

The ad click IDs, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

initialAttribution.referrerstring or null

The page they came from.

initialAttribution.landingPagestring or null

The page they landed on.

initialAttribution.clickAttimestamp or null

When the ad click behind it happened.

latestAttributionobject

The latest known value of each, so a later capture without one never blanks it.

Child attributes
latestAttribution.utmobject

The UTM tags: source, medium, campaign, term and content. Holds source, medium, campaign, term and content, each a string or null.

latestAttribution.clickIdsobject

The ad click IDs, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

latestAttribution.referrerstring or null

The page they came from.

latestAttribution.landingPagestring or null

The page they landed on.

latestAttribution.clickAttimestamp or null

When the ad click behind it happened.

The person object
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "(201) 555-0123",
  "consent": true,
  "strictMode": false,
  "stage": "green",
  "stageAt": "2026-11-02T14:03:11Z",
  "firstCapturedAt": "2026-10-14T09:21:40Z",
  "lastCapturedAt": "2026-11-02T14:03:11Z",
  "tags": [
    "VIP"
  ],
  "facts": [
    {
      "kind": "attribute",
      "name": "tier",
      "value": "gold",
      "currency": null,
      "eventId": null,
      "properties": null,
      "occurredAt": "2026-11-03T15:00:00Z"
    },
    {
      "kind": "event",
      "name": "quote_sent",
      "value": "4200",
      "currency": "USD",
      "eventId": "Q-1042",
      "properties": {
        "plan": "annual"
      },
      "occurredAt": "2026-10-28T10:12:00Z"
    }
  ],
  "leadScore": 72,
  "apasids": [
    "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c"
  ],
  "apasclids": [
    "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f"
  ],
  "firstTouch": {
    "channel": "Organic Search",
    "platform": null,
    "referringDomain": "google.com",
    "at": "2026-10-02T16:45:00Z"
  },
  "lastTouch": {
    "channel": "Paid Search",
    "platform": "Google Ads",
    "referringDomain": "google.com",
    "at": "2026-10-14T09:20:05Z"
  },
  "initialAttribution": {
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "brand",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": "https://www.google.com/",
    "landingPage": "https://www.example.com/offer",
    "clickAt": "2026-10-14T09:20:00Z"
  },
  "latestAttribution": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "november",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": "https://www.google.com/",
    "landingPage": "https://www.example.com/pricing",
    "clickAt": "2026-10-14T09:20:00Z"
  }
}

Get a person

GET/api/v1/persons/<apaspid>

Returns one person of your account by their APAS® Person ID, or the person an APAS® ID (a browser they used) or an APAS® Click ID (an ad click they arrived with) belongs to.

Path parameters

apaspidstringRequired

The person's APAS® Person ID. You find it in APAS® 360 → Persons, in its own column and in the export, and on the person's page. If two persons were merged, the old ID still works and returns the merged person.

The address takes either of these in its place, and returns the same person:

apasid

An APAS® ID of theirs: any browser they used.

apasclid

An APAS® Click ID they arrived with.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The person object, or a 404 when no person of your account has that ID.

Request
curl "https://api.apascloud.com/api/v1/persons/<apaspid>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "(201) 555-0123",
  "consent": true,
  "strictMode": false,
  "stage": "green",
  "stageAt": "2026-11-02T14:03:11Z",
  "firstCapturedAt": "2026-10-14T09:21:40Z",
  "lastCapturedAt": "2026-11-02T14:03:11Z",
  "tags": [
    "VIP"
  ],
  "facts": [
    {
      "kind": "attribute",
      "name": "tier",
      "value": "gold",
      "currency": null,
      "eventId": null,
      "properties": null,
      "occurredAt": "2026-11-03T15:00:00Z"
    },
    {
      "kind": "event",
      "name": "quote_sent",
      "value": "4200",
      "currency": "USD",
      "eventId": "Q-1042",
      "properties": {
        "plan": "annual"
      },
      "occurredAt": "2026-10-28T10:12:00Z"
    }
  ],
  "leadScore": 72,
  "apasids": [
    "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c"
  ],
  "apasclids": [
    "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f"
  ],
  "firstTouch": {
    "channel": "Organic Search",
    "platform": null,
    "referringDomain": "google.com",
    "at": "2026-10-02T16:45:00Z"
  },
  "lastTouch": {
    "channel": "Paid Search",
    "platform": "Google Ads",
    "referringDomain": "google.com",
    "at": "2026-10-14T09:20:05Z"
  },
  "initialAttribution": {
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "brand",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": "https://www.google.com/",
    "landingPage": "https://www.example.com/offer",
    "clickAt": "2026-10-14T09:20:00Z"
  },
  "latestAttribution": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "november",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": "https://www.google.com/",
    "landingPage": "https://www.example.com/pricing",
    "clickAt": "2026-10-14T09:20:00Z"
  }
}

Find a person

POST/api/v1/persons/search

Returns the person an identifier belongs to, when your tool holds an email, a phone number, an APAS® ID or an APAS® Click ID and not the APAS® Person ID. Give exactly one identifier: another one present, even as null, is refused, and so is any other key or an empty value. When more than one person has that value, the one captured first is returned.

Any value the person ever appeared under finds them, not only their current one. Send the identifier in a JSON body, as it is: an email or a phone number never goes in the address, which proxies, logs and browser histories keep.

An APAS® ID or an APAS® Click ID can also go in the query, with the same answer: GET /api/v1/persons?apasid=3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c. An email or a phone number in that query is refused with a 400.

Body

emailstringOne of these

An email address. Capitals do not matter, and any email the person ever gave finds them.

phonestringOne of these

A phone number, however it is written: it is matched on its last 10 digits. Any phone the person ever gave finds them.

apasidstringOne of these

An APAS® ID. Any browser of theirs finds them.

apasclidstringOne of these

An APAS® Click ID they arrived with.

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

A list, items, holding the person object found. When nobody has that value the list is empty and the answer is still a 200: finding nobody is an answer, not an error. total is 1 or 0, and nextCursor is always null here.

Request
curl -X POST \
  "https://api.apascloud.com/api/v1/persons/search" \
  -H "Authorization: Bearer <your API key>" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'
Response · 200
{
  "items": [
    {
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "(201) 555-0123",
      "consent": true,
      "strictMode": false,
      "stage": "green",
      "stageAt": "2026-11-02T14:03:11Z",
      "firstCapturedAt": "2026-10-14T09:21:40Z",
      "lastCapturedAt": "2026-11-02T14:03:11Z",
      "tags": [
        "VIP"
      ],
      "facts": [
        {
          "kind": "attribute",
          "name": "tier",
          "value": "gold",
          "currency": null,
          "eventId": null,
          "properties": null,
          "occurredAt": "2026-11-03T15:00:00Z"
        },
        {
          "kind": "event",
          "name": "quote_sent",
          "value": "4200",
          "currency": "USD",
          "eventId": "Q-1042",
          "properties": {
            "plan": "annual"
          },
          "occurredAt": "2026-10-28T10:12:00Z"
        }
      ],
      "leadScore": 72,
      "apasids": [
        "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c"
      ],
      "apasclids": [
        "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f"
      ],
      "firstTouch": {
        "channel": "Organic Search",
        "platform": null,
        "referringDomain": "google.com",
        "at": "2026-10-02T16:45:00Z"
      },
      "lastTouch": {
        "channel": "Paid Search",
        "platform": "Google Ads",
        "referringDomain": "google.com",
        "at": "2026-10-14T09:20:05Z"
      },
      "initialAttribution": {
        "utm": {
          "source": "google",
          "medium": "cpc",
          "campaign": "brand",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/offer",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "latestAttribution": {
        "utm": {
          "source": "newsletter",
          "medium": "email",
          "campaign": "november",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/pricing",
        "clickAt": "2026-10-14T09:20:00Z"
      }
    }
  ],
  "nextCursor": null,
  "total": 1
}
Nobody found · 200
{
  "items": [],
  "nextCursor": null,
  "total": 0
}

The record object

One capture, whatever it came from: a form or a quiz submission, a booking, a call, a text. It is a snapshot of who they were and how they came, as APAS® 360 → Records lists it, and its stage is kept current. A person has one record for every time they were captured.

Attributes

idstring

The record's ID.

apaspidstring or null

The APAS® Person ID of the person it belongs to. null until it is matched to one.

sourcestring

What it came from: form, quiz, scheduler, call, sms and the others listed under List records.

sourceNamestring or null

Which one: the name of the form, the quiz or the scheduler, or the tracking line a call or a text came in on.

capturedAttimestamp

When it was captured.

firstNamestring or null

Their first name, as captured.

lastNamestring or null

Their last name, as captured.

emailstring or null

Their email, as captured.

phonestring or null

Their phone, as captured.

consentboolean or null

The consent given with this capture: true, false for a decline, or null when it was not asked.

strictModeboolean

Whether it was captured under Strict Mode, your account setting that sends ad platforms no contact details.

stagestring or null

The furthest stage reached: red, orange, yellow, white or green.

stageAttimestamp or null

When that stage was reached.

apasidstring or null

The APAS® ID of the device it came from.

apasclidstring or null

The APAS® Click ID it came with.

attributionobject

Its UTM tags, click IDs and landing page: as captured, or, where the capture had none, recovered from the ad click its APAS® Click ID points to, or else from its landing visit.

Child attributes
attribution.utmobject

The UTM tags: source, medium, campaign, term and content. Holds source, medium, campaign, term and content, each a string or null.

attribution.clickIdsobject

The ad click IDs, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

attribution.referrerstring or null

The page they came from.

attribution.landingPagestring or null

The page they landed on.

attribution.clickAttimestamp or null

When the ad click behind it happened.

customFieldsobject or null

What they sent with it: the answers of a form or a quiz, the time of a booking.

callobject or null

On a call record, the call itself. null on every other record.

Child attributes
call.statusstring

The call's status, in capitals: INITIATED, RINGING, IN_PROGRESS, COMPLETED, FAILED, BUSY, NO_ANSWER, CANCELED, MISSED or REJECTED.

call.directionstring or null

inbound or outbound.

call.durationSecondsinteger or null

How long it lasted, in seconds.

The record object
{
  "id": "cmhi3x9qk0007l508a1b2c3d4",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "source": "form",
  "sourceName": "Contact form (external)",
  "capturedAt": "2026-11-02T14:03:11Z",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "2015550123",
  "consent": true,
  "strictMode": false,
  "stage": "green",
  "stageAt": "2026-11-02T14:03:11Z",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "attribution": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "november",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": null,
    "landingPage": "https://www.example.com/pricing",
    "clickAt": "2026-10-14T09:20:00Z"
  },
  "customFields": {
    "company": "Example Inc",
    "message": "Please call me about the annual plan."
  },
  "call": null
}

List records

GET/api/v1/records

Returns the records of a period, newest first: the last 30 days unless you give one. With apaspid, apasid or apasclid it returns one person's records, which is their timeline: give one, as the first that names someone, in that order, is used, and an ID that is nobody's returns an empty list. Narrowed to one person, the period is only what you give. A date alone is midnight UTC. A parameter the call does not take, a misspelt one included, is refused with a 400 that names it: apasId never reads as apasid.

Query parameters

fromstringOptional

The start of the period, in ISO 8601. Left out, it is 30 days before the end.

tostringOptional

The end of the period, in ISO 8601. Left out, it is now. A period is at most 93 days.

sourcestringOptional

Only the records of one source.

apaspidstringOptional

Only one person's records, by their APAS® Person ID. With it the period is not needed: left out, every record of theirs comes back.

apasidstringOptional

Only one person's records, by an APAS® ID of theirs in place of apaspid: every record of the person that device belongs to, whatever device each came from.

apasclidstringOptional

Only one person's records, by an APAS® Click ID they arrived with, in place of apaspid.

limitintegerOptional

How many records a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with. See Choosing fields.

Sources

form

A form submission.

quiz

A quiz submission.

scheduler

A booking.

call

A phone call.

sms

A text message.

rag

A conversation with the earlier website chat, which APAS® Cloud no longer offers: only older records carry it.

banner

A capture by a banner on your site.

signup

A signup.

optout

An opt-out of sharing with advertisers: from your Do Not Sell or Share link, its sourceName Do Not Sell page, or sent by your own system with Opt someone out, its sourceName Your system.

import

A contact you imported.

crm

A stage your CRM sent for someone APAS® Cloud did not hold yet.

payment

A payment by someone APAS® Cloud did not hold yet.

Returns

A list: items holds record objects, total says how many records match, over every page, and nextCursor is what to send as cursor for the next page, with the same parameters, or null on the last one. A period with no record is an empty list and a 200.

Request
curl -G "https://api.apascloud.com/api/v1/records" \
  -d "source=form" \
  -d "limit=50" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "items": [
    {
      "id": "cmhi3x9qk0007l508a1b2c3d4",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "source": "form",
      "sourceName": "Contact form (external)",
      "capturedAt": "2026-11-02T14:03:11Z",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "2015550123",
      "consent": true,
      "strictMode": false,
      "stage": "green",
      "stageAt": "2026-11-02T14:03:11Z",
      "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "attribution": {
        "utm": {
          "source": "newsletter",
          "medium": "email",
          "campaign": "november",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": null,
        "landingPage": "https://www.example.com/pricing",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "customFields": {
        "company": "Example Inc",
        "message": "Please call me about the annual plan."
      },
      "call": null
    }
  ],
  "nextCursor": null,
  "total": 1
}
One person's records
curl -G "https://api.apascloud.com/api/v1/records" \
  -d "apaspid=<apaspid>" \
  -H "Authorization: Bearer <your API key>"

Get a record

GET/api/v1/records/<id>

Returns one record of your account by its ID.

Path parameters

idstringRequired

The record's ID, as a list gives it.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The record object, or a 404 when no record of your account has that ID.

Request
curl "https://api.apascloud.com/api/v1/records/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cmhi3x9qk0007l508a1b2c3d4",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "source": "form",
  "sourceName": "Contact form (external)",
  "capturedAt": "2026-11-02T14:03:11Z",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "2015550123",
  "consent": true,
  "strictMode": false,
  "stage": "green",
  "stageAt": "2026-11-02T14:03:11Z",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "attribution": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "november",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "referrer": null,
    "landingPage": "https://www.example.com/pricing",
    "clickAt": "2026-10-14T09:20:00Z"
  },
  "customFields": {
    "company": "Example Inc",
    "message": "Please call me about the annual plan."
  },
  "call": null
}

The conversion object

One conversion APAS® Cloud received: a stage a person reached, by its colour, or a form, a quiz, a booking or a call that one of your modules captured. It is the conversion as Conversions → Health lists it, with what became of it: every ad platform it was sent to, when, and what the platform answered.

Each upload carries what APAS® Cloud set out to send and what came back, whole: every key and every level. The payload as it went to the ad platform and the platform's answer are in the response. The API reaches 90 days back, by convertedAt, and a conversion appears within about 15 minutes of its arrival.

Attributes

idstring

The conversion's ID, as Conversions → Health shows it.

eventstring

What it is: a stage by its colour (red, orange, yellow, white, green), or what one of your modules captured (form_submitted, quiz_submitted, scheduler_submitted, phone_call). What you call each stage is in the account object's stages.

convertedAttimestamp

When it happened: the time your system sent with it. A red sent without one is dated from when APAS® Cloud first captured the person, or from when it arrived if APAS® Cloud never captured them; any other stage sent without one, from when it arrived.

receivedAttimestamp or null

When APAS® Cloud first received it.

sourcestring

Where it came from: webhook, upload, stages, fill, form, quiz, scheduler, call or flow.

statusstring

What became of it: never_processed, processing, processed, retrying, rejected, failed, unattributed, no_consent, bot_gated, window_expired, filtered, short_call or imported.

recordIdstring or null

The record ID it was sent with: your system's own, or, for a stage APAS® 360 recorded (stages, fill), the id of the person's record in the records calls. null for a module's conversion.

eventIdstring or null

The ID of this occurrence it was sent with, such as a sale's or an invoice's: your system's own, or APAS® 360's for a stage it recorded.

valuenumber or null

The amount your system reported on a sale: the first one it sent, on whichever delivery first carried one. A sale sent again with another amount keeps this one here, while your reports take the last. null until it reports one, even when an ad platform was sent the stage's bidding value meanwhile: each upload's value says what it was sent.

currencystring or null

Your account's currency, which the value is counted in. Given whether or not a value was reported.

apaspidstring or null

The APAS® Person ID of the person it belongs to. null when it arrived with nothing a person of yours is known by.

apasidstring or null

The APAS® ID it arrived with: the device.

apasclidstring or null

The APAS® Click ID it arrived with.

clickIdsobject

Each ad click ID it carries, under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

propertiesobject or null

The properties it carries, as your system sent them or as APAS® 360 recorded them with the stage.

uploadsarray of objects

Each ad platform it was sent to, with how and when it was sent and what the platform answered, or held back from, with why. Empty when no ad platform was considered.

Child attributes
uploads[].platformstring

The ad platform: google-ads, bing-ads (Microsoft Ads), meta-ads, tiktok-ads, linkedin-ads, x-ads or reddit-ads.

uploads[].statusstring

How the platform answered: accepted, rejected, duplicate, skipped, retrying or waiting.

uploads[].sentAttimestamp or null

When it was last sent to the platform; on a skipped upload, when it was held back.

uploads[].sentAsstring or null

The name it was sent under. A stage is always sent by its colour, never by the name you gave it.

uploads[].valuenumber or null

The value sent to the platform, which can differ from the one received: a stage with no amount of its own goes with the value you set for bidding.

uploads[].currencystring or null

The currency of the value sent.

uploads[].referencestring or null

The platform's own ID for the upload, to look it up there.

uploads[].errorstring or null

The platform's answer when it refused, in its own words.

uploads[].errorCodestring or null

The platform's own code for the refusal.

uploads[].errorClassstring or null

What can fix a refusal: temporary (tried again by itself), reconnect, setup, rejected or too_old.

uploads[].reasonstring or null

Why it was skipped for this platform.

uploads[].attemptsinteger or null

How many times it was sent.

uploads[].nextAttemptAttimestamp or null

When it is tried again: while it is retrying, or waiting for something only you can fix. null otherwise.

uploads[].deadlineAttimestamp or null

When the platform stops accepting it.

uploads[].verdictstring or null

Google Ads only: its later verdict on the upload, once it has one.

uploads[].verdictAttimestamp or null

When that verdict was read.

uploads[].requestobject or null

What APAS® Cloud set out to send for this upload, whole: the event, its click IDs, its value and its hashed identifiers. null when nothing was sent.

uploads[].responseobject or null

What came back, whole: it holds the payload as it went to the ad platform and the platform's own answer. null when nothing was sent.

Sources

webhook

It came in at your conversions address: from your own system, or from a Send Conversion step in one of your APAS® Flows.

upload

Someone on your team typed it in or uploaded it in a file, under Conversions → Uploads.

stages

APAS® 360 recorded it: a move on the Stages board, a sale, or a new lead as it arrived.

fill

APAS® Cloud recorded it because a later stage arrived without this one.

form

One of your forms captured it.

quiz

One of your quizzes captured it.

scheduler

One of your schedulers captured it.

call

A call to one of your tracking numbers.

flow

One of your APAS® Flows recorded it some other way.

Statuses

never_processed

It was received and is waiting for the next run, within the hour.

processing

It is being sent now.

processed

It was sent to at least one ad platform, or held back because the person had already reached this stage, which goes to each ad platform once per person: each upload says sent or skipped, and why.

retrying

It is not through yet: an ad platform is tried again, or waits for you to reconnect it or fix a setting. Each upload says which.

rejected

Every ad platform it was sent to refused it for good, or kept failing for 14 days so it is no longer tried. Each upload says why.

failed

Sending it failed. Each upload says why.

unattributed

It carries no ad click, so there is no ad platform to send it to.

no_consent

The person declined advertising, so it was not sent.

bot_gated

Its APAS® Bot Score is below the minimum you set for the stage, so it was not sent.

window_expired

Its ad click is older than the ad platform accepts.

filtered

Your activation filter for the stage left it out.

short_call

It is held: so far the person only called, for less than your minimum call length.

imported

The person reached this stage before you imported them, so it is never sent to an ad platform.

Upload statuses

accepted

The ad platform took it.

rejected

The ad platform refused it, or it kept failing for 14 days and is no longer tried: errorClass says which, and error holds the last answer.

duplicate

The ad platform already had it.

skipped

It was not sent to this platform. reason says why.

retrying

It failed for now and is tried again at nextAttemptAt.

waiting

It waits for you: reconnect the platform or fix a setting, and it goes.

The conversion object
{
  "id": "-8412550917365402113",
  "event": "green",
  "convertedAt": "2026-11-02T14:03:11Z",
  "receivedAt": "2026-11-02T14:03:19Z",
  "source": "webhook",
  "status": "processed",
  "recordId": "006Qy00000ABC12",
  "eventId": "INV-1042",
  "value": 4200,
  "currency": "USD",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": "IwAR-example",
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "properties": {
    "plan": "annual"
  },
  "uploads": [
    {
      "platform": "google-ads",
      "status": "accepted",
      "sentAt": "2026-11-02T14:41:07Z",
      "sentAs": "green",
      "value": 4200,
      "currency": "USD",
      "reference": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
      "error": null,
      "errorCode": null,
      "errorClass": null,
      "reason": null,
      "attempts": 1,
      "nextAttemptAt": null,
      "deadlineAt": "2027-01-12T09:20:00Z",
      "verdict": "SUCCESS",
      "verdictAt": "2026-11-03T02:10:00Z",
      "request": {
        "client": "acme",
        "data": {
          "eventName": "green",
          "type": "green",
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "timestamp": "2026-11-02T14:03:11Z",
          "value": 4200,
          "currency": "USD",
          "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
          "hashedPhone": null,
          "eventId": "-8412550917365402113"
        }
      },
      "response": {
        "success": true,
        "platform": "google-ads",
        "action": "conversion",
        "result": {
          "conversionId": "7123456789",
          "transport": "data-manager",
          "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
          "status": "success",
          "httpStatus": 200,
          "httpStatusText": "OK",
          "timestamp": "2026-11-02T14:41:07.512Z",
          "sent_payload": {
            "destinations": [
              {
                "reference": "ca_7123456789",
                "operatingAccount": {
                  "accountType": "GOOGLE_ADS",
                  "accountId": "1234567890"
                },
                "productDestinationId": "7123456789"
              }
            ],
            "events": [
              {
                "eventTimestamp": "2026-11-02T14:03:11.000Z",
                "conversionValue": 4200,
                "currency": "USD",
                "eventSource": "WEB",
                "adIdentifiers": {
                  "gclid": "EAIaIQobChMI-example"
                },
                "userData": {
                  "userIdentifiers": [
                    {
                      "emailAddress": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e"
                    }
                  ]
                },
                "transactionId": "-8412550917365402113",
                "destinationReferences": [
                  "ca_7123456789"
                ]
              }
            ],
            "encoding": "HEX",
            "consent": {
              "adUserData": "CONSENT_GRANTED",
              "adPersonalization": "CONSENT_GRANTED"
            },
            "validateOnly": false
          },
          "api_response": {
            "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69"
          }
        }
      }
    },
    {
      "platform": "meta-ads",
      "status": "rejected",
      "sentAt": "2026-11-02T14:41:09Z",
      "sentAs": "green",
      "value": 4200,
      "currency": "USD",
      "reference": null,
      "error": "Invalid parameter",
      "errorCode": "100",
      "errorClass": "rejected",
      "reason": null,
      "attempts": 1,
      "nextAttemptAt": null,
      "deadlineAt": "2026-11-09T14:03:11Z",
      "verdict": null,
      "verdictAt": null,
      "request": {
        "client": "acme",
        "data": {
          "eventName": "green",
          "type": "green",
          "fbclid": "IwAR-example",
          "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
          "timestamp": "2026-11-02T14:03:11Z",
          "value": 4200,
          "currency": "USD",
          "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
          "hashedPhone": null,
          "eventId": "-8412550917365402113"
        }
      },
      "response": {
        "success": false,
        "error": "Invalid parameter",
        "failure": {
          "class": "rejected",
          "code": "100",
          "message": "Invalid parameter",
          "known": true
        },
        "details": {
          "meta_error": {
            "message": "Invalid parameter",
            "type": "OAuthException",
            "code": 100,
            "fbtrace_id": "AbCdEfGhIjKlMnOp"
          },
          "status_code": 400,
          "event_count": 1
        },
        "request_id": "5d2c8f1a-7b3e-4a6d-9c10-2e4f6a8b0c1d"
      }
    }
  ]
}

List conversions

GET/api/v1/conversions

Returns the conversions of a period, newest first: the last 30 days unless you give one. With recordId it returns the conversions sent with that record ID, and with apaspid, apasid or apasclid one person's: give one, as the first that names someone, in that order, is used. The period, the order and the cursor run on convertedAt, when it happened, not when it arrived; narrowed to one person or one record ID, the period is only what you give. A date alone is midnight UTC. A parameter the call does not take, a misspelt one included, is refused with a 400 that names it.

Query parameters

fromstringOptional

The start of the period, in ISO 8601. Left out, it is 30 days before the end.

tostringOptional

The end of the period, in ISO 8601. Left out, it is now. A period is at most 93 days, and the API reaches 90 days back.

eventstringOptional

Only the conversions of one event, such as green.

recordIdstringOptional

Only the conversions your system sent for one of its records, by the record ID it sent. With it the period is not needed.

apaspidstringOptional

Only one person's conversions, by their APAS® Person ID. With it the period is not needed.

apasidstringOptional

Only one person's conversions, by an APAS® ID of theirs in place of apaspid: every conversion of the person that device belongs to, not only the ones that arrived with it.

apasclidstringOptional

Only one person's conversions, by an APAS® Click ID they arrived with, in place of apaspid.

limitintegerOptional

How many conversions a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with. See Choosing fields.

Events

red

The red stage, the first: a new lead.

orange

The orange stage, the second.

yellow

The yellow stage, the third.

white

The white stage, the fourth.

green

The green stage, the last: a customer. One for every sale.

form_submitted

A form submission.

quiz_submitted

A quiz submission.

scheduler_submitted

A booking.

phone_call

An answered call.

Returns

A list: items holds conversion objects, total says how many the list holds in all, and nextCursor is what to send as cursor for the next page, or null on the last one. A period with no conversion is an empty list and a 200.

Request
curl -G "https://api.apascloud.com/api/v1/conversions" \
  -d "event=green" \
  -d "limit=50" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "items": [
    {
      "id": "-8412550917365402113",
      "event": "green",
      "convertedAt": "2026-11-02T14:03:11Z",
      "receivedAt": "2026-11-02T14:03:19Z",
      "source": "webhook",
      "status": "processed",
      "recordId": "006Qy00000ABC12",
      "eventId": "INV-1042",
      "value": 4200,
      "currency": "USD",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": "IwAR-example",
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "properties": {
        "plan": "annual"
      },
      "uploads": [
        {
          "platform": "google-ads",
          "status": "accepted",
          "sentAt": "2026-11-02T14:41:07Z",
          "sentAs": "green",
          "value": 4200,
          "currency": "USD",
          "reference": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
          "error": null,
          "errorCode": null,
          "errorClass": null,
          "reason": null,
          "attempts": 1,
          "nextAttemptAt": null,
          "deadlineAt": "2027-01-12T09:20:00Z",
          "verdict": "SUCCESS",
          "verdictAt": "2026-11-03T02:10:00Z",
          "request": {
            "client": "acme",
            "data": {
              "eventName": "green",
              "type": "green",
              "gclid": "EAIaIQobChMI-example",
              "gbraid": null,
              "wbraid": null,
              "timestamp": "2026-11-02T14:03:11Z",
              "value": 4200,
              "currency": "USD",
              "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
              "hashedPhone": null,
              "eventId": "-8412550917365402113"
            }
          },
          "response": {
            "success": true,
            "platform": "google-ads",
            "action": "conversion",
            "result": {
              "conversionId": "7123456789",
              "transport": "data-manager",
              "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
              "status": "success",
              "httpStatus": 200,
              "httpStatusText": "OK",
              "timestamp": "2026-11-02T14:41:07.512Z",
              "sent_payload": {
                "destinations": [
                  {
                    "reference": "ca_7123456789",
                    "operatingAccount": {
                      "accountType": "GOOGLE_ADS",
                      "accountId": "1234567890"
                    },
                    "productDestinationId": "7123456789"
                  }
                ],
                "events": [
                  {
                    "eventTimestamp": "2026-11-02T14:03:11.000Z",
                    "conversionValue": 4200,
                    "currency": "USD",
                    "eventSource": "WEB",
                    "adIdentifiers": {
                      "gclid": "EAIaIQobChMI-example"
                    },
                    "userData": {
                      "userIdentifiers": [
                        {
                          "emailAddress": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e"
                        }
                      ]
                    },
                    "transactionId": "-8412550917365402113",
                    "destinationReferences": [
                      "ca_7123456789"
                    ]
                  }
                ],
                "encoding": "HEX",
                "consent": {
                  "adUserData": "CONSENT_GRANTED",
                  "adPersonalization": "CONSENT_GRANTED"
                },
                "validateOnly": false
              },
              "api_response": {
                "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69"
              }
            }
          }
        },
        {
          "platform": "meta-ads",
          "status": "rejected",
          "sentAt": "2026-11-02T14:41:09Z",
          "sentAs": "green",
          "value": 4200,
          "currency": "USD",
          "reference": null,
          "error": "Invalid parameter",
          "errorCode": "100",
          "errorClass": "rejected",
          "reason": null,
          "attempts": 1,
          "nextAttemptAt": null,
          "deadlineAt": "2026-11-09T14:03:11Z",
          "verdict": null,
          "verdictAt": null,
          "request": {
            "client": "acme",
            "data": {
              "eventName": "green",
              "type": "green",
              "fbclid": "IwAR-example",
              "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
              "timestamp": "2026-11-02T14:03:11Z",
              "value": 4200,
              "currency": "USD",
              "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
              "hashedPhone": null,
              "eventId": "-8412550917365402113"
            }
          },
          "response": {
            "success": false,
            "error": "Invalid parameter",
            "failure": {
              "class": "rejected",
              "code": "100",
              "message": "Invalid parameter",
              "known": true
            },
            "details": {
              "meta_error": {
                "message": "Invalid parameter",
                "type": "OAuthException",
                "code": 100,
                "fbtrace_id": "AbCdEfGhIjKlMnOp"
              },
              "status_code": 400,
              "event_count": 1
            },
            "request_id": "5d2c8f1a-7b3e-4a6d-9c10-2e4f6a8b0c1d"
          }
        }
      ]
    }
  ],
  "nextCursor": null,
  "total": 1
}
Conversions for one record ID
curl -G "https://api.apascloud.com/api/v1/conversions" \
  -d "recordId=<recordId>" \
  -H "Authorization: Bearer <your API key>"
One person's conversions
curl -G "https://api.apascloud.com/api/v1/conversions" \
  -d "apaspid=<apaspid>" \
  -H "Authorization: Bearer <your API key>"

Get a conversion

GET/api/v1/conversions/<id>

Returns one conversion of your account by its ID.

Path parameters

idstringRequired

The conversion's ID, as a list gives it and as Conversions → Health shows it.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The conversion object, or a 404 when no conversion of your account has that ID. A conversion dated more than 90 days ago answers a 404 too, though Conversions → Health still shows it.

Request
curl "https://api.apascloud.com/api/v1/conversions/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "-8412550917365402113",
  "event": "green",
  "convertedAt": "2026-11-02T14:03:11Z",
  "receivedAt": "2026-11-02T14:03:19Z",
  "source": "webhook",
  "status": "processed",
  "recordId": "006Qy00000ABC12",
  "eventId": "INV-1042",
  "value": 4200,
  "currency": "USD",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": "IwAR-example",
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "properties": {
    "plan": "annual"
  },
  "uploads": [
    {
      "platform": "google-ads",
      "status": "accepted",
      "sentAt": "2026-11-02T14:41:07Z",
      "sentAs": "green",
      "value": 4200,
      "currency": "USD",
      "reference": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
      "error": null,
      "errorCode": null,
      "errorClass": null,
      "reason": null,
      "attempts": 1,
      "nextAttemptAt": null,
      "deadlineAt": "2027-01-12T09:20:00Z",
      "verdict": "SUCCESS",
      "verdictAt": "2026-11-03T02:10:00Z",
      "request": {
        "client": "acme",
        "data": {
          "eventName": "green",
          "type": "green",
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "timestamp": "2026-11-02T14:03:11Z",
          "value": 4200,
          "currency": "USD",
          "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
          "hashedPhone": null,
          "eventId": "-8412550917365402113"
        }
      },
      "response": {
        "success": true,
        "platform": "google-ads",
        "action": "conversion",
        "result": {
          "conversionId": "7123456789",
          "transport": "data-manager",
          "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69",
          "status": "success",
          "httpStatus": 200,
          "httpStatusText": "OK",
          "timestamp": "2026-11-02T14:41:07.512Z",
          "sent_payload": {
            "destinations": [
              {
                "reference": "ca_7123456789",
                "operatingAccount": {
                  "accountType": "GOOGLE_ADS",
                  "accountId": "1234567890"
                },
                "productDestinationId": "7123456789"
              }
            ],
            "events": [
              {
                "eventTimestamp": "2026-11-02T14:03:11.000Z",
                "conversionValue": 4200,
                "currency": "USD",
                "eventSource": "WEB",
                "adIdentifiers": {
                  "gclid": "EAIaIQobChMI-example"
                },
                "userData": {
                  "userIdentifiers": [
                    {
                      "emailAddress": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e"
                    }
                  ]
                },
                "transactionId": "-8412550917365402113",
                "destinationReferences": [
                  "ca_7123456789"
                ]
              }
            ],
            "encoding": "HEX",
            "consent": {
              "adUserData": "CONSENT_GRANTED",
              "adPersonalization": "CONSENT_GRANTED"
            },
            "validateOnly": false
          },
          "api_response": {
            "requestId": "7f3c9a1e-2b4d-4c6f-8a90-1e2d3c4b5a69"
          }
        }
      }
    },
    {
      "platform": "meta-ads",
      "status": "rejected",
      "sentAt": "2026-11-02T14:41:09Z",
      "sentAs": "green",
      "value": 4200,
      "currency": "USD",
      "reference": null,
      "error": "Invalid parameter",
      "errorCode": "100",
      "errorClass": "rejected",
      "reason": null,
      "attempts": 1,
      "nextAttemptAt": null,
      "deadlineAt": "2026-11-09T14:03:11Z",
      "verdict": null,
      "verdictAt": null,
      "request": {
        "client": "acme",
        "data": {
          "eventName": "green",
          "type": "green",
          "fbclid": "IwAR-example",
          "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
          "timestamp": "2026-11-02T14:03:11Z",
          "value": 4200,
          "currency": "USD",
          "hashedEmail": "1f3870be274f6c49b3e31a0c6728957f2e3e5b7c8d9a0b1c2d3e4f5a6b7c8d9e",
          "hashedPhone": null,
          "eventId": "-8412550917365402113"
        }
      },
      "response": {
        "success": false,
        "error": "Invalid parameter",
        "failure": {
          "class": "rejected",
          "code": "100",
          "message": "Invalid parameter",
          "known": true
        },
        "details": {
          "meta_error": {
            "message": "Invalid parameter",
            "type": "OAuthException",
            "code": 100,
            "fbtrace_id": "AbCdEfGhIjKlMnOp"
          },
          "status_code": 400,
          "event_count": 1
        },
        "request_id": "5d2c8f1a-7b3e-4a6d-9c10-2e4f6a8b0c1d"
      }
    }
  ]
}

The audience object

One audience of your account, as Audiences builds it: what it asks of a person, the people added to it or removed from it by ID, and how many people it holds. Who is in it is worked out each time you ask: everyone who matches what it asks, while its conditions are on, and everyone added to it, less everyone removed from it. So someone who opted out a minute ago is already left out. A stage counts once it reaches the person: within minutes of a move on the Stages board, within about an hour of one your CRM or your systems send. What it asks never takes a new lead (no stage yet, or red) whom the bot verdict calls automated: a verified bot, or an APAS® Bot Score of 1 to 29. Someone added to it by ID is in it all the same.

Its counts are of the people APAS® Cloud tracks. An audience that also takes the contacts of your CRM reads them from your CRM when you open, download or sync it, and they are not counted here.

Attributes

idstring

The audience's ID.

namestring

Its name.

descriptionstring or null

What it is for, as your team wrote it.

createdAttimestamp

When it was created.

updatedAttimestamp

When it was last changed.

criteriaobject or null

What it asks of a person, as the builder shows it. A person matches when every part holds; besides, the people added to it by ID are in it whatever it asks, and the people removed from it by ID are out of it. null when what was saved can no longer be read: open the audience in the app and save it again.

Child attributes
criteria.conditionsOnboolean

Whether its conditions choose people. true: everyone who matches the parts below is in it, beside the people added to it by ID. false: it holds only the people added to it by ID, and the parts below are kept as they were saved, choosing nobody.

criteria.stageobject or null

What they reached. null for any stage. Otherwise it holds mode (none, atLeast or exactly), stage (the colour, null when the mode is none) and window: null for any time, or direction (within or before) and days.

criteria.factsarray of objects

What else happened: one filter for each fact it asks about. Each holds kind (event or attribute), name, op (happened or notHappened for an event, is or isNot for an attribute), value (the value of an attribute filter) and withinDays (an event in the last so many days, null for any time).

criteria.tagsarray of objects

Which tags they hold: one filter for each group of tags. Each holds op (any, all or none) and tags, the tags by name.

criteria.listsarray of objects

Which of your Email Center lists they are on: one filter for each group of lists. Each holds op (any, all or none) and lists, each list by its id and name. A list brings a group of people into every audience that asks for it: put them on it, in the app or with Add to a list. A contact of your CRM alone is on no list.

criteria.includeCrmboolean

Whether it also takes the contacts of your CRM. They are read from your CRM when the audience is opened, downloaded or synced, and are never stored, so the counts here and the members do not include them.

criteria.cameFromobject or null

Filters by where a person came from, which the builder no longer offers. An audience saved with one still applies it until you remove it in the builder. null on every other audience.

peopleinteger or null

People in the audience, as the builder counts them: everyone in it, less the people ad-platform files leave out. Counted when you ask, for the people APAS® Cloud tracks. null, as every count but added and removed is, when criteria is null.

matchedinteger or null

Everyone in it, whether or not an ad-platform file would carry them: the people who match its criteria (while its conditions are on) and the people added to it by ID, less the people removed from it by ID. The members of the audience.

addedinteger

How many people were added to it by ID, in the app or by your system: each is in it whatever its conditions say. The exclusions still apply to them, as to everyone. 0 when nobody was.

removedinteger

How many people were removed from it by ID: each stays out even when they match, until they are added back. 0 when nobody was.

withEmailinteger or null

Of the people in the audience, how many have an email an ad-platform file can carry.

withPhoneinteger or null

Of the people in the audience, how many have a phone an ad-platform file can carry.

leftOutobject or null

Of the people who match, how many each reason leaves out of every ad-platform file and synced list. One person can have several reasons, so the counts can add up to more than the people left out. A synced list also leaves out anyone whose strictMode is true; a download keeps them.

Child attributes
leftOut.consentDeclinedinteger

People who declined consent, on any record of theirs.

leftOut.doNotSellinteger

People who asked you not to sell or share their data.

leftOut.globalPrivacyControlinteger

People a form, a quiz or a booking of whom was sent with Global Privacy Control on.

leftOut.deletionRequestedinteger

People who asked for their data to be deleted.

leftOut.marketingDeclinedinteger

People who declined marketing cookies on your consent banner, on any device of theirs.

leftOut.noConsentGiveninteger

On an account that asks for consent first, people no record of whom carries it. Always 0 otherwise.

leftOut.privacyRequestinteger

People a request in your Privacy Requests register names.

syncsarray of objects

Each ad platform list it is, or was, kept in sync with. Empty when it was never synced.

Child attributes
syncs[].platformstring

The ad platform: google-ads or bing-ads (Microsoft Ads).

syncs[].statusstring

Where the sync stands: active, stopping or stopped.

syncs[].enabledAttimestamp

When the sync was turned on.

syncs[].lastSyncedAttimestamp or null

When a sync last went through. null until the first one does.

syncs[].peopleinteger or null

How many people its last sync sent to the ad platform. null until the first one.

syncs[].errorstring or null

Why its last sync failed, in words. null when it went through.

syncs[].nextSyncAttimestamp or null

When it syncs next. null once it is stopped.

syncs[].stoppedAttimestamp or null

When it was stopped. null while it is active.

syncs[].stopReasonstring or null

Why it was stopped: user, archived, hipaa, strict_mode, module_off, inactive or disconnected. null while it is active.

Stage modes

none

Not converted yet: people no stage has been recorded for.

atLeast

Reached: people whose furthest stage is this one or a later one.

exactly

Stopped at: people whose furthest stage is this one, and no further.

Stage window directions

within

They last reached their furthest stage in the last so many days.

before

They last reached their furthest stage more than so many days ago: stalled leads, lapsed customers.

Fact conditions

happened

The event happened, in the last withinDays days when that is set.

notHappened

The event never happened.

is

The attribute's current value is this one. Capitals do not matter.

isNot

The attribute's current value is another one, or they have none.

Tag conditions

any

They hold at least one of the tags.

all

They hold every one of the tags.

none

They hold none of the tags.

List conditions

any

They are on at least one of the lists.

all

They are on every one of the lists.

none

They are on none of the lists.

Sync statuses

active

The list is kept in sync: updated every day, and at once when the audience changes or someone opts out.

stopping

The sync was turned off and its list is being emptied.

stopped

The sync is off. Its list was emptied and left in your ad account.

Stop reasons

user

Someone on your team turned it off.

archived

The audience was archived.

hipaa

HIPAA compliance was turned on for your account.

strict_mode

Strict Mode was turned on.

module_off

The Audiences module was switched off.

inactive

Your account became inactive.

disconnected

The connected ad account changed.

The audience object
{
  "id": "cmhk7r2ab0003l508p9q8r7s6",
  "name": "VIP leads with a quote",
  "description": "VIPs quoted in the last 30 days.",
  "createdAt": "2026-11-03T16:20:00Z",
  "updatedAt": "2026-11-05T09:12:44Z",
  "criteria": {
    "conditionsOn": true,
    "stage": {
      "mode": "atLeast",
      "stage": "yellow",
      "window": {
        "direction": "within",
        "days": 30
      }
    },
    "facts": [
      {
        "kind": "event",
        "name": "quote_sent",
        "op": "happened",
        "value": null,
        "withinDays": 30
      }
    ],
    "tags": [
      {
        "op": "any",
        "tags": [
          "VIP"
        ]
      }
    ],
    "lists": [],
    "includeCrm": false,
    "cameFrom": null
  },
  "people": 128,
  "matched": 134,
  "added": 2,
  "removed": 1,
  "withEmail": 121,
  "withPhone": 97,
  "leftOut": {
    "consentDeclined": 3,
    "doNotSell": 1,
    "globalPrivacyControl": 0,
    "deletionRequested": 0,
    "marketingDeclined": 2,
    "noConsentGiven": 0,
    "privacyRequest": 0
  },
  "syncs": [
    {
      "platform": "google-ads",
      "status": "active",
      "enabledAt": "2026-11-03T16:25:10Z",
      "lastSyncedAt": "2026-11-15T08:00:12Z",
      "people": 126,
      "error": null,
      "nextSyncAt": "2026-11-16T08:00:12Z",
      "stoppedAt": null,
      "stopReason": null
    }
  ]
}

List audiences

GET/api/v1/audiences

Returns your audiences, newest first. An archived audience is not listed.

Each audience is counted when you ask, one count for each. To list many of them faster, pick the fields you need: an audience is only counted when the answer carries people, matched, withEmail, withPhone or leftOut. added and removed are read from the audience's own people by ID, and cost no count.

Query parameters

limitintegerOptional

How many audiences a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

A list: items holds audience objects, total says how many audiences the list holds over every page (an archived one is not counted), and nextCursor is what to send as cursor for the next page, or null on the last one. An account with no audience answers an empty list and a 200.

Request
curl "https://api.apascloud.com/api/v1/audiences" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "items": [
    {
      "id": "cmhk7r2ab0003l508p9q8r7s6",
      "name": "VIP leads with a quote",
      "description": "VIPs quoted in the last 30 days.",
      "createdAt": "2026-11-03T16:20:00Z",
      "updatedAt": "2026-11-05T09:12:44Z",
      "criteria": {
        "conditionsOn": true,
        "stage": {
          "mode": "atLeast",
          "stage": "yellow",
          "window": {
            "direction": "within",
            "days": 30
          }
        },
        "facts": [
          {
            "kind": "event",
            "name": "quote_sent",
            "op": "happened",
            "value": null,
            "withinDays": 30
          }
        ],
        "tags": [
          {
            "op": "any",
            "tags": [
              "VIP"
            ]
          }
        ],
        "lists": [],
        "includeCrm": false,
        "cameFrom": null
      },
      "people": 128,
      "matched": 134,
      "added": 2,
      "removed": 1,
      "withEmail": 121,
      "withPhone": 97,
      "leftOut": {
        "consentDeclined": 3,
        "doNotSell": 1,
        "globalPrivacyControl": 0,
        "deletionRequested": 0,
        "marketingDeclined": 2,
        "noConsentGiven": 0,
        "privacyRequest": 0
      },
      "syncs": [
        {
          "platform": "google-ads",
          "status": "active",
          "enabledAt": "2026-11-03T16:25:10Z",
          "lastSyncedAt": "2026-11-15T08:00:12Z",
          "people": 126,
          "error": null,
          "nextSyncAt": "2026-11-16T08:00:12Z",
          "stoppedAt": null,
          "stopReason": null
        }
      ]
    }
  ],
  "nextCursor": null,
  "total": 1
}

Get an audience

GET/api/v1/audiences/<id>

Returns one audience of your account by its ID.

Path parameters

idstringRequired

The audience's ID, as a list gives it. It is also the last part of the audience's address in the app.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The audience object, or a 404 when no audience of your account has that ID. An archived audience answers a 404 too.

Request
curl "https://api.apascloud.com/api/v1/audiences/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cmhk7r2ab0003l508p9q8r7s6",
  "name": "VIP leads with a quote",
  "description": "VIPs quoted in the last 30 days.",
  "createdAt": "2026-11-03T16:20:00Z",
  "updatedAt": "2026-11-05T09:12:44Z",
  "criteria": {
    "conditionsOn": true,
    "stage": {
      "mode": "atLeast",
      "stage": "yellow",
      "window": {
        "direction": "within",
        "days": 30
      }
    },
    "facts": [
      {
        "kind": "event",
        "name": "quote_sent",
        "op": "happened",
        "value": null,
        "withinDays": 30
      }
    ],
    "tags": [
      {
        "op": "any",
        "tags": [
          "VIP"
        ]
      }
    ],
    "lists": [],
    "includeCrm": false,
    "cameFrom": null
  },
  "people": 128,
  "matched": 134,
  "added": 2,
  "removed": 1,
  "withEmail": 121,
  "withPhone": 97,
  "leftOut": {
    "consentDeclined": 3,
    "doNotSell": 1,
    "globalPrivacyControl": 0,
    "deletionRequested": 0,
    "marketingDeclined": 2,
    "noConsentGiven": 0,
    "privacyRequest": 0
  },
  "syncs": [
    {
      "platform": "google-ads",
      "status": "active",
      "enabledAt": "2026-11-03T16:25:10Z",
      "lastSyncedAt": "2026-11-15T08:00:12Z",
      "people": 126,
      "error": null,
      "nextSyncAt": "2026-11-16T08:00:12Z",
      "stoppedAt": null,
      "stopReason": null
    }
  ]
}

List an audience's members

GET/api/v1/audiences/<id>/members

Returns the people in an audience, newest first by when they were first captured.

Everyone in it is a member, whether or not an ad platform would be sent them: the people who match what it asks, while its conditions are on, and the people added to it by ID, less the people removed from it by ID. Each one says why ad-platform files and synced lists leave them out, in leftOut, and how they are in it, in addedBy. The people in the audience, as the builder counts them, are the members whose leftOut is empty.

Path parameters

idstringRequired

The audience's ID, as a list gives it.

Query parameters

limitintegerOptional

How many people a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with: a person's, leftOut, addedBy and addedAt. See Choosing fields.

Returns

A list: items holds person objects, each with three more attributes, leftOut, addedBy and addedAt. total says how many people are in it in all, which is the audience's matched, and nextCursor is what to send as cursor for the next page, or null on the last one. An audience nobody is in answers an empty list and a 200. No audience of your account with that ID, an archived one included, is a 404; one that can no longer be read as it was saved is a 400: open it in the app and save it again.

leftOutarray of strings

Why ad-platform files and synced lists leave this person out, each reason by its name. Empty when nothing does: they are one of the people in the audience. A synced list also leaves out anyone whose strictMode is true.

addedBystring

How they are in it: conditions (they match its conditions), teammate (someone on your team added them in the app) or webhook (your own system added them, through your audiences address). Someone added by ID who also matches is named by who added them.

addedAtstring or null

When they were added by ID. null when its conditions hold them.

How they are in it

conditions

They match its conditions.

teammate

Someone on your team added them in the app.

webhook

Your own system added them, through your audiences address with your webhook secret.

Reasons

consentDeclined

They declined consent, on any record of theirs.

doNotSell

They asked you not to sell or share their data.

globalPrivacyControl

A form, a quiz or a booking of theirs was sent with Global Privacy Control on.

deletionRequested

They asked for their data to be deleted.

marketingDeclined

They declined marketing cookies on your consent banner, on any device of theirs.

noConsentGiven

Your account asks for consent first (opt-in), and no record of theirs carries it.

privacyRequest

A request in your Privacy Requests register to erase their data, stop its sale, object to or restrict its use, or withdraw consent names them, unless it was refused.

Request
curl -G -d "limit=1" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/audiences/<id>/members"
Response · 200
{
  "items": [
    {
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "(201) 555-0123",
      "consent": true,
      "strictMode": false,
      "stage": "green",
      "stageAt": "2026-11-02T14:03:11Z",
      "firstCapturedAt": "2026-10-14T09:21:40Z",
      "lastCapturedAt": "2026-11-02T14:03:11Z",
      "tags": [
        "VIP"
      ],
      "facts": [
        {
          "kind": "attribute",
          "name": "tier",
          "value": "gold",
          "currency": null,
          "eventId": null,
          "properties": null,
          "occurredAt": "2026-11-03T15:00:00Z"
        },
        {
          "kind": "event",
          "name": "quote_sent",
          "value": "4200",
          "currency": "USD",
          "eventId": "Q-1042",
          "properties": {
            "plan": "annual"
          },
          "occurredAt": "2026-10-28T10:12:00Z"
        }
      ],
      "leadScore": 72,
      "apasids": [
        "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c"
      ],
      "apasclids": [
        "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f"
      ],
      "firstTouch": {
        "channel": "Organic Search",
        "platform": null,
        "referringDomain": "google.com",
        "at": "2026-10-02T16:45:00Z"
      },
      "lastTouch": {
        "channel": "Paid Search",
        "platform": "Google Ads",
        "referringDomain": "google.com",
        "at": "2026-10-14T09:20:05Z"
      },
      "initialAttribution": {
        "utm": {
          "source": "google",
          "medium": "cpc",
          "campaign": "brand",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/offer",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "latestAttribution": {
        "utm": {
          "source": "newsletter",
          "medium": "email",
          "campaign": "november",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/pricing",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "leftOut": [],
      "addedBy": "conditions",
      "addedAt": null
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMTAtMTRUMDk6MjE6NDAuMDAwWiIsImlkIjoiMGI2ZjRjMmEtOTFkMy00ZTU4LWE3YjItNmMxZDllM2Y1YTg0In0",
  "total": 134
}

The list object

One list of your account, as Email Center → Lists keeps it: whether people are put on it or it fills itself from its conditions, and how many people are on it now. A list holds the people on it, where an audience works out who it holds each time you ask. Your own systems put people on a static list, and take them off, with Add to a list.

Attributes

idstring

The list's ID.

namestring

Its name.

descriptionstring or null

What it is for, as your team wrote it.

kindstring

How people get on it: active, when its conditions decide who it holds, or static, when people are put on it and taken off.

conditionsobject or null

An active list's conditions, as the list shows them, in the form an audience's criteria take, without conditionsOn: a list's conditions are always on. includeCrm is always false: a list holds the people APAS® Cloud tracks; and lists is always empty: a list's conditions cannot ask which lists someone is on. null on a static list, and when what was saved can no longer be read: open the list in the app and save it again.

Child attributes
conditions.stageobject or null

What they reached. null for any stage. Otherwise it holds mode (none, atLeast or exactly), stage (the colour, null when the mode is none) and window: null for any time, or direction (within or before) and days.

conditions.factsarray of objects

What else happened: one filter for each fact it asks about. Each holds kind (event or attribute), name, op (happened or notHappened for an event, is or isNot for an attribute), value (the value of an attribute filter) and withinDays (an event in the last so many days, null for any time).

conditions.tagsarray of objects

Which tags they hold: one filter for each group of tags. Each holds op (any, all or none) and tags, the tags by name.

conditions.listsarray of objects

Which of your Email Center lists they are on: one filter for each group of lists. Each holds op (any, all or none) and lists, each list by its id and name. A list brings a group of people into every audience that asks for it: put them on it, in the app or with Add to a list. A contact of your CRM alone is on no list.

conditions.includeCrmboolean

Whether it also takes the contacts of your CRM. They are read from your CRM when the audience is opened, downloaded or synced, and are never stored, so the counts here and the members do not include them.

conditions.cameFromobject or null

Filters by where a person came from, which the builder no longer offers. An audience saved with one still applies it until you remove it in the builder. null on every other audience.

peopleinteger

How many people are on it now.

computedAttimestamp or null

When an active list last worked out who it holds. null on a static list, and before its first working-out.

createdAttimestamp

When it was created.

updatedAttimestamp

When it was last changed.

Kinds

active

It holds everyone its conditions match, kept up to date on its own as people come to match them and stop.

static

It holds the people put on it, until they are taken off.

The list object
{
  "id": "cm4r7t2kq0001x9l3v8b6n5wz",
  "name": "Newsletter",
  "description": "Everyone who asked for the monthly newsletter.",
  "kind": "static",
  "conditions": null,
  "people": 248,
  "computedAt": null,
  "createdAt": "2026-10-02T15:30:00Z",
  "updatedAt": "2026-11-12T08:41:05Z"
}

List lists

GET/api/v1/lists

Returns your lists, newest first. An archived list is not listed. Each list's id is what Add to a list names it by.

Query parameters

limitintegerOptional

How many lists a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

A list: items holds list objects, total says how many lists there are over every page (an archived one is not counted), and nextCursor is what to send as cursor for the next page, or null on the last one. An account with no list answers an empty list and a 200.

Request
curl "https://api.apascloud.com/api/v1/lists" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "items": [
    {
      "id": "cm4r7t2kq0001x9l3v8b6n5wz",
      "name": "Newsletter",
      "description": "Everyone who asked for the monthly newsletter.",
      "kind": "static",
      "conditions": null,
      "people": 248,
      "computedAt": null,
      "createdAt": "2026-10-02T15:30:00Z",
      "updatedAt": "2026-11-12T08:41:05Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

Get a list

GET/api/v1/lists/<id>

Returns one list of your account by its ID.

Path parameters

idstringRequired

The list's ID, as List lists gives it.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The list object, or a 404 when no list of your account has that ID. An archived list answers a 404 too.

Request
curl "https://api.apascloud.com/api/v1/lists/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cm4r7t2kq0001x9l3v8b6n5wz",
  "name": "Newsletter",
  "description": "Everyone who asked for the monthly newsletter.",
  "kind": "static",
  "conditions": null,
  "people": 248,
  "computedAt": null,
  "createdAt": "2026-10-02T15:30:00Z",
  "updatedAt": "2026-11-12T08:41:05Z"
}

List a list's members

GET/api/v1/lists/<id>/members

Returns the people on a list, newest first by when they were put on it.

Path parameters

idstringRequired

The list's ID, as List lists gives it.

Query parameters

limitintegerOptional

How many people a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with: a person's, and addedAt and addedBy. See Choosing fields.

Returns

A list: items holds person objects, each with two more attributes, addedAt and addedBy. total says how many people are on it in all, which is the list's people, and nextCursor is what to send as cursor for the next page, or null on the last one. A list nobody is on answers an empty list and a 200. No list of your account with that ID, an archived one included, is a 404.

addedAttimestamp

When they were put on the list.

addedBystring

What put them on it: conditions (an active list's), teammate, automation, flow, import or webhook (your own system, through your lists address).

Added by

conditions

An active list's conditions match them.

teammate

Someone on your team added them in the app.

automation

An email automation added them, with its Add to list step.

flow

APAS® Flows added them, with its Add to Email List step.

import

An import of people into the list added them.

webhook

Your own system added them, through your lists address with your webhook secret.

Request
curl -G -d "limit=1" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/lists/<id>/members"
Response · 200
{
  "items": [
    {
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "(201) 555-0123",
      "consent": true,
      "strictMode": false,
      "stage": "green",
      "stageAt": "2026-11-02T14:03:11Z",
      "firstCapturedAt": "2026-10-14T09:21:40Z",
      "lastCapturedAt": "2026-11-02T14:03:11Z",
      "tags": [
        "VIP"
      ],
      "facts": [
        {
          "kind": "attribute",
          "name": "tier",
          "value": "gold",
          "currency": null,
          "eventId": null,
          "properties": null,
          "occurredAt": "2026-11-03T15:00:00Z"
        },
        {
          "kind": "event",
          "name": "quote_sent",
          "value": "4200",
          "currency": "USD",
          "eventId": "Q-1042",
          "properties": {
            "plan": "annual"
          },
          "occurredAt": "2026-10-28T10:12:00Z"
        }
      ],
      "leadScore": 72,
      "apasids": [
        "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c"
      ],
      "apasclids": [
        "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f"
      ],
      "firstTouch": {
        "channel": "Organic Search",
        "platform": null,
        "referringDomain": "google.com",
        "at": "2026-10-02T16:45:00Z"
      },
      "lastTouch": {
        "channel": "Paid Search",
        "platform": "Google Ads",
        "referringDomain": "google.com",
        "at": "2026-10-14T09:20:05Z"
      },
      "initialAttribution": {
        "utm": {
          "source": "google",
          "medium": "cpc",
          "campaign": "brand",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/offer",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "latestAttribution": {
        "utm": {
          "source": "newsletter",
          "medium": "email",
          "campaign": "november",
          "term": null,
          "content": null
        },
        "clickIds": {
          "gclid": "EAIaIQobChMI-example",
          "gbraid": null,
          "wbraid": null,
          "msclkid": null,
          "fbclid": null,
          "ttclid": null,
          "li_fat_id": null,
          "twclid": null,
          "rdt_cid": null
        },
        "referrer": "https://www.google.com/",
        "landingPage": "https://www.example.com/pricing",
        "clickAt": "2026-10-14T09:20:00Z"
      },
      "addedAt": "2026-11-16T09:30:00Z",
      "addedBy": "webhook"
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMTEtMTZUMDk6MzA6MDAuMDAwWiIsImlkIjoiMGI2ZjRjMmEtOTFkMy00ZTU4LWE3YjItNmMxZDllM2Y1YTg0In0",
  "total": 248
}

The click object

One ad click on your account, as APAS® Cloud caught it: when, where it came from and went, what the ad platform and your tracking template put on it, and the person it became. A click is an ad click by the one rule your reports count ad clicks by. It never carries an IP address.

Each click read reads your warehouse, so a key makes at most 20 of them a minute, beside the limits every call has. Your account's reads of its warehouse (the clicks, a person's credit, the events) share 100 GB a day; past it they answer 429 until midnight UTC.

Attributes

apasclidstring or null

The APAS® Click ID: the one Get a click takes, and the one a record captured from this click carries. null on a direct click.

clickedAttimestamp

When the click happened: the click itself for one through an Edge URL, or when its first page loaded for a direct one.

kindstring

How it reached your site: edge, through one of your Edge URLs, or direct, straight from an ad.

platformstring

The ad platform it came from, by the one rule your reports name it by: Google Ads, for one, or Unknown platform when the ad named none.

linkstring or null

The Edge URL it went through, without what its address carried. null on a direct click.

landingPagestring or null

The page it landed on, without what its address carried. null when it never reached a page.

utmobject

The UTM tags it carried: source, medium, campaign, term and content. With your tracking template, term is the keyword and content the ad.

templateobject

What your tracking template filled in, each null when the ad platform left it out.

Child attributes
template.campaignIdstring or null

The campaign's ID. The template's apas_cid.

template.adGroupIdstring or null

The ad group's ID. The template's apas_agid.

template.adIdstring or null

The ad's ID. The template's apas_aid.

template.networkstring or null

Where the ad showed: the search network, the display network or a partner, as the platform marks it. The template's apas_nid.

template.matchTypestring or null

How the search matched the keyword: exact, phrase or broad, as the platform marks it. The template's apas_mt.

template.devicestring or null

The device the ad showed on, as the platform marks it. The template's apas_dev.

template.locationstring or null

The ID of the place the person was in, by the platform's own list of locations. The template's apas_loc.

template.targetIdstring or null

The ID of the keyword, audience or other target the ad matched. The template's apas_tid.

template.syntheticKeywordstring or null

The keyword the platform matched for an ad with no keyword of yours, such as a dynamic search ad. The template's apas_skw.

template.placementstring or null

The site, app or video the ad showed on, for an ad outside search. The template's apas_plc.

clickIdsobject

The ad click IDs it carried, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

countrystring or null

The country it came from, as a two-letter code.

citystring or null

The city it came from.

deviceobject

The device it landed on: its type (desktop, mobile or tablet), its operating system and its browser, each null when it never reached a page.

Child attributes
device.typestring or null

desktop, mobile or tablet.

device.osstring or null

Its operating system: iOS, Android, Windows, macOS and so on.

device.browserstring or null

Its browser: Safari, Chrome and so on.

botScoreinteger or null

Its APAS® Bot Score, from 1 (a bot) to 99 (likely human), as Cloudflare read it. null when it was not read.

botVerdictstring or null

What that score says, as your reports name it: likely human, likely bot, bot or verified bot.

apaspidstring or null

The APAS® Person ID of the person it became. null when nobody it landed on is a person in your account yet.

Kinds

edge

Through one of your Edge URLs. Its moment is the click itself, and link is the Edge URL. Its APAS® Click ID finds it with Get a click.

direct

Straight to your site from an ad, with your tracking template or an ad platform click ID. Its moment is when its first page loaded, and it has no APAS® Click ID.

The click object
{
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "clickedAt": "2026-10-14T09:20:00Z",
  "kind": "edge",
  "platform": "Google Ads",
  "link": "https://go.example.com/brand",
  "landingPage": "https://www.example.com/offer",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "brand",
    "term": null,
    "content": null
  },
  "template": {
    "campaignId": "21458963257",
    "adGroupId": "163258741236",
    "adId": "658124590123",
    "network": "g",
    "matchType": "e",
    "device": "m",
    "location": "1023191",
    "targetId": "kwd-29384756102",
    "syntheticKeyword": null,
    "placement": null
  },
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": null,
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "country": "US",
  "city": "Jersey City",
  "device": {
    "type": "mobile",
    "os": "iOS",
    "browser": "Safari"
  },
  "botScore": 91,
  "botVerdict": "likely human",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

Get a click

GET/api/v1/clicks/<apasclid>

Returns one ad click by its APAS® Click ID: the one a record captured from it carries, and every person lists as their apasclids. An Edge URL click's own record is kept 90 days; after that it is still found by the page it landed on, without its Edge URL.

Path parameters

apasclidstringRequired

The APAS® Click ID.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The click object, or a 404 when no click of your account has that APAS® Click ID. A 429 past the 20 a minute the click reads allow.

Request
curl "https://api.apascloud.com/api/v1/clicks/<apasclid>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "clickedAt": "2026-10-14T09:20:00Z",
  "kind": "edge",
  "platform": "Google Ads",
  "link": "https://go.example.com/brand",
  "landingPage": "https://www.example.com/offer",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "brand",
    "term": null,
    "content": null
  },
  "template": {
    "campaignId": "21458963257",
    "adGroupId": "163258741236",
    "adId": "658124590123",
    "network": "g",
    "matchType": "e",
    "device": "m",
    "location": "1023191",
    "targetId": "kwd-29384756102",
    "syntheticKeyword": null,
    "placement": null
  },
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": null,
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "country": "US",
  "city": "Jersey City",
  "device": {
    "type": "mobile",
    "os": "iOS",
    "browser": "Safari"
  },
  "botScore": 91,
  "botVerdict": "likely human",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
}

List a person's clicks

GET/api/v1/persons/<apaspid>/clicks

Returns every ad click of one person, newest first, on every device of theirs, over the last 400 days: each click through one of your Edge URLs, and each straight to your site from an ad.

Path parameters

apaspidstringRequired

Their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs in its place, as Get a person takes it.

Query parameters

limitintegerOptional

How many clicks a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, a click's. See Choosing fields.

Returns

A list: items holds click objects, total says how many clicks of theirs there are over every page, and nextCursor is what to send as cursor for the next page, or null on the last one. Someone with no ad click answers an empty list and a 200. No person of your account with that ID is a 404; past the click reads' limit, a 429.

Request
curl -G -d "limit=1" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/persons/<apaspid>/clicks"
Response · 200
{
  "items": [
    {
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "clickedAt": "2026-10-14T09:20:00Z",
      "kind": "edge",
      "platform": "Google Ads",
      "link": "https://go.example.com/brand",
      "landingPage": "https://www.example.com/offer",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand",
        "term": null,
        "content": null
      },
      "template": {
        "campaignId": "21458963257",
        "adGroupId": "163258741236",
        "adId": "658124590123",
        "network": "g",
        "matchType": "e",
        "device": "m",
        "location": "1023191",
        "targetId": "kwd-29384756102",
        "syntheticKeyword": null,
        "placement": null
      },
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "country": "US",
      "city": "Jersey City",
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "botScore": 91,
      "botVerdict": "likely human",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMTAtMTRUMDk6MjA6MDAuMDAwWiIsImlkIjoiczQ4MjFhIn0",
  "total": 2
}

The credit object

Who gets the credit for one person's lead, both ways your reports count it. The advertising side counts the lead for every ad platform one of their ad clicks came from in the 90 days before it, as MER and Paid Traffic do, so a lead two platforms touched counts for both. The channel side credits it once per model, to the visit First touch or Last touch names, as Source / Medium and Organic Traffic do. The two sides answer two questions, and are never added together.

Attributes

apaspidstring

The APAS® Person ID of the person.

basisstring or null

What their credit is counted at: red, their first red, or capture, their first capture while they have no red yet.

creditedAttimestamp or null

That moment.

platformsarray of strings

The ad platforms the advertising side credits them to, A to Z: each one an ad click of theirs in ads came from. A lead two platforms touched counts for both.

adsarray of objects

The advertising side: every ad click of theirs in the 90 days before creditedAt, on any device of theirs, newest first, each as Get a click answers it. At most 100.

firstTouchobject or null

The channel side: the visit First touch credits them to, their earliest visit on record at or before creditedAt.

Child attributes
firstTouch.channelstring or null

The visit's channel, as Web Analytics names it: Paid Search, Organic Search, Direct and so on.

firstTouch.platformstring or null

The ad platform, when an ad brought the visit: Google Ads, for one, or Unknown platform when the ad named none.

firstTouch.referringDomainstring or null

The site the visit came from.

firstTouch.attimestamp or null

When the visit began.

firstTouch.landingPagestring or null

The page it landed on, without what its address carried. null when its page was not read.

firstTouch.utmobject

The UTM tags it carried: source, medium, campaign, term and content. Holds source, medium, campaign, term and content, each a string or null.

firstTouch.clickIdsobject

The ad click IDs it carried, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

firstTouch.templateobject

What your tracking template filled in, each null when the ad platform left it out.

lastTouchobject or null

The visit Last touch credits them to: their latest visit in the 90 days before creditedAt, a direct one only when none of those had a source.

Child attributes
lastTouch.channelstring or null

The visit's channel, as Web Analytics names it: Paid Search, Organic Search, Direct and so on.

lastTouch.platformstring or null

The ad platform, when an ad brought the visit: Google Ads, for one, or Unknown platform when the ad named none.

lastTouch.referringDomainstring or null

The site the visit came from.

lastTouch.attimestamp or null

When the visit began.

lastTouch.landingPagestring or null

The page it landed on, without what its address carried. null when its page was not read.

lastTouch.utmobject

The UTM tags it carried: source, medium, campaign, term and content. Holds source, medium, campaign, term and content, each a string or null.

lastTouch.clickIdsobject

The ad click IDs it carried, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

lastTouch.templateobject

What your tracking template filled in, each null when the ad platform left it out.

Bases

red

Their first red, on any device of theirs: every later stage of theirs carries its credit.

capture

Their first capture, while they have no red yet; once they have one, their red.

The credit object
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "basis": "red",
  "creditedAt": "2026-10-14T09:21:40Z",
  "platforms": [
    "Google Ads"
  ],
  "ads": [
    {
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "clickedAt": "2026-10-14T09:20:00Z",
      "kind": "edge",
      "platform": "Google Ads",
      "link": "https://go.example.com/brand",
      "landingPage": "https://www.example.com/offer",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand",
        "term": null,
        "content": null
      },
      "template": {
        "campaignId": "21458963257",
        "adGroupId": "163258741236",
        "adId": "658124590123",
        "network": "g",
        "matchType": "e",
        "device": "m",
        "location": "1023191",
        "targetId": "kwd-29384756102",
        "syntheticKeyword": null,
        "placement": null
      },
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "country": "US",
      "city": "Jersey City",
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "botScore": 91,
      "botVerdict": "likely human",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    }
  ],
  "firstTouch": {
    "channel": "Organic Search",
    "platform": null,
    "referringDomain": "google.com",
    "at": "2026-10-02T16:45:00Z",
    "landingPage": "https://www.example.com/",
    "utm": {
      "source": null,
      "medium": null,
      "campaign": null,
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": null,
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "template": {
      "campaignId": null,
      "adGroupId": null,
      "adId": null,
      "network": null,
      "matchType": null,
      "device": null,
      "location": null,
      "targetId": null,
      "syntheticKeyword": null,
      "placement": null
    }
  },
  "lastTouch": {
    "channel": "Paid Search",
    "platform": "Google Ads",
    "referringDomain": "google.com",
    "at": "2026-10-14T09:20:05Z",
    "landingPage": "https://www.example.com/offer",
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "brand",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "template": {
      "campaignId": "21458963257",
      "adGroupId": "163258741236",
      "adId": "658124590123",
      "network": "g",
      "matchType": "e",
      "device": "m",
      "location": "1023191",
      "targetId": "kwd-29384756102",
      "syntheticKeyword": null,
      "placement": null
    }
  }
}

Get a person's credit

GET/api/v1/persons/<apaspid>/credit

Returns who gets the credit for one person's lead: the moment it is credited at, every ad click of theirs before it with the platforms they came from, each click as Get a click answers it, and their First touch and Last touch, each with the page it landed on and what its address carried. It reads your warehouse, so it counts toward the 20 a minute the click reads allow.

Path parameters

apaspidstringRequired

Their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs in its place, as Get a person takes it.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The credit object, or a 404 when no person of your account has that ID. For a few minutes after someone is first captured, until their visits are read, basis, creditedAt and both touches are null and there are no ads. Past the click reads' limit, a 429.

Request
curl "https://api.apascloud.com/api/v1/persons/<apaspid>/credit" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "basis": "red",
  "creditedAt": "2026-10-14T09:21:40Z",
  "platforms": [
    "Google Ads"
  ],
  "ads": [
    {
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "clickedAt": "2026-10-14T09:20:00Z",
      "kind": "edge",
      "platform": "Google Ads",
      "link": "https://go.example.com/brand",
      "landingPage": "https://www.example.com/offer",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand",
        "term": null,
        "content": null
      },
      "template": {
        "campaignId": "21458963257",
        "adGroupId": "163258741236",
        "adId": "658124590123",
        "network": "g",
        "matchType": "e",
        "device": "m",
        "location": "1023191",
        "targetId": "kwd-29384756102",
        "syntheticKeyword": null,
        "placement": null
      },
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "country": "US",
      "city": "Jersey City",
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "botScore": 91,
      "botVerdict": "likely human",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84"
    }
  ],
  "firstTouch": {
    "channel": "Organic Search",
    "platform": null,
    "referringDomain": "google.com",
    "at": "2026-10-02T16:45:00Z",
    "landingPage": "https://www.example.com/",
    "utm": {
      "source": null,
      "medium": null,
      "campaign": null,
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": null,
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "template": {
      "campaignId": null,
      "adGroupId": null,
      "adId": null,
      "network": null,
      "matchType": null,
      "device": null,
      "location": null,
      "targetId": null,
      "syntheticKeyword": null,
      "placement": null
    }
  },
  "lastTouch": {
    "channel": "Paid Search",
    "platform": "Google Ads",
    "referringDomain": "google.com",
    "at": "2026-10-14T09:20:05Z",
    "landingPage": "https://www.example.com/offer",
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "brand",
      "term": null,
      "content": null
    },
    "clickIds": {
      "gclid": "EAIaIQobChMI-example",
      "gbraid": null,
      "wbraid": null,
      "msclkid": null,
      "fbclid": null,
      "ttclid": null,
      "li_fat_id": null,
      "twclid": null,
      "rdt_cid": null
    },
    "template": {
      "campaignId": "21458963257",
      "adGroupId": "163258741236",
      "adId": "658124590123",
      "network": "g",
      "matchType": "e",
      "device": "m",
      "location": "1023191",
      "targetId": "kwd-29384756102",
      "syntheticKeyword": null,
      "placement": null
    }
  }
}

The event object

One analytics event on your account: something a visitor did on your website, a stage or a call APAS® Cloud recorded, or an event your own systems sent with Send an event. Each carries the page it happened on, its APAS® IDs, what attributes it and its bot verdict. Bots are marked, never left out: leave them out by their botVerdict. It never carries an IP address.

Each events read reads your warehouse, so it counts toward the 20 a minute the click reads allow, beside the limits every call has, and toward the 100 GB a day your account's reads of its warehouse share. A read's later pages are served from the result of the query behind its first page, so paging through a read does not read your warehouse again for every page.

Attributes

idstring

The ID it is kept under: the eventId your system sent with it, or the one APAS® Cloud gave it.

namestring

Its name: pageview, click_to_call, a conversion stage such as red, or a name your pages or your systems gave it.

occurredAttimestamp

When it happened.

originstring

Where it came from: web, server, api or backfill, listed below.

apaspidstring or null

The APAS® Person ID of the person it belongs to: the one your system sent it for, or whoever its device belongs to. null when its device is no person of your account yet.

apasidstring or null

The APAS® ID of the device it happened on. null for an event your system sent with no device.

apasclidstring or null

The APAS® Click ID it carried: on your website, the device's latest click through one of your Edge URLs, which is what attributes it; from your system, the one sent with it. null when it had none.

sessionIdstring or null

The visit it happened in, on your website. null when it was part of no visit.

pageobject

The page it happened on: its address as it was, and its title, each null when it happened on no page.

Child attributes
page.urlstring or null

Its address as it was, with what it carried, after APAS® Cloud took any contact details out of it.

page.titlestring or null

Its title.

referrerstring or null

The address the visitor came from, when their browser told it.

utmobject

The UTM tags in the page's address: source, medium, campaign, term and content.

clickIdsobject

The ad click IDs it carried, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

propertiesobject

What was recorded with it, as it was kept: what your pages, Tag Manager or your system sent. Empty when it carried none.

valuenumber or null

The value it was sent with. null when it had none.

currencystring or null

The currency of that value, as a three-letter code.

deviceobject

The device it happened on: its type (desktop, mobile or tablet), its operating system and its browser, each null when it happened on no device.

Child attributes
device.typestring or null

desktop, mobile or tablet.

device.osstring or null

Its operating system: iOS, Android, Windows, macOS and so on.

device.browserstring or null

Its browser: Safari, Chrome and so on.

countrystring or null

The country it came from, as a two-letter code.

regionstring or null

The region it came from, such as a state.

citystring or null

The city it came from.

botScoreinteger or null

Its APAS® Bot Score, from 1 (a bot) to 99 (likely human), as Cloudflare read it. null when it was not read.

botVerdictstring or null

What that score says, as your reports name it: likely human, likely bot, bot or verified bot.

Origins

web

Your website, through the APAS® Analytics script: a page view, a tap on a phone number, or an event your pages or Tag Manager record.

server

APAS® Cloud itself: a conversion stage someone reached, or an answered call.

api

Your own systems, sent with Send an event.

backfill

History from the analytics you used before APAS® Analytics, brought over when you moved.

The event object
{
  "id": "7c1e4b2a-9d3f-4a6b-8e5c-2f1d0a9b8c7e",
  "name": "click_to_call",
  "occurredAt": "2026-10-14T09:21:12Z",
  "origin": "web",
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "sessionId": "a4e9c2d1-6b7f-4c3e-9a8d-5f2e1b0c7d6a",
  "page": {
    "url": "https://www.example.com/offer?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=EAIaIQobChMI-example&apasclid=1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
    "title": "Same-day appointments"
  },
  "referrer": "https://www.google.com/",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "brand",
    "term": null,
    "content": null
  },
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": null,
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "properties": {},
  "value": null,
  "currency": null,
  "device": {
    "type": "mobile",
    "os": "iOS",
    "browser": "Safari"
  },
  "country": "US",
  "region": "New Jersey",
  "city": "Jersey City",
  "botScore": 91,
  "botVerdict": "likely human"
}

List events

GET/api/v1/events

Returns your account's events of one name or several within a period, newest first: every tap on a phone number in a week, say, or every event of one name your systems sent. A period is at most 31 days; read a longer one a period at a time.

Query parameters

namestringRequired

The event name to list, or several separated by commas: at most 10.

fromstringOptional

The start of the period, in ISO 8601. Left out, it is 7 days before the end.

tostringOptional

The end of the period, in ISO 8601. Left out, it is now. A period is at most 31 days.

limitintegerOptional

How many events a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, an event's. See Choosing fields.

Returns

A list: items holds event objects, total says how many events the period holds over every page, and nextCursor is what to send as cursor for the next page, or null on the last one. No name, or a period longer than 31 days, is a 400; past the click reads' limit, a 429.

Request
curl -G \
  -d "name=click_to_call" \
  -d "from=2026-10-13T00:00:00Z" \
  -d "to=2026-10-20T00:00:00Z" \
  -d "limit=1" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/events"
Response · 200
{
  "items": [
    {
      "id": "7c1e4b2a-9d3f-4a6b-8e5c-2f1d0a9b8c7e",
      "name": "click_to_call",
      "occurredAt": "2026-10-14T09:21:12Z",
      "origin": "web",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "sessionId": "a4e9c2d1-6b7f-4c3e-9a8d-5f2e1b0c7d6a",
      "page": {
        "url": "https://www.example.com/offer?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=EAIaIQobChMI-example&apasclid=1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
        "title": "Same-day appointments"
      },
      "referrer": "https://www.google.com/",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand",
        "term": null,
        "content": null
      },
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "properties": {},
      "value": null,
      "currency": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "country": "US",
      "region": "New Jersey",
      "city": "Jersey City",
      "botScore": 91,
      "botVerdict": "likely human"
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMTAtMTRUMDk6MjE6MTIuMDAwWiIsImlkIjoiN2MxZTRiMmEtOWQzZi00YTZiLThlNWMtMmYxZDBhOWI4YzdlIn0",
  "total": 37
}

List a person's events

GET/api/v1/persons/<apaspid>/events

Returns every event of one person, newest first, over the last 400 days: what each device of theirs did on your website, what APAS® Cloud recorded for them and what your systems sent for them.

Path parameters

apaspidstringRequired

Their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs in its place, as Get a person takes it.

Query parameters

namestringOptional

Only the events of this name, or of several separated by commas: at most 10. Left out, every event of theirs.

limitintegerOptional

How many events a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, an event's. See Choosing fields.

Returns

A list: items holds event objects, total says how many events of theirs there are over every page, and nextCursor is what to send as cursor for the next page, or null on the last one. Someone with no event answers an empty list and a 200. No person of your account with that ID is a 404; past the click reads' limit, a 429.

Request
curl -G -d "name=video_watched,click_to_call" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/persons/<apaspid>/events"
Response · 200
{
  "items": [
    {
      "id": "vw-8812",
      "name": "video_watched",
      "occurredAt": "2026-11-02T14:10:00Z",
      "origin": "api",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "apasid": null,
      "apasclid": null,
      "sessionId": null,
      "page": {
        "url": null,
        "title": null
      },
      "referrer": null,
      "utm": {
        "source": null,
        "medium": null,
        "campaign": null,
        "term": null,
        "content": null
      },
      "clickIds": {
        "gclid": null,
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "properties": {
        "plan": "pro",
        "video": "onboarding-2"
      },
      "value": 49,
      "currency": "USD",
      "device": {
        "type": null,
        "os": null,
        "browser": null
      },
      "country": null,
      "region": null,
      "city": null,
      "botScore": null,
      "botVerdict": null
    },
    {
      "id": "7c1e4b2a-9d3f-4a6b-8e5c-2f1d0a9b8c7e",
      "name": "click_to_call",
      "occurredAt": "2026-10-14T09:21:12Z",
      "origin": "web",
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
      "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
      "sessionId": "a4e9c2d1-6b7f-4c3e-9a8d-5f2e1b0c7d6a",
      "page": {
        "url": "https://www.example.com/offer?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=EAIaIQobChMI-example&apasclid=1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
        "title": "Same-day appointments"
      },
      "referrer": "https://www.google.com/",
      "utm": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand",
        "term": null,
        "content": null
      },
      "clickIds": {
        "gclid": "EAIaIQobChMI-example",
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "properties": {},
      "value": null,
      "currency": null,
      "device": {
        "type": "mobile",
        "os": "iOS",
        "browser": "Safari"
      },
      "country": "US",
      "region": "New Jersey",
      "city": "Jersey City",
      "botScore": 91,
      "botVerdict": "likely human"
    }
  ],
  "nextCursor": null,
  "total": 2
}

The Call Center object

Your Call Center's settings: the number your calls ring, how long a visitor keeps the tracking number they were shown, who on your site is shown one, and how calls are handled. An account that never set up the Call Center reads with the settings it would start on.

The Call Center reads come from your account, not your warehouse, so they count only toward the limits every call has.

Attributes

businessNumberstring or null

The number your calls ring, in E.164 (+12015550100). null until you set one.

attributionWindowMinutesinteger

How long a visitor keeps the tracking number they were shown, so a call within it is theirs: 30, 60 or 90.

showNumbersTostring

Who on your site is shown a tracking number: ads, ads_and_search or everyone, listed below.

poolSizeinteger

How many numbers your website pool is set to hold.

recommendedPoolSizeinteger or null

How many APAS® Cloud recommends from your own traffic, worked out daily. null until it is.

callerIdShownstring

What the phone that rings shows as the caller: tracking or caller, listed below.

shortestConversionSecondsinteger

The shortest call sent to your ad platforms as a conversion. Every call counts in your reports whatever its length; 0 sends every call.

recordCallsboolean

Whether calls are recorded.

callerNameLookupboolean

Whether each caller's listed name is looked up.

Who sees a tracking number

ads

Visitors who came from one of your ads.

ads_and_search

Those, and visitors who came from search: a search engine, a map or Business Profile link, or an AI assistant.

everyone

Every visitor.

Caller ID shown

tracking

The tracking number the caller dialled, so you know a call came through APAS® Cloud.

caller

The caller's own number. A withheld or invalid one still shows the tracking number.

The Call Center object
{
  "businessNumber": "+12015550100",
  "attributionWindowMinutes": 60,
  "showNumbersTo": "ads",
  "poolSize": 10,
  "recommendedPoolSize": 8,
  "callerIdShown": "tracking",
  "shortestConversionSeconds": 30,
  "recordCalls": false,
  "callerNameLookup": true
}

Get the Call Center

GET/api/v1/call-center

Returns your Call Center's settings. It takes no parameters.

Returns

The Call Center object.

Request
curl "https://api.apascloud.com/api/v1/call-center" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "businessNumber": "+12015550100",
  "attributionWindowMinutes": 60,
  "showNumbersTo": "ads",
  "poolSize": 10,
  "recommendedPoolSize": 8,
  "callerIdShown": "tracking",
  "shortestConversionSeconds": 30,
  "recordCalls": false,
  "callerNameLookup": true
}

The tracking number object

One number on your Twilio account: what it is used for, where it stands, the number its calls ring and, for a dedicated number, the source it is kept for.

Attributes

idstring

Its ID.

numberstring

The number, in E.164 (+12015550142).

namestring or null

The name it has on your Twilio account. null when it has none.

usestring

What it is used for: pool or dedicated, listed below.

statusstring

Where it stands: tracking, paused, untracked, releasing or released, listed below.

forwardsTostring or null

The number its calls ring: its own forwarding number, or your business number. null for a number APAS® Cloud does not answer.

sourceobject

For a dedicated number, the source it is kept for. Each null for a pool number.

Child attributes
source.labelstring or null

What you call the source, such as Van #3 signage.

source.categorystring or null

Its kind: billboard, vehicle, signage, print, social, listing, direct_mail, radio, tv, email, event, partner or other.

source.campaignstring or null

The campaign you grouped it under.

callsinteger

How many calls it has had.

lastCallAttimestamp or null

When its latest call came in. null before its first.

createdAttimestamp

When it was added to APAS® Cloud.

Uses

pool

In your website pool: shown to one visitor at a time, so a call through it is tied to the visit that saw it.

dedicated

Kept for one source of your own, such as a billboard, a van or a listing, so every call through it is that source.

Statuses

tracking

In use: APAS® Cloud answers its calls and, for a pool number, shows it on your site.

paused

Still answers and forwards its calls, but is shown to no new visitor: a number of an earlier Twilio account, or one whose Stop tracking Twilio has not finished.

untracked

On your Twilio account, but not used by APAS® Cloud: its calls go where Twilio sends them.

releasing

Being given back to Twilio. It answers until Twilio lets it go.

released

Given back to Twilio. Its calls stay in your call log.

The tracking number object
{
  "id": "cmhp2r7tn0002l708f4e5d6c7",
  "number": "+12015550142",
  "name": "Website pool 1",
  "use": "pool",
  "status": "tracking",
  "forwardsTo": "+12015550100",
  "source": {
    "label": null,
    "category": null,
    "campaign": null
  },
  "calls": 214,
  "lastCallAt": "2026-11-12T15:41:08Z",
  "createdAt": "2026-06-03T16:20:00Z"
}

List tracking numbers

GET/api/v1/tracking-numbers

Returns every number on your Twilio account, newest first: the ones APAS® Cloud tracks and the ones it does not.

Query parameters

statusstringOptional

Only the numbers of one status, listed under the tracking number object.

usestringOptional

Only the pool numbers, or only the dedicated ones.

limitintegerOptional

How many numbers a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, a number's. See Choosing fields.

Returns

A list: items holds tracking number objects, total says how many numbers there are over every page, and nextCursor is what to send as cursor for the next page, or null on the last one.

Request
curl "https://api.apascloud.com/api/v1/tracking-numbers" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "items": [
    {
      "id": "cmhp2r7tn0002l708f4e5d6c7",
      "number": "+12015550142",
      "name": "Website pool 1",
      "use": "pool",
      "status": "tracking",
      "forwardsTo": "+12015550100",
      "source": {
        "label": null,
        "category": null,
        "campaign": null
      },
      "calls": 214,
      "lastCallAt": "2026-11-12T15:41:08Z",
      "createdAt": "2026-06-03T16:20:00Z"
    },
    {
      "id": "cmhp2s1vb0005l708g8h9i0j1",
      "number": "+12015550187",
      "name": "Van 3",
      "use": "dedicated",
      "status": "tracking",
      "forwardsTo": "+12015550100",
      "source": {
        "label": "Van #3 signage",
        "category": "vehicle",
        "campaign": "Spring 2026"
      },
      "calls": 31,
      "lastCallAt": "2026-11-10T08:15:02Z",
      "createdAt": "2026-03-12T10:00:00Z"
    }
  ],
  "nextCursor": null,
  "total": 2
}

The call object

One call on your account, answered or missed: when, who called and the number they dialled, how it ended, and what made the phone ring: the visit behind it, with its UTMs and click IDs, and the person it belongs to. Whether a call was recorded or has a transcript is a yes or no: the recording and the transcript stay in your account.

Attributes

idstring

Its ID: the one Get a call takes.

startedAttimestamp

When the call came in.

endedAttimestamp or null

When it ended. null while it is live.

durationSecondsinteger

How long it lasted, in seconds.

directionstring

inbound, a call to one of your numbers, or outbound.

outcomestring

How it ended: answered, missed, rejected or live, as Call Center counts calls, listed below.

statusstring

Its exact status, one of those an outcome takes in.

callerobject

Who called: their number as it arrived and what the phone network gave with it, each null when it gave none.

Child attributes
caller.numberstring or null

Their number, in E.164. null when it was withheld.

caller.namestring or null

Their listed name, when you look caller names up and one is listed.

caller.citystring or null

The city their number belongs to.

caller.statestring or null

The state or region their number belongs to.

caller.countrystring or null

The country their number belongs to, as a two-letter code.

trackingNumberstring or null

The tracking number they dialled.

forwardedTostring or null

The number it rang. null when it was not forwarded.

usestring or null

What that tracking number was used for when the call came in: pool or dedicated.

sourceobject

For a dedicated number, the source it was kept for when the call came in. Each null for a pool number.

Child attributes
source.labelstring or null

What you call the source, such as Van #3 signage.

source.categorystring or null

Its kind: billboard, vehicle, signage, print, social, listing, direct_mail, radio, tv, email, event, partner or other.

source.campaignstring or null

The campaign you grouped it under.

firstTimeCallerboolean or null

Whether it is the first call from the caller's number to your account. null when the number was withheld.

apaspidstring or null

The APAS® Person ID of the person who called: the visitor who held the number, or the person with that phone number. null when neither is a person of your account yet.

apasidstring or null

The APAS® ID of the visitor who held the number when they called. null for a call no visit is tied to.

apasclidstring or null

The APAS® Click ID of that visitor's latest click through one of your Edge URLs. null when they had none.

utmobject

The UTM tags of the visit behind the call: source, medium, campaign, term and content.

clickIdsobject

The ad click IDs of the visit behind the call, each under the name its ad platform gives it. Holds gclid, gbraid, wbraid, msclkid, fbclid, ttclid, li_fat_id, twclid and rdt_cid, each a string or null.

agentstring or null

The agent who picked up, for a call routed through a call queue. null for any other call.

queueobject

The call queue it went through: its name, how long the caller waited and how they left it. Each null for a call no queue held.

Child attributes
queue.namestring or null

The queue.

queue.waitedSecondsinteger or null

How long they waited in it, in seconds.

queue.exitReasonstring or null

How they left it, listed below.

recordedboolean

Whether the call was recorded.

transcribedboolean

Whether the call has a transcript.

Outcomes

answered

The phone that rang picked up. Its statuses: completed.

missed

Nobody picked up: the caller hung up first, it rang out or was busy, or the call could not go through. Its statuses: missed, no_answer, busy, canceled, failed.

rejected

Your call routing turned it away. Its statuses: rejected.

live

Still going. Its statuses: initiated, ringing, in_progress.

Leaving a queue

bridged

An agent picked up.

hangup

The caller hung up while waiting.

overflow_leave

They waited as long as the queue allows and left it for what comes next.

system_error

The phone network could not keep the call in the queue.

error

The call left the queue on an error.

The call object
{
  "id": "cmgq8w3fd0011l308h2j4k6m8",
  "startedAt": "2026-10-14T09:21:15Z",
  "endedAt": "2026-10-14T09:25:27Z",
  "durationSeconds": 252,
  "direction": "inbound",
  "outcome": "answered",
  "status": "completed",
  "caller": {
    "number": "+12015550123",
    "name": "DOE JANE",
    "city": "Jersey City",
    "state": "NJ",
    "country": "US"
  },
  "trackingNumber": "+12015550142",
  "forwardedTo": "+12015550100",
  "use": "pool",
  "source": {
    "label": null,
    "category": null,
    "campaign": null
  },
  "firstTimeCaller": true,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "brand",
    "term": null,
    "content": null
  },
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": null,
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "agent": null,
  "queue": {
    "name": null,
    "waitedSeconds": null,
    "exitReason": null
  },
  "recorded": false,
  "transcribed": false
}

List calls

GET/api/v1/calls

Returns your calls of a period, newest first: all of them, or those of one outcome, one tracking number or one person. Yesterday's missed calls, say, as a list to call back. A caller's number is never a parameter: to read someone's calls, give their APAS® Person ID.

Query parameters

fromstringOptional

The start of the period, in ISO 8601. Left out, it is 30 days before the end.

tostringOptional

The end of the period, in ISO 8601. Left out, it is now. A period is at most 93 days.

outcomestringOptional

Only the calls of one outcome: answered, missed, rejected or live.

trackingNumberstringOptional

Only the calls to one tracking number, in any form: +12015550187, 12015550187 or (201) 555-0187.

apaspidstringOptional

Only one person's calls, by their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs: the calls tied to a visit of theirs, and the calls from their phone numbers. With it the period is not needed: left out, every call of theirs comes back.

limitintegerOptional

How many calls a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, a call's. See Choosing fields.

Returns

A list: items holds call objects, total says how many calls there are over every page, and nextCursor is what to send as cursor for the next page, or null on the last one. No person of your account with that ID is a 404.

Request
curl -G \
  -d "from=2026-11-10T00:00:00Z" \
  -d "to=2026-11-11T00:00:00Z" \
  -d "outcome=missed" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/calls"
Response · 200
{
  "items": [
    {
      "id": "cmhw1k8pz0004l608n3p5r7t9",
      "startedAt": "2026-11-10T08:15:02Z",
      "endedAt": "2026-11-10T08:15:31Z",
      "durationSeconds": 0,
      "direction": "inbound",
      "outcome": "missed",
      "status": "missed",
      "caller": {
        "number": "+12015550168",
        "name": null,
        "city": "Newark",
        "state": "NJ",
        "country": "US"
      },
      "trackingNumber": "+12015550187",
      "forwardedTo": "+12015550100",
      "use": "dedicated",
      "source": {
        "label": "Van #3 signage",
        "category": "vehicle",
        "campaign": "Spring 2026"
      },
      "firstTimeCaller": true,
      "apaspid": null,
      "apasid": null,
      "apasclid": null,
      "utm": {
        "source": null,
        "medium": null,
        "campaign": null,
        "term": null,
        "content": null
      },
      "clickIds": {
        "gclid": null,
        "gbraid": null,
        "wbraid": null,
        "msclkid": null,
        "fbclid": null,
        "ttclid": null,
        "li_fat_id": null,
        "twclid": null,
        "rdt_cid": null
      },
      "agent": null,
      "queue": {
        "name": null,
        "waitedSeconds": null,
        "exitReason": null
      },
      "recorded": false,
      "transcribed": false
    }
  ],
  "nextCursor": null,
  "total": 1
}

Get a call

GET/api/v1/calls/<id>

Returns one call by its ID.

Path parameters

idstringRequired

The call's ID.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The call object, or a 404 when no call of your account has that ID.

Request
curl "https://api.apascloud.com/api/v1/calls/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cmgq8w3fd0011l308h2j4k6m8",
  "startedAt": "2026-10-14T09:21:15Z",
  "endedAt": "2026-10-14T09:25:27Z",
  "durationSeconds": 252,
  "direction": "inbound",
  "outcome": "answered",
  "status": "completed",
  "caller": {
    "number": "+12015550123",
    "name": "DOE JANE",
    "city": "Jersey City",
    "state": "NJ",
    "country": "US"
  },
  "trackingNumber": "+12015550142",
  "forwardedTo": "+12015550100",
  "use": "pool",
  "source": {
    "label": null,
    "category": null,
    "campaign": null
  },
  "firstTimeCaller": true,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "apasid": "3f2b8c1e-7a4d-4e9b-9c55-1d2e3f4a5b6c",
  "apasclid": "1791969600000.9b2f6c1e-5d3a-4f7b-8e21-6a7b8c9d0e1f",
  "utm": {
    "source": "google",
    "medium": "cpc",
    "campaign": "brand",
    "term": null,
    "content": null
  },
  "clickIds": {
    "gclid": "EAIaIQobChMI-example",
    "gbraid": null,
    "wbraid": null,
    "msclkid": null,
    "fbclid": null,
    "ttclid": null,
    "li_fat_id": null,
    "twclid": null,
    "rdt_cid": null
  },
  "agent": null,
  "queue": {
    "name": null,
    "waitedSeconds": null,
    "exitReason": null
  },
  "recorded": false,
  "transcribed": false
}

The Email Center object

Your Email Center itself: whether it can send and what is still to set up, the domains your emails go from, who they are from, the footer they end with, who may be emailed and the limits on sending. A check your system can make before it counts on an email going out. It never carries a DNS record, a credential or an ID of the email provider's.

The Email Center reads come from your account, not your warehouse, so they count only toward the limits every call has.

Attributes

sendingstring

Whether it can send: ready, not_ready or paused, listed below.

setuparray of strings

What is still to set up before it can send, in the order it is needed, listed below. Empty when nothing is.

pausedAttimestamp or null

When the brakes paused sending. null when they did not.

pausedReasonstring or null

Why: bounces or complaints (spam reports). null when sending is not paused.

sendingDomainobject

The domain your emails go from, and where it stands.

Child attributes
sendingDomain.domainstring or null

The domain.

sendingDomain.statusstring or null

Where it stands: none, pending, verified or error, listed below.

broadcastDomainobject

The domain your broadcasts go from when you set one up, and where it stands. Its domain is null when broadcasts go from the sending domain.

Child attributes
broadcastDomain.domainstring or null

The domain.

broadcastDomain.statusstring or null

Where it stands: none, pending, verified or error, listed below.

fromobject

Who your emails are from: the From name and address. Each null until you set it.

Child attributes
from.namestring or null

The From name.

from.addressstring or null

The From address, on the sending domain.

replyTostring or null

Where replies go, when not to the From address. null when they go there.

footerobject

The business name and postal address every email ends with. Each null until you set it.

Child attributes
footer.namestring or null

The business name.

footer.addressstring or null

The postal address.

consentOnlyboolean

Whether only people who gave consent can be emailed, rather than leads and customers too.

doubleOptInboolean

Whether someone new confirms their address before they are emailed.

frequencyCapobject or null

The most emails one person gets in a period: max, and period (day, week, two_weeks or month). null when there is no cap.

Child attributes
frequencyCap.maxinteger or null

How many emails.

frequencyCap.periodstring or null

Over what period: day, week, two_weeks or month.

minBotScoreinteger

The lowest APAS® Bot Score someone may have and still be emailed, so bots that filled in a form are not.

Sending

ready

It sends: everything is set up and nothing paused it.

not_ready

Something is still to set up: setup says what, and emails are held back until it is.

paused

The brakes paused it after too many bounces or spam reports: nothing is sent until an administrator resumes it in Email Center Settings.

Still to set up

no_sender_account

Email Center is not set up at the sender yet.

domain_not_verified

The sending domain is not verified yet.

no_sender

No From name or address yet.

no_footer

No business name or postal address for the footer yet.

Domain statuses

none

None is set up.

pending

Set up, its DNS records not all found yet.

verified

Verified: its DKIM, Return-Path and DMARC records were found.

error

Its check failed: Email Center Settings says why.

The Email Center object
{
  "sending": "ready",
  "setup": [],
  "pausedAt": null,
  "pausedReason": null,
  "sendingDomain": {
    "domain": "mail.example.com",
    "status": "verified"
  },
  "broadcastDomain": {
    "domain": "news.example.com",
    "status": "verified"
  },
  "from": {
    "name": "Example Co",
    "address": "[email protected]"
  },
  "replyTo": "[email protected]",
  "footer": {
    "name": "Example Co",
    "address": "123 Main Street, Jersey City, NJ 07302"
  },
  "consentOnly": false,
  "doubleOptIn": true,
  "frequencyCap": {
    "max": 3,
    "period": "week"
  },
  "minBotScore": 2
}

Get the Email Center

GET/api/v1/email-center

Returns your Email Center. It takes no parameters.

Returns

The Email Center object. An account that never set up its Email Center answers not_ready, with everything still to set up.

Request
curl "https://api.apascloud.com/api/v1/email-center" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "sending": "ready",
  "setup": [],
  "pausedAt": null,
  "pausedReason": null,
  "sendingDomain": {
    "domain": "mail.example.com",
    "status": "verified"
  },
  "broadcastDomain": {
    "domain": "news.example.com",
    "status": "verified"
  },
  "from": {
    "name": "Example Co",
    "address": "[email protected]"
  },
  "replyTo": "[email protected]",
  "footer": {
    "name": "Example Co",
    "address": "123 Main Street, Jersey City, NJ 07302"
  },
  "consentOnly": false,
  "doubleOptIn": true,
  "frequencyCap": {
    "max": 3,
    "period": "week"
  },
  "minBotScore": 2
}

The email status object

Where one person stands for your email, as Email Center works it out for every email it sends and as APAS® 360 shows it: the address they are emailed at, whether they can be emailed and why, whether your broadcasts reach them, and what stops them. When someone unsubscribes from an email of yours, your other systems can stop emailing them too, and when they unsubscribe in one of your systems, Unsubscribe someone stops Email Center's.

The Email Center reads come from your account, not your warehouse, so they count only toward the limits every call has.

Attributes

apaspidstring

The APAS® Person ID of the person.

addressstring or null

The address Email Center emails them at. null when they have none.

statusstring

Where they stand: subscribed, unconfirmed, no_reason, unsubscribed, bounced, spam or no_address, listed below.

reasonstring or null

Why they may be emailed, when they are subscribed: consent, lead or customer, listed below.

broadcastsboolean

Whether your broadcasts reach them. A broadcast goes only to people who gave consent.

changedAttimestamp or null

Since when a stop holds them: when they unsubscribed, bounced or reported spam. null without a stop on record.

changedBystring or null

What recorded that stop: person, email_provider, teammate or your_system, listed below. null without a stop on record.

Statuses

subscribed

No stop on their address, and a reason to email them in force.

unconfirmed

Double opt-in is on and they have not confirmed their address yet.

no_reason

Nothing on record allows emailing them: no consent, no request of their own and no purchase.

unsubscribed

They unsubscribed. Only they can undo it.

bounced

Their address does not exist or refuses mail.

spam

They marked an email of yours as spam.

no_address

They have no email address.

Reasons

consent

They said yes to your emails: on a form, a quiz, a booking or an import, or by confirming their address.

lead

They asked you for something themselves: a form, a quiz, a booking, a call or a text.

customer

They became a customer: they reached green.

What recorded a stop

person

They did it themselves, from an email or the page it led them to.

email_provider

The email provider reported it: a bounce, or a spam report.

teammate

A teammate of yours: unsubscribing them by hand on their APAS® 360 page, or changing their address.

your_system

Your own system, with Unsubscribe someone.

The email status object
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "address": "[email protected]",
  "status": "subscribed",
  "reason": "consent",
  "broadcasts": true,
  "changedAt": null,
  "changedBy": null
}

Get a person's email status

GET/api/v1/persons/<apaspid>/email-status

Returns one person's email status. It takes no query parameters.

Path parameters

apaspidstringRequired

Their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs in its place, as Get a person takes it.

Returns

The email status object, or a 404 when no person of your account has that ID.

Request
curl "https://api.apascloud.com/api/v1/persons/<apaspid>/email-status" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "address": "[email protected]",
  "status": "subscribed",
  "reason": "consent",
  "broadcasts": true,
  "changedAt": null,
  "changedBy": null
}

The email object

One email Email Center sent or held back, as your Email Log shows it: what sent it, to whom, how it went, and when it was delivered, opened, clicked, bounced, marked as spam or unsubscribed from. Opens and clicks are counted as your Email Center reports count them. It never carries the email's content.

Attributes

idstring

Its ID: the one Get an email takes.

namestring

The name the email has in Email Center.

subjectstring

Its subject line, as it was sent.

kindstring

What sent it: automation, broadcast, confirmation or personal, listed below.

automationobject or null

The automation that sent it: its ID and name. null for any other email.

Child attributes
automation.idstring or null

Its ID.

automation.namestring or null

Its name.

broadcastobject or null

The broadcast that sent it: its ID and name. null for any other email.

Child attributes
broadcast.idstring or null

Its ID.

broadcast.namestring or null

Its name.

apaspidstring or null

The APAS® Person ID of the person it was for. null when that person is no longer in your account.

tostring or null

The address it went to. null for an email held back before it had one.

createdAttimestamp

When it was due: the moment Email Center wrote it down, before anything left.

sentAttimestamp or null

When the email provider took it. null for one not sent.

outcomestring

How it went: sent, held, refused or sending, listed below.

heldReasonstring or null

Why it was held back or refused, listed below. null for one sent.

reasonstring or null

Why the person could be emailed when it went: consent, lead or customer. null for one held back before it was decided.

deliveredAttimestamp or null

When their mail server accepted it. null until it did.

openedAttimestamp or null

When they first opened it, as Email Center counts opens: a click counts as an open, and an open by Apple Mail's privacy proxy or a link scanner does not. null until they did.

clickedAttimestamp or null

When they first clicked a link in it, as Email Center counts clicks: a link to your site counts once their visit lands, and a link scanner never counts. null until they did.

bouncedAttimestamp or null

When it bounced. null if it did not.

spamAttimestamp or null

When they marked it as spam. null if they did not.

unsubscribedAttimestamp or null

When they unsubscribed from it. null if they did not.

Kinds

automation

A step of one of your automations.

broadcast

One of your broadcasts: sent once, an RSS issue, or a resend.

confirmation

The double opt-in email asking them to confirm their address.

personal

An email a teammate wrote to them from their record.

Outcomes

sent

Handed to the email provider. delivered and the rest say what came of it.

held

Held back: heldReason says why.

refused

The email provider refused it, or could not be reached: heldReason says which.

sending

On its way.

Why an email was held back or refused

no_sender_account

Email Center is not set up at the sender yet.

sending_paused

Sending is paused.

domain_not_verified

The sending domain is not verified yet.

no_sender

No From name or address yet.

no_footer

No business name or postal address for the footer yet.

no_address

No email address.

unsubscribed

They unsubscribed.

bounced

Their address bounced.

spam

They marked an email as spam.

no_reason

No reason to email them on record.

no_consent

They have not given consent to your emails.

not_confirmed

They have not confirmed their address (double opt-in).

type_opted_out

They opted out of this kind of email.

already_confirmed

They had confirmed already.

bot

Their APAS® Bot Score is below your minimum.

frequency_cap

Reached frequency cap.

step_removed

The step was removed before it sent.

broadcast_removed

The broadcast was removed before it sent.

run_left

They left the automation before it sent.

duplicate_address

Their address already got this broadcast.

no_person

The person is no longer in APAS® 360.

unknown_kind

The email could not be read.

inactive_recipient

The sender will not deliver to this address: it bounced, complained or unsubscribed before.

invalid_request

The sender refused the email.

sender_key

The sender refused its key.

sender_unreachable

The sender could not be reached.

sender_domain

The sender does not know the sending domain.

refused

The sender refused the email.

account_cancelled

The account was cancelled.

The email object
{
  "id": "cmhx7a2kd0006l908p4q6r8s0",
  "name": "Thank you",
  "subject": "Thanks for choosing us, Jane",
  "kind": "automation",
  "automation": {
    "id": "cmh2d9e1f0001l108a2b3c4d5",
    "name": "New customer welcome"
  },
  "broadcast": null,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "to": "[email protected]",
  "createdAt": "2026-11-03T09:30:00Z",
  "sentAt": "2026-11-03T09:30:01Z",
  "outcome": "sent",
  "heldReason": null,
  "reason": "consent",
  "deliveredAt": "2026-11-03T09:30:04Z",
  "openedAt": "2026-11-03T10:12:37Z",
  "clickedAt": "2026-11-03T10:13:02Z",
  "bouncedAt": null,
  "spamAt": null,
  "unsubscribedAt": null
}

List emails

GET/api/v1/emails

Returns your emails of a period, newest first: all of them, or those of one outcome, one kind, one automation, one broadcast or one person. A test email, which goes to a teammate, is not listed.

Query parameters

fromstringOptional

The start of the period, in ISO 8601. Left out, it is 30 days before the end.

tostringOptional

The end of the period, in ISO 8601. Left out, it is now. A period is at most 93 days.

outcomestringOptional

Only the emails of one outcome: sent, held, refused or sending.

kindstringOptional

Only the emails of one kind: automation, broadcast, confirmation or personal.

automationstringOptional

Only the emails of one automation, by its ID.

broadcaststringOptional

Only the emails of one broadcast, by its ID.

apaspidstringOptional

Only one person's emails, by their APAS® Person ID, or an APAS® ID or an APAS® Click ID of theirs. With it the period is not needed: left out, every email of theirs comes back.

limitintegerOptional

How many emails a page holds: 50 unless you say, 100 at most: a larger number gives 100.

cursorstringOptional

The nextCursor of the page before, to get the page after it.

fieldsstringOptional

The fields to answer with, an email's. See Choosing fields.

Returns

A list: items holds email objects, total says how many emails there are over every page, and nextCursor is what to send as cursor for the next page, or null on the last one. No person of your account with that ID is a 404.

Request
curl -G \
  -d "from=2026-11-01T00:00:00Z" \
  -d "to=2026-11-16T00:00:00Z" \
  -H "Authorization: Bearer <your API key>" \
  "https://api.apascloud.com/api/v1/emails"
Response · 200
{
  "items": [
    {
      "id": "cmhz3c5ne0009l008s7t9v1w3",
      "name": "November newsletter",
      "subject": "What is new this November",
      "kind": "broadcast",
      "automation": null,
      "broadcast": {
        "id": "cmhy8b4me0002l808q5r7t9u1",
        "name": "November newsletter"
      },
      "apaspid": "7d2e9a41-3c5b-4f86-9e17-2a4b6c8d0e1f",
      "to": "[email protected]",
      "createdAt": "2026-11-10T15:00:00Z",
      "sentAt": null,
      "outcome": "held",
      "heldReason": "no_consent",
      "reason": null,
      "deliveredAt": null,
      "openedAt": null,
      "clickedAt": null,
      "bouncedAt": null,
      "spamAt": null,
      "unsubscribedAt": null
    },
    {
      "id": "cmhx7a2kd0006l908p4q6r8s0",
      "name": "Thank you",
      "subject": "Thanks for choosing us, Jane",
      "kind": "automation",
      "automation": {
        "id": "cmh2d9e1f0001l108a2b3c4d5",
        "name": "New customer welcome"
      },
      "broadcast": null,
      "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
      "to": "[email protected]",
      "createdAt": "2026-11-03T09:30:00Z",
      "sentAt": "2026-11-03T09:30:01Z",
      "outcome": "sent",
      "heldReason": null,
      "reason": "consent",
      "deliveredAt": "2026-11-03T09:30:04Z",
      "openedAt": "2026-11-03T10:12:37Z",
      "clickedAt": "2026-11-03T10:13:02Z",
      "bouncedAt": null,
      "spamAt": null,
      "unsubscribedAt": null
    }
  ],
  "nextCursor": null,
  "total": 2
}

Get an email

GET/api/v1/emails/<id>

Returns one email by its ID.

Path parameters

idstringRequired

The email's ID.

Query parameters

fieldsstringOptional

The fields to answer with. See Choosing fields.

Returns

The email object, or a 404 when no email of your account has that ID.

Request
curl "https://api.apascloud.com/api/v1/emails/<id>" \
  -H "Authorization: Bearer <your API key>"
Response · 200
{
  "id": "cmhx7a2kd0006l908p4q6r8s0",
  "name": "Thank you",
  "subject": "Thanks for choosing us, Jane",
  "kind": "automation",
  "automation": {
    "id": "cmh2d9e1f0001l108a2b3c4d5",
    "name": "New customer welcome"
  },
  "broadcast": null,
  "apaspid": "0b6f4c2a-91d3-4e58-a7b2-6c1d9e3f5a84",
  "to": "[email protected]",
  "createdAt": "2026-11-03T09:30:00Z",
  "sentAt": "2026-11-03T09:30:01Z",
  "outcome": "sent",
  "heldReason": null,
  "reason": "consent",
  "deliveredAt": "2026-11-03T09:30:04Z",
  "openedAt": "2026-11-03T10:12:37Z",
  "clickedAt": "2026-11-03T10:13:02Z",
  "bouncedAt": null,
  "spamAt": null,
  "unsubscribedAt": null
}

AI tools (MCP)

The same keys connect AI tools that speak the Model Context Protocol, such as Claude Code, Cursor and Codex. The configuration to paste is in your account, under Integrations → Credentials, on the Connect a tool card below your keys.

Over MCP a key reads your account and your persons, and runs read-only queries on your warehouse, your calls, your submissions, your bookings and your flows. Records, conversions, audiences, lists, clicks, credit, events, the Call Center's numbers and settings and the Email Center are read through the calls above. MCP calls count toward the same limits as the calls above, and a request from a web page is refused there too, with a 403: a key stays on a server.

Need a field or a call that is not here yet? Tell us.

MCP endpoint
https://api.apascloud.com/api/mcp