Developer docs: Calls

Calls

Call history, details, transcripts, recordings and outbound calls.

List calls (no transcripts)Link to List calls (no transcripts)

GET/calls-history

Newest first by default. Filter by direction, status, agent, scenario, creation date or updatedSince.

Scope: calls:read

Query parameters

pagenumber: Default: 1
limitnumber: Default: 20 · Max 100
updatedSincestring: ISO 8601: only records changed at or after this instant. With sort=updatedAt&order=asc this is an incremental sync cursor
orderstring: One of: asc, desc · Default: desc
sortstring: One of: createdAt, updatedAt, startTime · Default: createdAt
directionstring: One of: inbound, outbound
callTypestring: One of: inbound, outbound
statusstring: One of: initiated, ringing, connected, listening, responding, transferring, callback_scheduled, ended, failed, completed, queued, in-progress, busy, canceled, no-answer
agentIdstring
scenariostring
startDatestring
endDatestring

curl "https://bookifycall.com/api/v1/external/calls-history" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "organizationId": "00000000-0000-4000-8000-000000000100",
      "agentId": "00000000-0000-4000-8000-000000000002",
      "callSid": "CA00000000000000000000000000000000",
      "callType": "inbound",
      "callStatus": "completed",
      "fromNumber": "+15551230001",
      "toNumber": "+15551230002",
      "scenario": "inbound_general",
      "duration": 250,
      "startTime": "2026-01-15T16:30:00.000Z",
      "endTime": "2026-01-15T16:34:10.000Z",
      "topics": [
        "pricing"
      ],
      "endReason": "caller_hangup",
      "callerInfo": {
        "name": "Jane Doe",
        "company": "Example Dental",
        "email": "jane@example.com",
        "callbackNumber": "+15551230001"
      },
      "promptId": "agent:00000000-0000-4000-8000-000000000002:inbound",
      "promptVersion": "3f9a1c0e",
      "aiProvider": "openai",
      "aiModel": "gpt-realtime",
      "voiceMode": "openai_native",
      "createdAt": "2026-01-15T16:30:00.000Z",
      "updatedAt": "2026-01-15T16:34:10.000Z",
      "agent": {
        "id": "00000000-0000-4000-8000-000000000002",
        "name": "Riley"
      },
      "summary": {
        "summary": "Caller asked about pricing and booked a demo for Tuesday.",
        "callOutcome": "appointment_booked",
        "intent": {
          "label": "book_demo",
          "description": "Wants a product demo"
        },
        "sentiment": {
          "label": "positive"
        },
        "satisfactionScore": 4,
        "keyPoints": [
          "Team of 12",
          "Wants a demo"
        ],
        "followUp": {
          "needed": true,
          "suggestedAction": "Send pricing sheet",
          "dueHint": "before the demo"
        },
        "leadId": "00000000-0000-4000-8000-000000000003",
        "analysis": {
          "analyzedAt": "2026-01-15T16:34:30.000Z"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 37,
    "pages": 2
  }
}

Call detail: transcript, AI analysis, lead, booked appointmentLink to Call detail: transcript, AI analysis, lead, booked appointment

GET/calls-history/{id}

Scope: calls:read
Not found: 404 CALL_002

Path parameters

idstringrequired

