1. Cerata
  2. Docs
  3. Quickstart

Quickstart: your first legal check in five minutes

Get a key, send one action to the preflight API, and teach your agent what to do with each of the four answers. Every example below is complete: set your key and run it.

1. Get an API key

Contact us for a key to the test API. The full key is shown once, so copy it straight into your secrets manager or environment.

Shell
export CERATA_API_KEY="ak_test_…"

Keys look like ak_<environment>_<id>_<secret>. Each key belongs to one environment, test or live, and checks, holds and review settings are kept apart per environment. Never put a key in client-side code.

2. Make your first check

This asks whether a sales call to a Tampa number at 8:15 p.m. local time is allowed. Send the facts you know about the action. The more you send, the more Cerata can check.

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_call",
    "purpose": "telemarketing",
    "at": "2026-10-20T20:15:00-04:00",
    "automated": false
  },
  "sender": {
    "name": "Gulf Coast Motors"
  },
  "recipient": {
    "phone": "+18135550142",
    "address": {
      "line1": "601 E Kennedy Blvd",
      "city": "Tampa",
      "state": "FL",
      "zip": "33602"
    },
    "consent": {
      "type": "prior_express_written"
    },
    "dnc_registered": false,
    "prior_calls_24h": 0
  }
}'
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_call",
      "purpose": "telemarketing",
      "at": "2026-10-20T20:15:00-04:00",
      "automated": false
    },
    "sender": {
      "name": "Gulf Coast Motors"
    },
    "recipient": {
      "phone": "+18135550142",
      "address": {
        "line1": "601 E Kennedy Blvd",
        "city": "Tampa",
        "state": "FL",
        "zip": "33602"
      },
      "consent": {
        "type": "prior_express_written"
      },
      "dnc_registered": false,
      "prior_calls_24h": 0
    }
  }),
});

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_call",
        "purpose": "telemarketing",
        "at": "2026-10-20T20:15:00-04:00",
        "automated": False
    },
    "sender": {
        "name": "Gulf Coast Motors"
    },
    "recipient": {
        "phone": "+18135550142",
        "address": {
            "line1": "601 E Kennedy Blvd",
            "city": "Tampa",
            "state": "FL",
            "zip": "33602"
        },
        "consent": {
            "type": "prior_express_written"
        },
        "dnc_registered": False,
        "prior_calls_24h": 0
    }
}

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"))

The answer comes back in the same request. Here it is a block: Florida limits sales calls to 8 a.m. to 8 p.m. in the called person's time zone, which is stricter than the federal 9 p.m. limit under the TCPA.

Response · 200 OK
{
  "check_id": "chk_3f9a1c7e5b2d4a6f8e0c1b3d5a7f9e2c",
  "receipt_id": "chk_3f9a1c7e5b2d4a6f8e0c1b3d5a7f9e2c",
  "env": "test",
  "decision": "block",
  "risk_level": "medium",
  "jurisdictions": [
    "US",
    "US-FL"
  ],
  "rules": [
    {
      "id": "us-fl.telemarketing.hours",
      "version": "1.0.0",
      "result": "fired",
      "reasons": [
        "us-fl.telemarketing.hours"
      ]
    },
    {
      "id": "us.tcpa.calling-hours",
      "version": "1.0.0",
      "result": "passed",
      "reasons": []
    },
    {
      "id": "us.tcpa.dnc",
      "version": "1.0.0",
      "result": "passed",
      "reasons": []
    }
  ],
  "reasons": [
    "us-fl.telemarketing.hours"
  ],
  "fixes": [
    {
      "code": "us-fl.telemarketing.hours",
      "text": "Call between 08:00 and 20:00 in every recipient local time zone."
    }
  ],
  "decision_digest": "sha256:208488aa1e61022f1d40e22f29787a28b4540131d08f6fc7ddeb3f37ad4b7d0b",
  "receipt": "eyJhbGciOiJFZERTQSIs…"
}

