1. Cerata
  2. Docs
  3. API reference

API reference

One endpoint decides an action: POST /v1/preflight. Two more support it: GET /v1/holds/{id} for held checks and POST /v1/verify for receipts and tokens. All JSON over HTTPS.

Base URL and authentication

All requests go to https://clearance-kohl.vercel.app. Authenticate with your API key as a Bearer token:

HTTP
Authorization: Bearer ak_test_…

Keys come from the dashboard under Agents and keys; during the preview, contact us for a test key. A key is shown once and belongs to one environment, test or live. A missing, malformed or refused key returns 401 with a WWW-Authenticate header, and the response never says why the key was refused. Keep keys on your server.

POST /v1/preflight

Decide one action. Send the facts you know; action.type and action.at are always required, and action.purpose is required for outbound_call and outbound_text (send exactly telemarketing). Every other field is optional, but missing facts can turn a clear into a flag. Unknown fields are ignored.

Request body

FieldTypeRequiredDescription
actionobjectRequiredThe action your agent is about to take.
action.typeenumRequiredOne of outbound_call, outbound_text, email, rental_listing, job_post, product_listing, price_quote, generic.
action.contextenumOptionalWhat the action is about beside its channel: housing, hiring, commerce, food or other.
action.atstringRequiredWhen the action happens, as ISO 8601 with a UTC offset or Z, for example 2026-10-21T10:05:00-04:00. Times without an offset are rejected.
action.purposestringRequiredRequired for calls and texts: send exactly telemarketing for a sales or marketing call or text. Any other value is outside coverage and is flagged, never cleared. The match is exact and case-sensitive; a missing or free-text purpose on a call or text comes back as a flag with the reason out_of_coverage and no fixes. For listings and job posts, send advertisement.
action.subjectstringOptionalWhat the outreach is about. A scoped revocation applies only when action.subject equals its scope exactly.
action.automatedbooleanOptionalPlaced or sent by an autodialer or other automated system.
action.artificial_voicebooleanOptionalUses an artificial or prerecorded voice.
action.volumenumberOptionalHow many people this action, or the campaign it belongs to, reaches.
action.caller_idobjectOptionalCaller ID facts for calls: number_transmitted, name_transmitted, callback_reachable, seller_name_substitution, carrier_name_unavailable, seller_name_transmitted, seller_service_number_transmitted, seller_service_number_answered_business_hours, callback_connects_solicitor_or_seller. All booleans.
senderobjectOptionalWho the action is from.
sender.namestringRequiredThe business or person sending. Required when sender is present.
sender.postal_addressstringOptionalThe sender's physical postal address.
sender.employer_sizenumberOptionalNumber of employees, for job posts.
recipientobjectOptionalWho the action is for.
recipient.phonestringOptionalE.164 format, for example +18135550142.
recipient.emailstringOptionalEmail address.
recipient.addressobject | nullOptionalline1, city, zip required; state, country optional. This is how Cerata finds the state and local rules that apply. Send it whenever you have it.
recipient.geoidobjectOptionalUS Census geography ids instead of an address: state, county, place (or null).
recipient.consentobjectOptionaltype: prior_express_written, prior_express, unknown or none. revocations: list of {scope?, at} when the person opted out. A revocation with no scope blocks every subject. A scoped revocation applies only when action.subject equals its scope exactly, and is checked against action.at. A scoped revocation sent without action.subject is flagged.
recipient.dnc_registeredbooleanOptionalThe number is on a do-not-call registry, from your own registry scrub.
recipient.established_business_relationshipbooleanOptionalYou have an existing business relationship with this person.
recipient.prior_calls_24hnumberOptionalCalls you already placed to this person in the last 24 hours.
contentobjectOptionalWhat the action says.
content.textstringOptionalThe message, script, listing or job ad text.
content.subjectstringOptionalEmail subject line.
content.identified_as_adbooleanOptionalThe message clearly says it is an advertisement.
content.opt_out_mechanismbooleanOptionalThe message includes a working way to opt out.
content.postal_address_presentbooleanOptionalThe message includes the sender's valid postal address.
propertyobjectOptionalFor rental listings.
property.addressobjectRequiredSame shape as recipient.address. Required when property is present.
property.geoidobjectOptionalCensus geography ids, as for the recipient.
property.older_personsenumOptional55_plus or 62_plus when the property is housing for older persons.
property.idstringOptionalYour id for the property, 1 to 256 characters.
jobobjectOptionalFor job posts.
job.titlestringRequiredJob title. Required when job is present.
job.work_locationsarrayRequiredWhere the work happens: {state, city?} objects.
job.remote_eligiblebooleanOptionalThe role can be done remotely.
job.remote_open_tostring[]OptionalPlaces remote candidates may work from.
tokenobjectOptionalAsk for a clearance token: "token": {"aud": "<the receiving service>"}. aud (required) names the service that will receive the action; single_use (optional) makes it redeemable once. Tokens are issued only on clear. Not a fact: it never changes the decision.

