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:
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
| Field | Type | Required | Description |
|---|---|---|---|
action | object | Required | The action your agent is about to take. |
action. | enum | Required | One of outbound_call, outbound_text, email, rental_listing, job_post, product_listing, price_quote, generic. |
action. | enum | Optional | What the action is about beside its channel: housing, hiring, commerce, food or other. |
action. | string | Required | When 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. | string | Required | Required 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. | string | Optional | What the outreach is about. A scoped revocation applies only when action.subject equals its scope exactly. |
action. | boolean | Optional | Placed or sent by an autodialer or other automated system. |
action. | boolean | Optional | Uses an artificial or prerecorded voice. |
action. | number | Optional | How many people this action, or the campaign it belongs to, reaches. |
action. | object | Optional | Caller 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. |
sender | object | Optional | Who the action is from. |
sender. | string | Required | The business or person sending. Required when sender is present. |
sender. | string | Optional | The sender's physical postal address. |
sender. | number | Optional | Number of employees, for job posts. |
recipient | object | Optional | Who the action is for. |
recipient. | string | Optional | E.164 format, for example +18135550142. |
recipient. | string | Optional | Email address. |
recipient. | object | null | Optional | line1, 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. | object | Optional | US Census geography ids instead of an address: state, county, place (or null). |
recipient. | object | Optional | type: 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. | boolean | Optional | The number is on a do-not-call registry, from your own registry scrub. |
recipient. | boolean | Optional | You have an existing business relationship with this person. |
recipient. | number | Optional | Calls you already placed to this person in the last 24 hours. |
content | object | Optional | What the action says. |
content. | string | Optional | The message, script, listing or job ad text. |
content. | string | Optional | Email subject line. |
content. | boolean | Optional | The message clearly says it is an advertisement. |
content. | boolean | Optional | The message includes a working way to opt out. |
content. | boolean | Optional | The message includes the sender's valid postal address. |
property | object | Optional | For rental listings. |
property. | object | Required | Same shape as recipient.address. Required when property is present. |
property. | object | Optional | Census geography ids, as for the recipient. |
property. | enum | Optional | 55_plus or 62_plus when the property is housing for older persons. |
property. | string | Optional | Your id for the property, 1 to 256 characters. |
job | object | Optional | For job posts. |
job. | string | Required | Job title. Required when job is present. |
job. | array | Required | Where the work happens: {state, city?} objects. |
job. | boolean | Optional | The role can be done remotely. |
job. | string[] | Optional | Places remote candidates may work from. |
token | object | Optional | Ask 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
| Header | Description |
|---|---|
Authorization | Required. Bearer <API key>. |
Content-Type | Required. application/json. |
Idempotency-Key | Recommended. 1 to 255 printable ASCII characters, unique per action. See idempotency. |
X-Request-Id | Optional. Your own id for the request, echoed back. |
Response body
| Field | Type | Always | Description |
|---|---|---|---|
check_id | string | Always | This check's id, chk_…. |
receipt_id | string | Always | The id of this check's receipt. Store it with the action. |
env | string | Always | The key's environment: test or live. |
decision | enum | Always | clear, flag, hold or block. |
risk_level | enum | Always | low, medium or high. |
uncertainty | number | Sometimes | Present when part of the check could not be settled, from 0 to 1. |
jurisdictions | string[] | Always | The places whose rules were applied, for example US, US-FL. |
rules | array | Always | One entry per rule that applied: id, version, result, reasons. Other members can appear; treat them as diagnostic. |
rules[]. | enum | Always | passed, 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). |
reasons | string[] | Always | Rule ids and reason codes behind the decision. See reasons. |
fixes | array | Always | {code, text?} objects your agent can apply before checking again. |
receipt | string | Always | The signed receipt, a compact JWS. See receipts. |
token | string | Sometimes | A clearance token, only on clear and only when the request asked for one. |
hold | object | Sometimes | Only on hold: hold_id, status_url, kind, state, eta_seconds. |
hold. | string | Always | A path, /v1/holds/{id}. Prefix it with https://clearance-kohl.vercel.app. |
hold. | number | Sometimes | Roughly how long until a decision. Poll no faster than this suggests. |
decision_digest | string | Always | sha256:… commitment to the decision. The same facts under the same rules give the same digest. |
policy | object | Always | The review settings that applied to this check. Diagnostic. |
relied_on | array | Sometimes | Stored 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"))
{
"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_progresswithRetry-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.
| Status | error.code | Meaning |
|---|---|---|
200 | None | A decided check: clear, flag or block. |
202 | None | A held check. Location and hold.status_url name the hold. |
400 | None | The body is not valid JSON. |
400 | invalid_idempotency_key | The Idempotency-Key is not 1 to 255 printable ASCII characters. |
401 | None | The key is missing, malformed or not accepted. The response never says which. WWW-Authenticate is set. |
402 | None | Billing 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. |
404 | None | No such hold in your organization and environment. |
409 | idempotency_in_progress | A request with this Idempotency-Key is still running. Retry after Retry-After seconds. |
422 | invalid_facts | The facts fail validation. error.issues lists each problem with its path. |
422 | idempotency_key_reused | This Idempotency-Key was already used with a different body. |
429 | None | Over a rate limit. Wait Retry-After seconds. |
500 | None | Something failed on our side. Don't act; retry later. |
503 | None | A dependency is unavailable and the check fails closed. Don't act; retry with backoff. |
{
"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.
General information, not legal advice. Cerata is not a law firm. A check tells you what the rules Cerata covers say about one action; it is not a guarantee that the action is lawful.