The rules list is trimmed here. A real response lists every rule that applied. receipt is a signed record of this check; see receipts.

3. Handle the four decisions

Your agent only acts on clear. Everything else comes with reasons and, usually, fixes. Read decisions and fixes for the full loop.

  • Clear Go ahead. Keep the receipt_id with the action.
  • Flag Don't send it as is. Apply the fixes and check again, or ask a person.
  • Hold Wait. The response status is 202 and a person decides. Poll the hold.
  • Block Don't send it. Apply the fix, then check again.
// After every check: act only on clear.
switch (check.decision) {
  case 'clear':
    await placeCall(lead);                    // go ahead; keep check.receipt_id with the call
    break;
  case 'flag':
  case 'block':
    // Don't send it. Show the reasons and apply check.fixes, then check again.
    return { retry: true, fixes: check.fixes, reasons: check.reasons };
  case 'hold':
    // A person decides. Poll the hold until its decision is no longer 'hold'.
    return { waitFor: `https://clearance-kohl.vercel.app${check.hold.status_url}` };
}
# After every check: act only on clear.
decision = result["decision"]
if decision == "clear":
    place_call(lead)  # go ahead; keep result["receipt_id"] with the call
elif decision in ("flag", "block"):
    # Don't send it. Show the reasons and apply the fixes, then check again.
    revise(lead, result["fixes"], result["reasons"])
elif decision == "hold":
    # A person decides. Poll the hold until its decision is no longer "hold".
    wait_for(f"https://clearance-kohl.vercel.app{result['hold']['status_url']}")

Fail closed. If the check returns an error, a 503 or times out, treat it as “don't act”. Never fall back to sending without a check.

4. Or paste this into your AI coding assistant

Working in Claude Code, Cursor or a similar tool? Paste this prompt and let the assistant wire the check in. It is scoped to the actions Cerata checks today, plus job posts, where the New York City rule is being verified.

Prompt
Add a legal check with Cerata before my agent takes any of these actions: a sales call, a sales text, a marketing email, a rental listing or a job post.

Call POST https://clearance-kohl.vercel.app/v1/preflight with my CERATA_API_KEY as a Bearer token and a new Idempotency-Key for each check. The request and response are documented at https://cerata.ai/docs/api-reference.

Send only facts the app actually knows: the action type, the time with its UTC offset, the purpose (for a sales or marketing call or text, send action.purpose exactly "telemarketing", lowercase; any other value is flagged, never cleared), the sender's name, the recipient's phone or email and postal address, consent and do-not-call status if we store them, and the message text. Never guess a fact to get a better answer.

Only act when the decision is "clear". On "flag" or "block", don't send: show me the reasons, apply the returned fixes and check again, at most three times. On "hold", don't send yet: poll the hold's status_url until a person decides, then follow that decision. If the check errors or times out, don't act.

Store the receipt_id with every action the agent takes.

Using the TypeScript SDK

The TypeScript SDK is in private preview; ask us for access. Everything it does is a plain HTTPS call, so the HTTP examples work today from any language.

TypeScript
import { createClient } from '@cerata/sdk';

const cerata = createClient({
  apiKey: process.env.CERATA_API_KEY!,
  baseUrl: 'https://clearance-kohl.vercel.app',
});

const check = await cerata.preflight({
  "action": {
    "type": "outbound_call",
    "purpose": "telemarketing",
    "at": "2026-10-20T20:15:00-04:00",
    "automated": false
  },
  "sender": {
    "name": "Gulf Coast Motors"
  },
  "recipient": {
    "phone": "+18135550142",
    "address": {
      "line1": "601 E Kennedy Blvd",
      "city": "Tampa",
      "state": "FL",
      "zip": "33602"
    },
    "consent": {
      "type": "prior_express_written"
    },
    "dnc_registered": false,
    "prior_calls_24h": 0
  }
});

console.log(check.decision, check.fixes);

The SDK throws on any non-2xx answer, so wrap the call and treat an exception as “don't act”.

Next steps