AuditCakeDevelopersBook a walkthrough

AI Voice Call

Have AuditCake's AI agent place a call about one of your audits — the same outbound audit call AuditCake makes in its workflow, on demand. You reference an audit and choose which party to reach; AuditCake dials the contact already on that audit (a transactional call) and returns the outcome and a transcript.

POSThttps://auditcake.com/api/v1/ai/voice-call

You don't pass a phone number. AuditCake dials the contact on file for the audit — so the number, the names, and the audit details spoken on the call all come from the audit you reference (see Create an audit).

Request

FieldRequiredNotes
auditCodeYesThe audit to call about — its auditCode or your own carrierControlId.
contactNo"insured" (default — the audit's working contact) or "agent" (the agent of record). AuditCake resolves that party's phone.
webhookUrlNoAn https URL AuditCake POSTs the outcome to when the call completes. If omitted, poll instead.
demoBypassCallingWindowNoCalls are placed only inside the calling window — weekdays 11:30 AM–7:00 PM Eastern; outside it the request returns 429. true lets a call go off-hours — but only for demo audits (an audit flagged for testing, whose contact is your own number). On a real audit the flag is ignored and the 429 still applies. Default false.
curl -X POST https://auditcake.com/api/v1/ai/voice-call \
  -H "x-api-key: ack_live_<api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "auditCode": "K7M4PQ",
    "contact": "insured",
    "webhookUrl": "https://example.com/hooks/voice"
  }'

The call is queued and a job id comes back right away (202):

{
  "jobId": "aij_9f2c…",
  "status": "queued",
  "pollUrl": "/api/v1/ai/voice-call/aij_9f2c…",
  "contact": "insured"
}

Getting the outcome

If you passed a webhookUrl, AuditCake POSTs the completed result there. Otherwise poll:

GEThttps://auditcake.com/api/v1/ai/voice-call/:jobId
{
  "jobId": "aij_9f2c…",
  "status": "completed",
  "result": {
    "status": "completed",
    "durationSeconds": 84,
    "transcript": "Full call transcript…",
    "summary": "Insured will upload the documents.",
    "actions": [
      { "type": "send_email_link", "data": { "email_address": "…" } }
    ]
  }
}

result.status is one of completed, no_answer, voicemail, or failed.actions are the structured outcomes the agent reported (e.g. the insured asked for the link by email). The call transcript is returned; call recordings are not exposed in this version.

Calling rules

These are enforced for you — a request that can't be placed returns an error rather than dialing:

StatusMeaning
400Bad contact role, missing auditCode, or an invalid webhookUrl.
401The x-api-key header is missing or not recognized.
404No audit with that id falls within the calling key's scope.
409That contact has opted out of calls — AuditCake will not dial them.
422No phone number on file for the requested contact.
429Outside the permitted calling window (11:30 AM–7:00 PM Eastern, Mon–Fri).