curl "https://bookifycall.com/api/v1/external/calls-history/00000000-0000-4000-8000-000000000001" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "agentId": "00000000-0000-4000-8000-000000000002",
    "callSid": "CA00000000000000000000000000000000",
    "callType": "inbound",
    "callStatus": "completed",
    "fromNumber": "+15551230001",
    "toNumber": "+15551230002",
    "scenario": "inbound_general",
    "duration": 250,
    "startTime": "2026-01-15T16:30:00.000Z",
    "endTime": "2026-01-15T16:34:10.000Z",
    "summary": {
      "summary": "Caller asked about pricing and booked a demo for Tuesday.",
      "callOutcome": "appointment_booked",
      "intent": {
        "label": "book_demo",
        "description": "Wants a product demo"
      },
      "sentiment": {
        "label": "positive"
      },
      "satisfactionScore": 4,
      "keyPoints": [
        "Team of 12",
        "Wants a demo"
      ],
      "followUp": {
        "needed": true,
        "suggestedAction": "Send pricing sheet",
        "dueHint": "before the demo"
      },
      "leadId": "00000000-0000-4000-8000-000000000003",
      "analysis": {
        "analyzedAt": "2026-01-15T16:34:30.000Z"
      }
    },
    "topics": [
      "pricing"
    ],
    "endReason": "caller_hangup",
    "callerInfo": {
      "name": "Jane Doe",
      "company": "Example Dental",
      "email": "jane@example.com",
      "callbackNumber": "+15551230001"
    },
    "promptId": "agent:00000000-0000-4000-8000-000000000002:inbound",
    "promptVersion": "3f9a1c0e",
    "aiProvider": "openai",
    "aiModel": "gpt-realtime",
    "voiceMode": "openai_native",
    "createdAt": "2026-01-15T16:30:00.000Z",
    "updatedAt": "2026-01-15T16:34:10.000Z",
    "agent": {
      "id": "00000000-0000-4000-8000-000000000002",
      "name": "Riley"
    },
    "lead": {
      "id": "00000000-0000-4000-8000-000000000003",
      "organizationId": "00000000-0000-4000-8000-000000000100",
      "callId": "00000000-0000-4000-8000-000000000001",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+15551230001",
      "company": "Example Dental",
      "industry": "dental",
      "status": "qualified",
      "source": "call",
      "challenges": "Missed calls after hours",
      "interests": "Online booking",
      "preferences": {},
      "score": 72,
      "temperature": "hot",
      "bant": {
        "budget": "Approved",
        "authority": "Owner",
        "need": "After-hours answering",
        "timeline": "This month"
      },
      "lastContactedAt": "2026-01-15T16:34:10.000Z",
      "nextFollowUpAt": null,
      "createdAt": "2026-01-15T16:34:10.000Z",
      "updatedAt": "2026-01-15T16:34:10.000Z"
    },
    "hasRecording": true,
    "analysis": {
      "ready": true,
      "summary": "Caller asked about pricing and booked a demo for Tuesday.",
      "outcome": "appointment_booked",
      "intent": "book_demo",
      "intentDescription": "Wants a product demo",
      "sentiment": "positive",
      "satisfactionScore": 4,
      "topics": [
        "pricing"
      ],
      "keyPoints": [
        "Team of 12",
        "Wants a demo"
      ],
      "followUp": {
        "needed": true,
        "suggestedAction": "Send pricing sheet",
        "dueHint": "before the demo"
      },
      "caller": {
        "name": "Jane Doe",
        "company": "Example Dental",
        "email": "jane@example.com",
        "callbackNumber": "+15551230001"
      },
      "leadId": "00000000-0000-4000-8000-000000000003",
      "analyzedAt": "2026-01-15T16:34:30.000Z"
    },
    "appointmentId": "00000000-0000-4000-8000-000000000004",
    "transcript": [
      {
        "timestamp": "2026-01-15T16:30:00.000Z",
        "speaker": "agent",
        "message": "Thanks for calling Example Dental, how can I help?"
      },
      {
        "timestamp": "2026-01-15T16:30:05.000Z",
        "speaker": "user",
        "message": "I would like to book a demo."
      }
    ]
  }
}

Transcript and prompt provenanceLink to Transcript and prompt provenance

GET/calls-history/{id}/transcript

Scope: calls:read
Not found: 404 CALL_002

Path parameters

idstringrequired

curl "https://bookifycall.com/api/v1/external/calls-history/00000000-0000-4000-8000-000000000001/transcript" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "callSid": "CA00000000000000000000000000000000",
    "startTime": "2026-01-15T16:30:00.000Z",
    "endTime": "2026-01-15T16:34:10.000Z",
    "duration": 250,
    "transcript": [
      {
        "timestamp": "2026-01-15T16:30:00.000Z",
        "speaker": "agent",
        "message": "Thanks for calling Example Dental, how can I help?"
      },
      {
        "timestamp": "2026-01-15T16:30:05.000Z",
        "speaker": "user",
        "message": "I would like to book a demo."
      }
    ],
    "aiProvenance": {
      "promptId": "agent:00000000-0000-4000-8000-000000000002:inbound",
      "promptVersion": "3f9a1c0e",
      "provider": "openai",
      "model": "gpt-realtime",
      "voiceMode": "openai_native"
    }
  }
}

Short-lived signed URL to the call audioLink to Short-lived signed URL to the call audio

GET/calls-history/{id}/recording

The URL is valid for up to an hour: download the audio, never store the link.

Scope: recordings:read
Not found: 404 REC_001

Path parameters

idstringrequired

curl "https://bookifycall.com/api/v1/external/calls-history/00000000-0000-4000-8000-000000000001/recording" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "url": "https://recordings.example.com/calls/example.mp3?X-Amz-Expires=3600&X-Amz-Signature=example",
    "source": "s3",
    "expiresInSeconds": 3600,
    "duration": 250,
    "format": "mp3"
  }
}

Place an outbound callLink to Place an outbound call

POST/calls/outbound

Scope: calls:write
Idempotency-Key: supported

Body (JSON)

agentIdstring: Required unless the key is bound to an agent
aiAgentIdstring: Live alias of agentId
phoneNumberstring
toNumberstring: Alias of phoneNumber
namestring
emailstring
companystring
callIntentstring
scenariostring
notesstring
leadContextobject
providerstring: One of: openai, elevenlabs, deepgram

curl -X POST "https://bookifycall.com/api/v1/external/calls/outbound" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"00000000-0000-4000-8000-000000000002","phoneNumber":"+15551230001","name":"Jane Doe","company":"Example Dental","callIntent":"Confirm Thursday appointment","notes":"Prefers mornings"}'

Example response · 200

{
  "success": true,
  "message": "Outbound call initiated",
  "data": {
    "callId": "00000000-0000-4000-8000-000000000001",
    "callSid": "CA00000000000000000000000000000000",
    "to": "+15551230001"
  }
}

Next: Scheduled calls