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.
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
| Field | Required | Notes |
|---|---|---|
mode | No | "reminders" (default) — the in-progress follow-up cascade. It's the only run type today; more (final-submission, re-activation) will be added here. |
preview | No | true 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). |
auditCode | No | Scope 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. |
demoBypassCallingWindow | No | Texts 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
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
| Field | Notes |
|---|---|
mode | The run type that was executed (echoes the request). |
advanced | The audits AuditCake acted on — each with the steps it sent (the due reminder channels for that audit). |
skipped | The audits it left alone, each with a reason (below). |
Why an audit is skipped
| Reason | Meaning |
|---|---|
automation_off | Automated outreach isn't enabled for that audit — AuditCake never contacts an audit you haven't opted in. |
not_yet_due | Nothing 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.
| Event | Channel | Recipient | Sent when |
|---|---|---|---|
kickoff_email | Insured | The first-touch welcome email to the insured (the audit's first contact). | |
kickoff_text | Text | Insured | The first-touch welcome text to the insured. |
agent_kickoff_email | Agent | The first-touch kickoff email to the agent of record. | |
reminder_email | Insured | A due email reminder goes to the insured. | |
reminder_text | Text | Insured | A due text reminder goes to the insured. |
reminder_call | Call | Insured | An automated voice call is placed to the insured. |
agent_email | Agent | A reminder email goes to the agent of record. | |
agent_call | Call | Agent | An 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"
}| Field | Notes |
|---|---|
event | One of the event types in the table above. |
jobId | The scheduler run this event belongs to. |
auditCode | The audit the outreach was for. |
recipient | insured or agent. |
channel | email, text, or call. |
sentAt | ISO-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
| Status | Meaning |
|---|---|
400 | Unknown mode, or the webhookUrl isn't a valid http(s) URL. |
401 | The x-api-key header is missing or not recognized. |
404 | No job with that id falls within the calling key's scope (on poll). |
500 | An unexpected error on AuditCake's side. Safe to retry. |