1. Cerata
  2. Docs
  3. Decisions and fixes

Clear, flag, hold and block: what your agent should do

Every check returns exactly one decision. Your agent acts on clear and nothing else. The other three come with reasons and, where Cerata can offer one, a fix your agent can apply before it checks again.

The four decisions

Decisions are ordered from least to most severe: clear, flag, hold, block. When several rules apply, the most severe answer wins.

  1. Clear

    What it means

    Every rule Cerata covers for this action passed, and coverage is complete for the places involved, or your account has acknowledged federal-only coverage for them.

    What your agent does

    Act. Store the receipt_id with the action. If you asked for a token, pass it to the service that sends.

  2. Flag

    What it means

    Not safe to send as is. A fact is missing, a rule is still being verified, or Cerata's coverage for a place is incomplete. risk_level says how serious.

    What your agent does

    Don't send it as is. Apply the fixes and check again. If no fix applies, a person on your team decides.

  3. Hold

    What it means

    The action needs a person's judgment before it goes. The API answers 202 Accepted with a hold.

    What your agent does

    Wait. Poll hold.status_url and follow the reviewer's decision. See holds and review.

  4. Block

    What it means

    A covered rule says no. reasons names the rule and fixes says what would make it acceptable.

    What your agent does

    Don't send it. Apply the fix, for example a later send time or a required opt-out line, then check again.

Only clear means go. The SDK guards, the MCP gateway and the Agent SDK hook all deny every decision except clear, and so should your own code. A flag is not permission.

Reasons and fixes

reasons is a list of short codes. Most name the rule or the finding that decided, such as us-fl.telemarketing.hours or us.fha.advertising.familial-status. A few describe the check itself:

ReasonWhat it means
missing_factA rule needed a fact you didn't send. The fix names it, for example Provide recipient.consent.type.
out_of_coverageCerata's coverage for a place or kind of action involved is incomplete, or the check carries an unsupported action.purpose: for calls and texts anything but exactly telemarketing, including a missing purpose. It flags or holds. When the cause is the purpose, fixes is empty and acknowledging a state gap does not help: send "purpose": "telemarketing" for a sales or marketing call or text, or treat the action as unchecked. A place gap can clear only if your account has acknowledged federal-only coverage for it. See coverage.
rule_pending_verificationA rule that applies is still being verified against its official source. It never clears.
escalated_by_volumeAn uncertain answer was raised because the action reaches many people (action.volume).
hold_budget_exhaustedThe check would have held, but your hold budget for the day is used, so it flags at high risk instead.

Each fix has a code (the rule id, or missing_fact) and, usually, plain-language text your agent or your user can act on. Fixes are written to be applied, not just read.

The retry-with-fix loop

When the answer is flag or block, your agent revises the action and checks again. Keep the loop short and honest:

  1. Apply the fix

    Rewrite the message, move the send time, or remove the problem wording. For a missing_fact fix, add the fact only if your system actually knows it.

  2. Check again with a new Idempotency-Key

    A corrected request is a new request. Reusing the key with a changed body returns 422 idempotency_key_reused. See idempotency.

  3. Stop after three tries

    If it still isn't clear, stop and hand the action to a person with the reasons attached.

// The retry-with-fix loop: at most three checks, a new Idempotency-Key each time.
async function checkAndAct(draft: Draft, revise: (d: Draft, fixes: Fix[]) => Promise<Draft | null>) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    const check = await preflight(toFacts(draft));            // POST /v1/preflight
    if (check.decision === 'clear') return send(draft, check.receipt_id);
    if (check.decision === 'hold') return waitForPerson(check.hold.status_url);
    const next = await revise(draft, check.fixes);           // your agent rewrites, re-times or adds known facts
    if (next === null) return askPerson(check);               // no safe revision: a person decides
    draft = next;
  }
  return askPerson();                                         // still not clear: stop and escalate
}
# The retry-with-fix loop: at most three checks, a new Idempotency-Key each time.
def check_and_act(draft):
    for attempt in range(3):
        result = preflight(to_facts(draft))  # POST /v1/preflight
        if result["decision"] == "clear":
            return send(draft, result["receipt_id"])
        if result["decision"] == "hold":
            return wait_for_person(result["hold"]["status_url"])
        draft = revise(draft, result["fixes"])  # rewrite, re-time or add known facts
        if draft is None:
            return ask_person(result)  # no safe revision: a person decides
    return ask_person(None)  # still not clear: stop and escalate

Never invent facts to get a clear. Every check is signed. A receipt that shows consent your business never had is evidence against you, not for you.

Example: a thin request

A text with only a phone number can't be checked fully. Cerata flags it and lists what it needs. Without a postal address it can only place the recipient in the US, so state rules can't be applied and the answer includes out_of_coverage.

{
  "action": {
    "type": "outbound_text",
    "purpose": "telemarketing",
    "at": "2026-10-21T10:05:00-04:00"
  },
  "sender": {
    "name": "Gulf Coast Motors"
  },
  "recipient": {
    "phone": "+18135550190"
  },
  "content": {
    "text": "Hi Maria, want me to book you a test drive this weekend?"
  }
}
{
  "check_id": "chk_1b3d5f7a9c2e4a6b8d0f1e3c5a7b9d2f",
  "receipt_id": "chk_1b3d5f7a9c2e4a6b8d0f1e3c5a7b9d2f",
  "env": "test",
  "decision": "flag",
  "risk_level": "medium",
  "jurisdictions": [
    "US"
  ],
  "rules": [
    {
      "id": "us.tcpa.consent-automated",
      "version": "1.0.0",
      "result": "indeterminate",
      "reasons": [
        "missing_fact"
      ]
    },
    {
      "id": "us.tcpa.dnc",
      "version": "1.0.0",
      "result": "indeterminate",
      "reasons": [
        "missing_fact"
      ]
    }
  ],
  "reasons": [
    "missing_fact",
    "out_of_coverage"
  ],
  "fixes": [
    {
      "code": "missing_fact",
      "text": "Provide action.artificial_voice"
    },
    {
      "code": "missing_fact",
      "text": "Provide action.automated"
    },
    {
      "code": "missing_fact",
      "text": "Provide recipient.consent.type"
    },
    {
      "code": "missing_fact",
      "text": "Provide recipient.dnc_registered"
    }
  ],
  "receipt": "eyJhbGciOiJFZERTQSIs…"
}

Sending the recipient's address, consent type and do-not-call status turns the same text into a clear, as in the API reference example.

Risk level

Every decided check carries risk_level: low, medium or high. Use it to route flags: a low or medium flag can go back to your agent to fix; a high flag is a good point to involve a person. Your review settings in the dashboard decide which uncertain checks hold for a person and which come back as flags.