AuditCakeDevelopersBook a walkthrough

AI Scheduler

Kick off AuditCake's automated follow-up across your active audits — the same scheduled outreach AuditCake runs on its own cadence, on demand. AuditCake walks the audits that are open and being worked, decides each one's next due step (a reminder email, text, or call to the insured or agent), sends the ones that are due, and returns a summary of which audits it advanced and which it skipped.

POSThttps://auditcake.com/api/v1/ai/scheduler

The run is scoped to your carrier automatically — there is nothing to identify in the body. AuditCake considers the audits you've created that are still in progress (see Create an audit) and acts only on those with automated outreach enabled.

Request

FieldRequiredNotes
modeNo"reminders" (default) — the in-progress follow-up cascade. It's the only run type today; more (final-submission, re-activation) will be added here.
previewNotrue runs in preview mode: AuditCake decides every due step and renders the exact email/text/call it would send, but sends nothing. The result is returned here and saved as a regenerable preview you can review first — kept separate from the audit's activity history (which records only what actually happened), and it never affects the schedule, so a real run afterward still sends. Default false (a real run sends).
auditCodeNoScope the run to a single audit instead of the whole book — decide and (unless preview) send only that audit's due steps. Omit to run across every active, opted-in audit the key can see.
demoBypassCallingWindowNoTexts and calls are held to a calling window — weekdays 11:30 AM–7:00 PM Eastern; email is exempt. Outside it, a due text/call is skipped (and does not count as sent) until an in-window run. true lets a run place those off-hours — but only for demo audits (an audit flagged for testing, whose contacts are your own coordinates). On a real audit the flag is ignored and the window still holds, so it can never reach a real recipient outside quiet hours. Default false.
curl -X POST https://auditcake.com/api/v1/ai/scheduler \
  -H "x-api-key: ack_live_<api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "reminders",
    "webhookUrl": "https://example.com/hooks/scheduler"
  }'

The run completes right away and a job id comes back with the summary (202). The per-audit detail is in the job result — returned on the webhook (if you passed one) and always pollable at the pollUrl:

{
  "jobId": "aij_5c1a0f8e2b7d4419a3e6c012",
  "status": "completed",
  "pollUrl": "/api/v1/ai/scheduler/aij_5c1a0f8e2b7d4419a3e6c012",
  "summary": { "considered": 12, "advanced": 3, "skipped": 9 }
}

summary is an at-a-glance count: how many active audits were considered, how many AuditCake advanced (sent a due step on), and how many it skipped.

Getting the result

Webhook (recommended)

If you passed a webhookUrl, AuditCake POSTs the completed result there as { jobId, status: "completed", result } — no polling needed.

Polling

GEThttps://auditcake.com/api/v1/ai/scheduler/:jobId
curl https://auditcake.com/api/v1/ai/scheduler/aij_5c1a0f8e2b7d4419a3e6c012 \
  -H "x-api-key: ack_live_<api-key>"

While the run is in flight, status is queued. When it finishes:

{
  "jobId": "aij_5c1a0f8e2b7d4419a3e6c012",
  "status": "completed",
  "result": {
    "mode": "reminders",
    "advanced": [
      { "auditCode": "K7M4PQ", "steps": ["reminder_email", "reminder_text"] },
      { "auditCode": "B2N8WL", "steps": ["agent_call"] }
    ],
    "skipped": [
      { "auditCode": "R3X9TQ", "reason": "automation_off" },
      { "auditCode": "T6P1ZD", "reason": "not_yet_due" }
    ]
  }
}

Result fields

FieldNotes
modeThe run type that was executed (echoes the request).
advancedThe audits AuditCake acted on — each with the steps it sent (the due reminder channels for that audit).
skippedThe audits it left alone, each with a reason (below).

Why an audit is skipped

