Holds and human review
Some actions need a person. When a check holds, the action waits, a reviewer decides, and your agent follows that decision. The review is recorded on a signed receipt, so you can show who decided and when.
When a check holds
A check holds when the action is high-stakes and the answer depends on judgment, for example a rental listing that may exclude a protected group, or a rule that applies but is still being verified. Your review settings in the dashboard decide which uncertain checks hold and which come back as flags. Clear-cut violations never hold: they block.
A held check answers 202 Accepted. The body is a normal check response with decision: "hold", its own receipt and a hold object. The Location header and hold.status_url both point to the hold.
{
"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
}
}
Who reviews
- Your team. Holds appear in the review queue in the dashboard, with the action, the rules involved and the related law. Members with the Reviewer role decide.
Holds are decided by your own reviewers. Cerata staff do not decide holds for you.
Some holds first get a short automated second review (kind: "agent_panel", state: "pending_panel"). It settles quickly or passes the hold to a person. Poll the same URL either way.
Holds are capped by a daily hold budget. When it is used up, a check that would have held comes back as a high-risk flag with the reason hold_budget_exhausted. Your agent still doesn't send it.
Get the decision
Poll GET /v1/holds/{id} with the same API key. Start no faster than eta_seconds suggests, and back off.
// Poll a held check until someone decides. Back off between polls.
async function waitForDecision(statusUrl: string): Promise<HoldStatus> {
let delay = 5_000;
for (;;) {
const res = await fetch(`https://clearance-kohl.vercel.app${statusUrl}`, {
headers: { Authorization: `Bearer ${process.env.CERATA_API_KEY}` },
});
if (!res.ok) throw new Error(`hold status ${res.status}`); // fail closed
const hold = await res.json();
if (hold.state === 'expired' || hold.state === 'cancelled') return hold; // not approved
if (hold.decision !== 'hold') return hold; // clear, flag or block
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(delay * 2, 300_000);
}
}
import os, time
import requests
def wait_for_decision(status_url):
"""Poll a held check until someone decides. Back off between polls."""
delay = 5
while True:
res = requests.get(
f"https://clearance-kohl.vercel.app{status_url}",
headers={"Authorization": f"Bearer {os.environ['CERATA_API_KEY']}"},
timeout=10,
)
res.raise_for_status() # fail closed
hold = res.json()
if hold["state"] in ("expired", "cancelled"):
return hold # not approved
if hold["decision"] != "hold":
return hold # clear, flag or block
time.sleep(delay)
delay = min(delay * 2, 300)
{
"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…"
}
Hold states
| state | What it means | What your agent does |
|---|---|---|
pending_panel | A short automated review is running. | Wait and poll. |
queued_for_person | Waiting for a reviewer. | Wait and poll. |
decided | A reviewer decided. decision and review.outcome say clear, flag or block. | Follow it like any other decision. |
expired | No one decided in time. | Don't act. Check again if the action still matters. |
cancelled | The hold was withdrawn. | Don't act. |
A decided hold can carry reasons and fixes (after a flag or block), a token (after a clear, when the original check asked for one), and a receipt: a new signed receipt for the reviewer's decision, which records the review. Keep it with the action.
Webhooks
Coming soon
A hold.resolved event, signed under the Standard Webhooks scheme, is coming soon. Endpoint setup is not available in the dashboard yet, so poll the hold for now. This page will document the payload when webhooks open.
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.