Request headers

HeaderDescription
AuthorizationRequired. Bearer <API key>.
Content-TypeRequired. application/json.
Idempotency-KeyRecommended. 1 to 255 printable ASCII characters, unique per action. See idempotency.
X-Request-IdOptional. Your own id for the request, echoed back.

Response body

FieldTypeAlwaysDescription
check_idstringAlwaysThis check's id, chk_….
receipt_idstringAlwaysThe id of this check's receipt. Store it with the action.
envstringAlwaysThe key's environment: test or live.
decisionenumAlwaysclear, flag, hold or block.
risk_levelenumAlwayslow, medium or high.
uncertaintynumberSometimesPresent when part of the check could not be settled, from 0 to 1.
jurisdictionsstring[]AlwaysThe places whose rules were applied, for example US, US-FL.
rulesarrayAlwaysOne entry per rule that applied: id, version, result, reasons. Other members can appear; treat them as diagnostic.
rules[].resultenumAlwayspassed, fired (the rule decided against the action), indeterminate (a fact is missing or unclear), not_applied (not in force on that date), pending_verification, skipped:dominated (a more severe answer already decided).
reasonsstring[]AlwaysRule ids and reason codes behind the decision. See reasons.
fixesarrayAlways{code, text?} objects your agent can apply before checking again.
receiptstringAlwaysThe signed receipt, a compact JWS. See receipts.
tokenstringSometimesA clearance token, only on clear and only when the request asked for one.
holdobjectSometimesOnly on hold: hold_id, status_url, kind, state, eta_seconds.
hold.status_urlstringAlwaysA path, /v1/holds/{id}. Prefix it with https://clearance-kohl.vercel.app.
hold.eta_secondsnumberSometimesRoughly how long until a decision. Poll no faster than this suggests.
decision_digeststringAlwayssha256:… commitment to the decision. The same facts under the same rules give the same digest.
policyobjectAlwaysThe review settings that applied to this check. Diagnostic.
relied_onarraySometimesStored qualifications the decision relied on, when any. The receipt carries the same list.

New response fields may be added at any time. Ignore the ones you don't use.

Examples

A sales text to a Tampa number at 10:05 a.m. local time with written consent on file, asking for a token for the SMS gateway:

curl https://clearance-kohl.vercel.app/v1/preflight \
  -H "Authorization: Bearer $CERATA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "action": {
    "type": "outbound_text",
    "purpose": "telemarketing",
    "at": "2026-10-21T10:05:00-04:00",
    "automated": true
  },
  "sender": {
    "name": "Gulf Coast Motors"
  },
  "recipient": {
    "phone": "+18135550190",
    "address": {
      "line1": "601 E Kennedy Blvd",
      "city": "Tampa",
      "state": "FL",
      "zip": "33602"
    },
    "consent": {
      "type": "prior_express_written"
    },
    "dnc_registered": false,
    "prior_calls_24h": 0
  },
  "content": {
    "text": "Hi Maria, want me to book you a test drive this weekend? Reply STOP to opt out."
  },
  "token": {
    "aud": "sms-gateway.example.com"
  }
}'
const res = await fetch('https://clearance-kohl.vercel.app/v1/preflight', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CERATA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "action": {
      "type": "outbound_text",
      "purpose": "telemarketing",
      "at": "2026-10-21T10:05:00-04:00",
      "automated": true
    },
    "sender": {
      "name": "Gulf Coast Motors"
    },
    "recipient": {
      "phone": "+18135550190",
      "address": {
        "line1": "601 E Kennedy Blvd",
        "city": "Tampa",
        "state": "FL",
        "zip": "33602"
      },
      "consent": {
        "type": "prior_express_written"
      },
      "dnc_registered": false,
      "prior_calls_24h": 0
    },
    "content": {
      "text": "Hi Maria, want me to book you a test drive this weekend? Reply STOP to opt out."
    },
    "token": {
      "aud": "sms-gateway.example.com"
    }
  }),
});