ReasonMeaning
automation_offAutomated outreach isn't enabled for that audit — AuditCake never contacts an audit you haven't opted in.
not_yet_dueNothing is due — the audit was recently contacted (so calling again right away won't re-send) or hasn't reached its next cadence step.

AuditCake also skips weekends, holidays, and outside-hours automatically, and won't contact anyone who has opted out — so a run is always safe to call.

Scheduler events

AuditCake advances an audit by sending one or more outreach events. These are the event types the scheduler emits — the names that show up in a run's steps and in the real-time webhook below.

EventChannelRecipientSent when
kickoff_emailEmailInsuredThe first-touch welcome email to the insured (the audit's first contact).
kickoff_textTextInsuredThe first-touch welcome text to the insured.
agent_kickoff_emailEmailAgentThe first-touch kickoff email to the agent of record.
reminder_emailEmailInsuredA due email reminder goes to the insured.
reminder_textTextInsuredA due text reminder goes to the insured.
reminder_callCallInsuredAn automated voice call is placed to the insured.
agent_emailEmailAgentA reminder email goes to the agent of record.
agent_callCallAgentAn automated voice call is placed to the agent of record.

An audit's very first run sends the kickoff_* welcome events; every run after that sends the reminder_* cascade.

Real-time events

The webhookUrl on a run delivers one summary when that run finishes. To hear about each outreach as it happens — and about everything else an audit does — register a standing webhook once (see Webhook delivery). It is a single subscription that receives every kind of update AuditCake emits, each tagged by event: the scheduler's outreach events below, alongside audit-lifecycle events such as audit.completed. Register the URL in your Automation settings; once it is set, AuditCake POSTs one payload per outreach event, in addition to the per-run completion summary.

Each scheduler event arrives in the same signed envelope as every subscription delivery (an HMAC X-AuditCake-Signature header, a 2xx ack, retried with backoff — the delivery contract is on Webhook delivery). Payload fields vary by category; for the outreach events:

{
  "event": "reminder_email",
  "jobId": "aij_5c1a0f8e2b7d4419a3e6c012",
  "auditCode": "K7M4PQ",
  "recipient": "insured",
  "channel": "email",
  "sentAt": "2026-06-06T14:32:08Z"
}
FieldNotes
eventOne of the event types in the table above.
jobIdThe scheduler run this event belongs to.
auditCodeThe audit the outreach was for.
recipientinsured or agent.
channelemail, text, or call.
sentAtISO-8601 UTC timestamp of the send.

One POST per event — an example of each:

{ "event": "reminder_email", "jobId": "aij_5c1a0f8e2b7d4419a3e6c012", "auditCode": "K7M4PQ", "recipient": "insured", "channel": "email", "sentAt": "2026-06-06T14:32:08Z" }
{ "event": "reminder_text",  "jobId": "aij_5c1a0f8e2b7d4419a3e6c012", "auditCode": "K7M4PQ", "recipient": "insured", "channel": "text",  "sentAt": "2026-06-06T14:32:09Z" }
{ "event": "reminder_call",  "jobId": "aij_5c1a0f8e2b7d4419a3e6c012", "auditCode": "B2N8WL", "recipient": "insured", "channel": "call",  "sentAt": "2026-06-06T14:32:11Z" }
{ "event": "agent_email",    "jobId": "aij_5c1a0f8e2b7d4419a3e6c012", "auditCode": "R3X9TQ", "recipient": "agent",   "channel": "email", "sentAt": "2026-06-06T14:32:12Z" }
{ "event": "agent_call",     "jobId": "aij_5c1a0f8e2b7d4419a3e6c012", "auditCode": "T6P1ZD", "recipient": "agent",   "channel": "call",  "sentAt": "2026-06-06T14:32:14Z" }

Audit-lifecycle events — an auditor completes an audit, a status changes — arrive on this same subscription, tagged with an audit.* event. Their envelope and the full list are on Webhook delivery.

Where the reminder emails come from

By default, the emails this run sends go out from an AuditCake-managed address on your behalf — nothing to configure. If you'd rather they come from your own domain, so the insured and agent see audits@yourcompany.com as the sender, AuditCake can send under a domain you control.

Sending from your own domain is a one-time setup. You authenticate the domain for email, then add a small set of DNS records — CNAMEs for DKIM and a return path — at your DNS host. Once they resolve, the whole domain is authenticated and every address on it (audits, replies, help) can send without any per-address verification.

Type   Host                            Value
CNAME  s1._domainkey.yourcompany.com   s1.dkim.<provided-by-auditcake>
CNAME  s2._domainkey.yourcompany.com   s2.dkim.<provided-by-auditcake>
CNAME  em.yourcompany.com              return.<provided-by-auditcake>

The hosts above are illustrative — to set this up, tell AuditCake the domain and from-address you'd like to use and we'll send back the exact records (and their target values) for your domain.

Error responses

StatusMeaning
400Unknown mode, or the webhookUrl isn't a valid http(s) URL.
401The x-api-key header is missing or not recognized.
404No job with that id falls within the calling key's scope (on poll).
500An unexpected error on AuditCake's side. Safe to retry.