if (res.status !== 200 && res.status !== 202) {
  throw new Error(`Cerata check failed: ${res.status}`); // fail closed: don't act
}
const check = await res.json();
console.log(check.decision, check.fixes);
import os, uuid
import requests

check = {
    "action": {
        "type": "outbound_text",
        "purpose": "telemarketing",
        "at": "2026-10-21T10:05:00-04:00",
        "automated": True
    },
    "sender": {
        "name": "Gulf Coast Motors"
    },
    "recipient": {
        "phone": "+18135550190",
        "address": {
            "line1": "601 E Kennedy Blvd",
            "city": "Tampa",
            "state": "FL",
            "zip": "33602"
        },
        "consent": {
            "type": "prior_express_written"
        },
        "dnc_registered": False,
        "prior_calls_24h": 0
    },
    "content": {
        "text": "Hi Maria, want me to book you a test drive this weekend? Reply STOP to opt out."
    },
    "token": {
        "aud": "sms-gateway.example.com"
    }
}

res = requests.post(
    "https://clearance-kohl.vercel.app/v1/preflight",
    headers={
        "Authorization": f"Bearer {os.environ['CERATA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=check,
    timeout=10,
)
if res.status_code not in (200, 202):
    raise RuntimeError(f"Cerata check failed: {res.status_code}")  # fail closed: don't act
result = res.json()
print(result["decision"], result.get("fixes"))
Response · 200 OK
{
  "check_id": "chk_8d2e4f6a0b1c3e5d7f9a2b4c6d8e0f1a",
  "receipt_id": "chk_8d2e4f6a0b1c3e5d7f9a2b4c6d8e0f1a",
  "env": "test",
  "decision": "clear",
  "risk_level": "low",
  "jurisdictions": [
    "US",
    "US-FL"
  ],
  "rules": [
    {
      "id": "us.tcpa.calling-hours",
      "version": "1.0.0",
      "result": "passed",
      "reasons": []
    },
    {
      "id": "us.tcpa.consent-automated",
      "version": "1.0.0",
      "result": "passed",
      "reasons": []
    },
    {
      "id": "us-fl.ftsa.consent",
      "version": "1.0.0",
      "result": "passed",
      "reasons": []
    }
  ],
  "reasons": [],
  "fixes": [],
  "receipt": "eyJhbGciOiJFZERTQSIs…",
  "token": "eyJhbGciOiJFZERTQSIs…"
}

A rental listing in Boston that says “No Section 8”. Massachusetts treats housing voucher holders as a protected source of income (M.G.L. c.151B, section 4(10)), and the rule is still being verified, so a person decides:

{
  "action": {
    "type": "rental_listing",
    "purpose": "advertisement",
    "at": "2026-10-21T09:02:00-04:00"
  },
  "sender": {
    "name": "Harbor Point Leasing"
  },
  "property": {
    "address": {
      "line1": "100 Tremont St",
      "city": "Boston",
      "state": "MA",
      "zip": "02108"
    }
  },
  "content": {
    "text": "Sunny 2BR near the Common. $3,100/mo, heat included. No Section 8. Available Nov 1."
  }
}
{
  "check_id": "chk_6a8c0e2b4d6f8a1c3e5b7d9f0a2c4e6b",
  "receipt_id": "chk_6a8c0e2b4d6f8a1c3e5b7d9f0a2c4e6b",
  "env": "test",
  "decision": "hold",
  "risk_level": "high",
  "jurisdictions": [
    "US",
    "US-MA"
  ],
  "rules": [
    {
      "id": "us-ma.housing.source-of-income",
      "version": "1.1.0",
      "result": "pending_verification",
      "reasons": [
        "rule_pending_verification"
      ]
    }
  ],
  "reasons": [
    "out_of_coverage",
    "rule_pending_verification"
  ],
  "fixes": [],
  "receipt": "eyJhbGciOiJFZERTQSIs…",
  "hold": {
    "hold_id": "hld_4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b",
    "status_url": "/v1/holds/hld_4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b",
    "kind": "person",
    "state": "queued_for_person",
    "eta_seconds": 14400
  }
}

GET /v1/holds/{id}

A held check's current status. Same API key, same organization and environment as the check. decision stays hold until a reviewer decides.

curl https://clearance-kohl.vercel.app/v1/holds/hld_4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b \
  -H "Authorization: Bearer $CERATA_API_KEY"
{
  "hold_id": "hld_4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b",
  "check_id": "chk_6a8c0e2b4d6f8a1c3e5b7d9f0a2c4e6b",
  "decision": "block",
  "state": "decided",
  "kind": "person",
  "review": {
    "by": "reviewer",
    "level": "review",
    "outcome": "block",
    "at": "2026-10-21T11:40:12Z"
  },
  "receipt": "eyJhbGciOiJFZERTQSIs…"
}

Fields: hold_id, check_id, decision, state (pending_panel, queued_for_person, decided, expired, cancelled), kind, and once decided review (by, level, outcome, at). A reviewed clear can carry a token; a reviewed flag or block carries reasons and fixes; a person's decision carries its own signed receipt. Details on holds and review.

POST /v1/verify

Check that a receipt or a clearance token is genuine. No API key needed, so anyone you share a receipt with can verify it. Send exactly one of receipt or token; for a token, also aud and, to bind it to the action, action.

curl https://clearance-kohl.vercel.app/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt": "eyJhbGciOiJFZERTQSIs…"}'
{
  "valid": true,
  "kind": "receipt",
  "kid": "2026-11-a",
  "claims": {
    "schema": "receipt/v1",
    "decision": "block",
    "jurisdictions": [
      "US",
      "US-FL"
    ]
  }
}

A well-formed request answers 200: valid is false with a reason when it doesn't verify. An empty or malformed body returns 400 with errors[]. ?consume=true redeems a token once; see tokens.

Idempotency

Send an Idempotency-Key header on every check so a network retry never counts or decides twice. Keys are kept for 24 hours per organization.

  • The same key with the same body replays the stored response, with Idempotent-Replayed: true.
  • The same key with a different body returns 422 idempotency_key_reused. A corrected request needs a new key.
  • A request still running under the key returns 409 idempotency_in_progress with Retry-After.
  • A stored error replays too, so after a 422 invalid_facts, fix the body and use a new key.

Rate limits

Checks are limited per API key and per organization, counted over a 60-second window. Authenticated checks carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Over the limit, the API answers 429 with Retry-After. Your current limits are in your dashboard; contact us if you need more.

Errors and status codes

Errors use RFC 9457 problem details with Content-Type: application/problem+json. When there is a machine-readable code, it is in error.code. Responses never include stack traces or internal messages. Every response has an X-Request-Id; include it when you contact support.

Statuserror.codeMeaning
200NoneA decided check: clear, flag or block.
202NoneA held check. Location and hold.status_url name the hold.
400NoneThe body is not valid JSON.
400invalid_idempotency_keyThe Idempotency-Key is not 1 to 255 printable ASCII characters.
401NoneThe key is missing, malformed or not accepted. The response never says which. WWW-Authenticate is set.
402NoneBilling refused the check. The body is problem+json with type ending /problems/billing-required, a reason and a billing_url. No check is recorded and no receipt is issued. Don't act.
404NoneNo such hold in your organization and environment.
409idempotency_in_progressA request with this Idempotency-Key is still running. Retry after Retry-After seconds.
422invalid_factsThe facts fail validation. error.issues lists each problem with its path.
422idempotency_key_reusedThis Idempotency-Key was already used with a different body.
429NoneOver a rate limit. Wait Retry-After seconds.
500NoneSomething failed on our side. Don't act; retry later.
503NoneA dependency is unavailable and the check fails closed. Don't act; retry with backoff.
422 Unprocessable Content
{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "error": {
    "code": "invalid_facts",
    "issues": [
      {
        "origin": "string",
        "code": "invalid_format",
        "format": "datetime",
        "path": [
          "action",
          "at"
        ],
        "message": "Invalid ISO datetime"
      }
    ]
  }
}

Treat every error as “don't act”. The API fails closed: if it can't decide safely, it answers 503 rather than guessing. Retry 429, 500 and 503 with backoff, and only send once a check returns clear.