openapi: 3.1.0 info: title: CallView API version: v1 description: "Send leads to CallView, get called back with what happened. The AI calls each lead, and a person on your team takes the interested ones. Guide: https://developers.callview.ai" contact: name: CallView support email: support@callview.ai url: https://developers.callview.ai servers: - url: https://v2-api.callview.ai/api/v1/external description: CallView V2 tags: - name: Leads description: Add leads to a campaign (speed to lead), look them up, change them, opt them out. - name: Calls description: Calls, their outcomes, recordings and transcripts. Call a lead now. - name: Campaigns description: Your campaigns. Start and pause them. - name: DNC description: Your organization's Do Not Call list. - name: Events description: Every event we sent, or would have sent, for the last 30 days. - name: Webhooks description: Where we send events, and how each delivery went. - name: Usage description: Requests, leads, calls, minutes and cost for a month. - name: Exports description: Download your leads and calls as a file. security: - BasicAuth: [] - BearerAuth: [] components: securitySchemes: BasicAuth: type: http scheme: basic description: Your key ID (ck_live_... or ck_test_...) as the username and the secret (cs_live_... or cs_test_...) as the password. BearerAuth: type: http scheme: bearer description: The secret alone (cs_live_... or cs_test_...) as a Bearer token. parameters: IdempotencyKey: in: header name: Idempotency-Key required: false description: Any string you choose (1 to 255 visible characters), new for each new action. Send the same key again within 24 hours and you get the first answer back instead of a second lead or call. schema: type: string minLength: 1 maxLength: 255 example: crm-10442-create headers: Request-Id: description: The ID of this request (req_...). Quote it when you contact us. schema: type: string RateLimit-Limit: description: Requests allowed a minute. schema: type: integer RateLimit-Remaining: description: Requests left this minute. schema: type: integer RateLimit-Reset: description: Seconds until the minute resets. schema: type: integer Retry-After: description: Seconds to wait before trying again. schema: type: integer Idempotent-Replayed: description: true when this is the kept answer to an earlier request with the same Idempotency-Key. schema: type: string schemas: PublicError: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - idempotency_error - api_error code: type: string enum: - invalid_request - invalid_phone - on_dnc_list - outside_calling_hours - duplicate_lead - number_retired - consent_required - campaign_closed - queue_full - test_flows_busy - phone_cannot_change - ambiguous_external_id - duplicate_dnc_entry - not_found - authentication_failed - permission_denied - rate_limited - too_many_concurrent_requests - lead_rate_limited - idempotency_mismatch - idempotency_in_progress - limit_reached - endpoint_paused - service_unavailable - internal_error - lead_busy - lead_taken_out_of_queue - call_limit_reached - number_not_allowed - recording_not_available description: A stable word. Branch on this, never on the message. message: type: string description: For people. Phone numbers and emails in it are masked. param: type: - string - "null" description: The field the error is about, when there is one. request_id: type: - string - "null" description: The same as the Request-Id header. Quote it when you contact us. reason: type: string description: The specific cause when the code is a broader word (for example why authentication failed). lead_id: type: - string - "null" format: uuid description: "duplicate_lead only: the lead that already exists." missing_permission: type: string description: 'permission_denied only: the permission the key is missing, for example "calls:read".' campaign_id: type: - string - "null" format: uuid description: "permission_denied only: the campaign outside the key's scope (null when the endpoint needs a key for every campaign)." candidates: type: array description: "ambiguous_external_id only: the leads that match, so you can add campaign_id." items: type: object properties: id: type: string format: uuid campaign_id: type: string format: uuid required: - id - campaign_id required: - type - code - message - param - request_id required: - error ListMeta: type: object properties: next_cursor: type: - string - "null" description: Pass this as starting_after (or cursor) to get the next page. null on the last page. has_more: type: boolean required: - next_cursor - has_more examples: - next_cursor: null has_more: false Deleted: type: object properties: id: type: string object: type: string deleted: type: boolean const: true livemode: type: boolean description: "false for a test key: sample data, never real." required: - deleted Consent: type: object properties: source: type: string maxLength: 100 description: Where the lead agreed, for example web_form, crm or purchased_list. agreed_at: type: string format: date-time description: When the lead agreed. text: type: string maxLength: 5000 description: The words the lead agreed to. Send text or url. url: type: string format: uri description: The page the lead agreed on. Send text or url. ip: type: string description: The lead's IP address when agreeing, if you have it. required: - source - agreed_at LeadCallSummary: type: object properties: id: type: string format: uuid started: type: string format: date-time outcome: type: - string - "null" enum: - interested - not_interested - callback - voicemail - no_answer - busy - failed - dnc - wrong_number - hung_up - screened - language_barrier - not_qualified - undetermined - other - null description: A stable outcome word (see the Outcomes guide). null while there is no outcome yet. outcome_label: type: - string - "null" duration_seconds: type: - integer - "null" required: - id - started - outcome - outcome_label - duration_seconds Lead: type: object properties: id: type: string format: uuid external_id: type: - string - "null" description: Your own ID for the lead. campaign_id: type: string format: uuid name: type: - string - "null" phone: type: string description: +1 and 10 digits. email: type: - string - "null" address: type: - string - "null" fields: type: object additionalProperties: type: string description: Your custom fields. consent: oneOf: - $ref: "#/components/schemas/Consent" - type: "null" lead_source: type: - string - "null" owner: type: - object - "null" properties: id: type: string name: type: string required: - id - name description: The SDR the latest call was dialed for, or null. created: type: string format: date-time updated: type: string format: date-time status: type: string enum: - new - queued - scheduled - held - dialing - on_call - callback_scheduled - done - out_of_queue description: Where the lead is now. See the Speed to lead guide for each word. call_now: type: boolean place_in_line: type: - integer - "null" description: 1 = next, 0 = being dialed now. Only on a single-lead read. estimated_wait_seconds: type: - integer - "null" description: A guess, in seconds. scheduled_for: type: - string - "null" format: date-time description: "status scheduled: when the lead can be called." scheduled_reason: type: - string - "null" enum: - outside_calling_hours - recent_contact_cooldown - retry_after_outcome - next_dial_time - null held_reason: type: - string - "null" enum: - campaign_paused - campaign_not_started - spend_cap_reached - null callback_at: type: - string - "null" format: date-time description: "status callback_scheduled: the booked time (UTC)." late: type: boolean description: A call_now lead that waited past the late limit (15 minutes by default). attempts: type: integer last_outcome: type: - string - "null" enum: - interested - not_interested - callback - voicemail - no_answer - busy - failed - dnc - wrong_number - hung_up - screened - language_barrier - not_qualified - undetermined - other - null description: A stable outcome word (see the Outcomes guide). null while there is no outcome yet. last_outcome_label: type: - string - "null" next_dial_at: type: - string - "null" format: date-time calls: type: array items: $ref: "#/components/schemas/LeadCallSummary" description: The last 10 calls, newest first. livemode: type: boolean description: On every API reply. A lead inside a live event leaves it out. required: - id - external_id - campaign_id - name - phone - email - address - fields - consent - lead_source - owner - created - updated - status - call_now - place_in_line - estimated_wait_seconds - scheduled_for - scheduled_reason - held_reason - callback_at - late - attempts - last_outcome - last_outcome_label - next_dial_at - calls examples: - id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T16:58:04.000Z status: queued call_now: true place_in_line: 3 estimated_wait_seconds: 90 scheduled_for: null scheduled_reason: null held_reason: null callback_at: null late: false attempts: 0 last_outcome: null last_outcome_label: null next_dial_at: null calls: [] livemode: true LeadOptOut: allOf: - $ref: "#/components/schemas/Lead" - type: object properties: call_in_progress: type: boolean description: true when a call was live. It is left up, and the number is never dialed again. required: - call_in_progress LeadAccepted: type: object properties: id: type: - string - "null" format: uuid description: Our ID for the lead. null on a dry run. external_id: type: - string - "null" status: type: string enum: - dialing - queued - scheduled - held call_now: type: boolean place_in_line: type: - integer - "null" description: 1 = next, 0 = being dialed now. estimated_wait_seconds: type: - integer - "null" scheduled_for: type: - string - "null" format: date-time scheduled_reason: type: - string - "null" enum: - outside_calling_hours - recent_contact_cooldown - null held_reason: type: - string - "null" enum: - campaign_paused - campaign_not_started - spend_cap_reached - null dry_run: type: boolean requeued: type: boolean const: true description: Only when the lead already existed and was put back in the queue. livemode: type: boolean description: "false for a test key: sample data, never real." required: - id - external_id - status - call_now - place_in_line - estimated_wait_seconds - scheduled_for - scheduled_reason - held_reason - dry_run - livemode examples: - id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 status: queued call_now: true place_in_line: 1 estimated_wait_seconds: 20 scheduled_for: null scheduled_reason: null held_reason: null dry_run: false livemode: true LeadBatchResult: type: object properties: succeeded: type: integer failed: type: integer dry_run: type: boolean results: type: array items: oneOf: - type: object properties: index: type: integer ok: type: boolean const: true lead: $ref: "#/components/schemas/LeadAccepted" required: - index - ok - lead - type: object properties: index: type: integer ok: type: boolean const: false error: type: object properties: code: type: string message: type: string param: type: - string - "null" lead_id: type: - string - "null" format: uuid required: - code - message - param required: - index - ok - error livemode: type: boolean description: "false for a test key: sample data, never real." required: - succeeded - failed - dry_run - results - livemode RecordingLink: type: object properties: url: type: string format: uri expires_at: type: string format: date-time livemode: type: boolean description: "false for a test key: sample data, never real." required: - url - expires_at - livemode examples: - url: https://storage.example.com/recordings/e4d3c2b1.mp3?X-Signature=example expires_at: 2026-10-06T17:10:20.000Z livemode: true Transcript: type: object properties: call_id: type: string format: uuid lines: type: array items: type: object properties: speaker: type: string enum: - ai - lead - agent name: type: string text: type: string at: type: string required: - speaker - name - text - at livemode: type: boolean description: "false for a test key: sample data, never real." required: - call_id - lines - livemode examples: - call_id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b lines: - speaker: ai name: AI text: Hi, is this Dana? This is Alex from Example Solar. at: 2026-10-06T16:58:15.000Z - speaker: lead name: LEAD_NAME text: Yes, I'd like to hear what it would cost for my house. at: 2026-10-06T16:59:02.000Z - speaker: agent name: SDR_NAME text: Hi Dana, I can help with that. at: 2026-10-06T16:59:12.000Z livemode: true Campaign: type: object properties: id: type: string format: uuid name: type: string status: type: string description: "Live keys only: draft, active, paused or completed." livemode: type: boolean description: "false for a test key: sample data, never real." required: - id - name additionalProperties: true description: A test key sees only id and name. A live key sees the campaign's settings too (more fields). examples: - id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: Roofing leads status: active livemode: true CampaignStatusChange: type: object properties: id: type: string format: uuid livemode: type: boolean description: "false for a test key: sample data, never real." required: - id additionalProperties: true DncEntry: type: object properties: id: type: string format: uuid phone: type: string source: type: - string - "null" createdAt: type: string format: date-time livemode: type: boolean description: "false for a test key: sample data, never real." required: - id - phone additionalProperties: true examples: - id: 9c8b7a6f-5e4d-4c3b-8a29-1f0e9d8c7b6a phone: "+12125557812" source: api createdAt: 2026-10-06T16:58:04.000Z livemode: true DncCheck: type: object properties: phone: type: string description: The number as sent. normalizedPhone: type: - string - "null" description: E.164, as the list stores it; null when the number couldn't be read. onDncList: type: boolean livemode: type: boolean description: "false for a test key: sample data, never real." required: - phone - normalizedPhone - onDncList - livemode DncBatchResult: type: object properties: succeeded: type: integer failed: type: integer errors: type: array items: type: string livemode: type: boolean description: "false for a test key: sample data, never real." required: - succeeded - failed - errors - livemode Export: type: object properties: id: type: string format: uuid exportType: type: string enum: - leads - call_history - analytics status: type: string rowCount: type: integer createdAt: type: string format: date-time expiresAt: type: - string - "null" format: date-time livemode: type: boolean description: "false for a test key: sample data, never real." required: - id - exportType - status additionalProperties: true ExportCreated: type: object properties: export: $ref: "#/components/schemas/Export" downloadUrl: type: string format: uri livemode: type: boolean description: "false for a test key: sample data, never real." required: - export - downloadUrl - livemode Event: type: object properties: id: type: string pattern: ^evt_ description: Unique. If you have seen this id before, skip it. type: type: string enum: - lead.created - lead.queued - lead.interested - lead.opted_out - lead.late - call.started - call.answered - call.completed - handover.accepted - voicemail.left - callback.booked created: type: string format: date-time livemode: type: boolean description: "false for a test key: sample data, never real." api_version: type: string example: 2026-10-01 data: type: object properties: object: type: object description: The lead or the call, as GET /leads/{id} or GET /calls/{id} returns it, plus the event's own fields. required: - object sample: type: boolean const: true description: Only on a "Send test event" sample. required: - id - type - created - livemode - api_version - data WebhookEndpoint: type: object properties: id: type: string format: uuid object: type: string const: webhook_endpoint url: type: string format: uri events: type: array items: type: string campaign_ids: type: - array - "null" items: type: string format: uuid description: null = every campaign. mode: type: string enum: - live - test livemode: type: boolean description: "false for a test key: sample data, never real." status: type: string enum: - active - paused description: "paused: by you, or by us after 24 hours of failures in a row." failing_since: type: - string - "null" format: date-time paused_at: type: - string - "null" format: date-time last_success_at: type: - string - "null" format: date-time previous_secret_expires_at: type: - string - "null" format: date-time description: "During a secret roll: when the old secret stops signing." created: type: string format: date-time updated: type: string format: date-time required: - id - object - url - events - campaign_ids - mode - livemode - status - failing_since - paused_at - last_success_at - previous_secret_expires_at - created - updated examples: - id: 3f6a9c2e-1b7d-4e5f-8a90-1c2d3e4f5a6b object: webhook_endpoint url: https://crm.example.com/callview events: - call.completed - lead.interested campaign_ids: null mode: live livemode: true status: active failing_since: null paused_at: null last_success_at: 2026-10-06T17:05:21.000Z previous_secret_expires_at: null created: 2026-10-01T09:00:00.000Z updated: 2026-10-01T09:00:00.000Z WebhookEndpointWithSecret: allOf: - $ref: "#/components/schemas/WebhookEndpoint" - type: object properties: secret: type: string pattern: ^whsec_ description: "Shown only in this reply. Keep it safe: it checks our signature." required: - secret WebhookEndpointResumed: allOf: - $ref: "#/components/schemas/WebhookEndpoint" - type: object properties: resent: type: integer description: Deliveries queued again. required: - resent WebhookDelivery: type: object properties: id: type: string object: type: string const: webhook_delivery endpoint_id: type: string format: uuid event_id: type: - string - "null" event_type: type: string status: type: string enum: - pending - sent - failed - gave_up - skipped_paused attempts: type: integer description: Tries so far (7 at most). next_attempt_at: type: - string - "null" format: date-time last_attempt_at: type: - string - "null" format: date-time response_status: type: - integer - "null" response_body: type: - string - "null" description: The first 4 KB of your answer. duration_ms: type: - integer - "null" resent_from: type: - string - "null" created: type: string format: date-time livemode: type: boolean description: "false for a test key: sample data, never real." required: - id - object - endpoint_id - event_id - event_type - status - attempts - next_attempt_at - last_attempt_at - response_status - response_body - duration_ms - resent_from - created - livemode examples: - id: 5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a object: webhook_delivery endpoint_id: 3f6a9c2e-1b7d-4e5f-8a90-1c2d3e4f5a6b event_id: evt_callcompletedxxxxxxxxxxx event_type: call.completed status: sent attempts: 1 next_attempt_at: null last_attempt_at: 2026-10-06T17:05:21.000Z response_status: 200 response_body: ok duration_ms: 182 resent_from: null created: 2026-10-06T17:05:20.000Z livemode: true WebhookDeliveryWithEvent: allOf: - $ref: "#/components/schemas/WebhookDelivery" - type: object properties: event: $ref: "#/components/schemas/Event" required: - event UsageCounts: type: object properties: requests: type: integer leads_added: type: integer calls: type: integer calls_connected: type: integer minutes: type: number description: Billable minutes, rounded up per call, as on your bill. cost_usd: type: number description: The minutes at your rate. required: - requests - leads_added - calls - calls_connected - minutes - cost_usd Usage: type: object properties: object: type: string const: usage period: type: string example: 2026-10 timezone: type: string description: Your organization's time zone. Months follow it. livemode: type: boolean description: "false for a test key: sample data, never real." totals: $ref: "#/components/schemas/UsageCounts" group_by: type: - string - "null" enum: - key - campaign - day - null groups: type: array items: allOf: - $ref: "#/components/schemas/UsageCounts" - type: object properties: key_id: type: - string - "null" key_name: type: - string - "null" campaign_id: type: - string - "null" format: uuid campaign_name: type: - string - "null" day: type: string format: date updated: type: - string - "null" format: date-time description: When the numbers were last counted (every 5 minutes). required: - object - period - timezone - livemode - totals - group_by - groups - updated examples: - object: usage period: 2026-10 timezone: America/New_York livemode: true totals: requests: 1840 leads_added: 212 calls: 260 calls_connected: 141 minutes: 388 cost_usd: 58.2 group_by: null groups: [] updated: 2026-10-06T17:05:00.000Z LeadResponse: type: object properties: data: $ref: "#/components/schemas/Lead" required: - data LeadListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Lead" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta LeadOptOutResponse: type: object properties: data: $ref: "#/components/schemas/LeadOptOut" required: - data LeadAcceptedResponse: type: object properties: data: $ref: "#/components/schemas/LeadAccepted" required: - data LeadBatchResponse: type: object properties: data: $ref: "#/components/schemas/LeadBatchResult" required: - data CampaignLeadListResponse: type: object properties: data: type: array items: type: object additionalProperties: true properties: id: type: string format: uuid livemode: type: boolean description: "false for a test key: sample data, never real." meta: $ref: "#/components/schemas/ListMeta" required: - data - meta CallResponse: type: object properties: data: $ref: "#/components/schemas/ApiCall" required: - data CallListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/ApiCall" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta CallNowResponse: type: object properties: data: $ref: "#/components/schemas/ApiCallNowReply" required: - data RecordingLinkResponse: type: object properties: data: $ref: "#/components/schemas/RecordingLink" required: - data TranscriptResponse: type: object properties: data: $ref: "#/components/schemas/Transcript" required: - data CampaignResponse: type: object properties: data: $ref: "#/components/schemas/Campaign" required: - data CampaignListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Campaign" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta CampaignStatusResponse: type: object properties: data: $ref: "#/components/schemas/CampaignStatusChange" required: - data DncEntryResponse: type: object properties: data: $ref: "#/components/schemas/DncEntry" required: - data DncListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/DncEntry" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta DncCheckResponse: type: object properties: data: $ref: "#/components/schemas/DncCheck" required: - data DncBatchResponse: type: object properties: data: $ref: "#/components/schemas/DncBatchResult" required: - data ExportCreatedResponse: type: object properties: data: $ref: "#/components/schemas/ExportCreated" required: - data ExportListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Export" required: - data EventResponse: type: object properties: data: $ref: "#/components/schemas/Event" required: - data EventListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/Event" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta WebhookEndpointResponse: type: object properties: data: $ref: "#/components/schemas/WebhookEndpoint" required: - data WebhookEndpointListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WebhookEndpoint" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta WebhookEndpointWithSecretResponse: type: object properties: data: $ref: "#/components/schemas/WebhookEndpointWithSecret" required: - data WebhookEndpointResumedResponse: type: object properties: data: $ref: "#/components/schemas/WebhookEndpointResumed" required: - data WebhookDeliveryResponse: type: object properties: data: $ref: "#/components/schemas/WebhookDelivery" required: - data WebhookDeliveryListResponse: type: object properties: data: type: array items: $ref: "#/components/schemas/WebhookDelivery" meta: $ref: "#/components/schemas/ListMeta" required: - data - meta WebhookDeliveryWithEventResponse: type: object properties: data: $ref: "#/components/schemas/WebhookDeliveryWithEvent" required: - data DeletedResponse: type: object properties: data: $ref: "#/components/schemas/Deleted" required: - data UsageResponse: type: object properties: data: $ref: "#/components/schemas/Usage" required: - data LegacyResponse: type: object additionalProperties: true description: An older (22-1) shape. See the route for its replacement. ApiCall: type: object properties: id: type: string format: uuid object: type: string enum: - call livemode: type: boolean lead: type: - object - "null" properties: id: type: string format: uuid external_id: type: - string - "null" name: type: - string - "null" phone: type: - string - "null" description: E.164 (+1...) campaign_id: type: - string - "null" format: uuid direction: type: string enum: - outbound - inbound status: type: string enum: - ringing - in_progress - ended outcome: type: - string - "null" enum: - interested - not_interested - callback - voicemail - no_answer - busy - failed - dnc - wrong_number - hung_up - screened - language_barrier - not_qualified - undetermined - other - null description: A stable word. null while the call has no outcome yet; other only for a label we don't know (see outcome_label). outcome_label: type: - string - "null" description: Your organization's name for the outcome, e.g. Hung Up note: type: - string - "null" description: The AI's after-call note, or what a person wrote duration_seconds: type: - integer - "null" started: type: string format: date-time answered: type: - string - "null" format: date-time ended: type: - string - "null" format: date-time updated: type: string format: date-time handled_by: type: object properties: id: type: - string - "null" description: The user's ID; null for the AI and for a closer name: type: string role: type: string enum: - sdr - closer - ai owner: type: - object - "null" properties: id: type: string name: type: string tth_seconds: type: - number - "null" description: Seconds from buying intent to a person on the call callback_at: type: - string - "null" format: date-time recording_available: type: boolean transcript_available: type: boolean started_by: type: object properties: type: type: string enum: - dialer - api - person api_key_id: type: - string - "null" examples: - id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: ended outcome: interested outcome_label: Interested note: Wants a quote for a 6 kW system; home owner, roof replaced 2019. duration_seconds: 412 started: 2026-10-06T16:58:06.000Z answered: 2026-10-06T16:58:14.000Z ended: 2026-10-06T17:04:58.000Z updated: 2026-10-06T17:05:20.000Z handled_by: id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: SDR_NAME role: sdr owner: null tth_seconds: 9.3 callback_at: null recording_available: true transcript_available: true started_by: type: api api_key_id: key_example ApiCallNowReply: type: object properties: lead_id: type: string format: uuid external_id: type: - string - "null" campaign_id: type: string format: uuid status: type: string enum: - dialing - queued - scheduled - held place_in_line: type: - integer - "null" description: 1 = next; 0 = being dialed now estimated_wait_seconds: type: - integer - "null" scheduled_for: type: - string - "null" format: date-time scheduled_reason: type: - string - "null" enum: - outside_calling_hours - recent_contact_cooldown - null held_reason: type: - string - "null" enum: - campaign_paused - campaign_not_started - spend_cap_reached - null calls_left_today: type: integer description: API-started calls this lead has left in the rolling 24 hours livemode: type: boolean paths: /calls: get: tags: - Calls summary: List calls description: | Newest first. Cursor-paged: pass the last call's id as starting_after for the next page. Needs calls:read; a key limited to some campaigns sees only their calls. Deprecated for one release: offset and status (and a limit over 100) still answer the old list shape, with a Deprecation header. parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: starting_after schema: type: string format: uuid - in: query name: campaign_id schema: type: string format: uuid - in: query name: lead_id schema: type: string format: uuid - in: query name: external_id schema: type: string description: The lead's ID in your system. - in: query name: outcome schema: type: string enum: - interested - not_interested - callback - voicemail - no_answer - busy - failed - dnc - wrong_number - hung_up - screened - language_barrier - not_qualified - undetermined - other - in: query name: created[gte] schema: type: string example: 2026-10-06T00:00:00Z - in: query name: created[lte] schema: type: string - in: query name: offset deprecated: true schema: type: integer - in: query name: status deprecated: true schema: type: string responses: "200": description: A page of calls, newest first content: application/json: schema: $ref: "#/components/schemas/CallListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (a bad filter, or a starting_after that isn't one of your calls) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (calls:read, or campaign_id outside the key's campaigns) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign_id) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCalls post: tags: - Calls summary: Call this lead now description: | Puts an existing lead at the front of its campaign's dial queue (the same queue as POST /leads with call_now): it is dialed next, never above the campaign's lines. The same checks and the same reply as POST /leads: dialing, queued (with the place in line), scheduled (outside the lead's calling hours) or held (a paused campaign). Do Not Call, calling hours and the other dialing rules always apply. At most 3 API-started calls per lead in 24 hours. Needs calls:write. requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: lead_id: type: string format: uuid external_id: type: string description: Your ID for the lead (send campaign_id too if it is in more than one campaign) campaign_id: type: string format: uuid example: external_id: crm-10442 responses: "202": description: Accepted. status says what happens next. content: application/json: schema: $ref: "#/components/schemas/CallNowResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (neither or both of lead_id and external_id; an external_id in more than one campaign without campaign_id) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (calls:write, or campaign_id outside the key's campaigns) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such lead for this key) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: lead_busy, lead_taken_out_of_queue, campaign_closed, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: lead_busy: summary: lead_busy value: error: type: invalid_request_error code: lead_busy message: The lead is being dialed or is on a call now. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c lead_taken_out_of_queue: summary: lead_taken_out_of_queue value: error: type: invalid_request_error code: lead_taken_out_of_queue message: A person took the lead out of the dialing queue in CallView; the API does not overrule a person. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c campaign_closed: summary: campaign_closed value: error: type: invalid_request_error code: campaign_closed message: The campaign is completed and takes no new leads. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - lead_busy - lead_taken_out_of_queue - campaign_closed - idempotency_mismatch - idempotency_in_progress "422": description: on_dnc_list, number_retired, or number_not_allowed (a premium or international number; reason premium / international) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: on_dnc_list: summary: on_dnc_list value: error: type: invalid_request_error code: on_dnc_list message: The number is on the organization's Do Not Call list. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_retired: summary: number_retired value: error: type: invalid_request_error code: number_retired message: The number was retired in this campaign after repeated failed calls. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_not_allowed: summary: number_not_allowed value: error: type: invalid_request_error code: number_not_allowed message: "A premium-rate or international number (including +1 Caribbean numbers) is not dialed for this organization. `reason` says which: premium or international." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - on_dnc_list - number_retired - number_not_allowed "429": description: call_limit_reached, test_flows_busy, rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: call_limit_reached: summary: call_limit_reached value: error: type: rate_limit_error code: call_limit_reached message: The lead has had 3 calls started by the API in the last 24 hours. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c test_flows_busy: summary: test_flows_busy value: error: type: rate_limit_error code: test_flows_busy message: "Test mode only: this test key already has 20 sample calls running. Retry after Retry-After seconds." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - call_limit_reached - test_flows_busy - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postCalls parameters: - $ref: "#/components/parameters/IdempotencyKey" /calls/{id}: get: tags: - Calls summary: Get a call description: Needs calls:read. A call in another organization, or in a campaign outside the key's, is 404. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: The call content: application/json: schema: $ref: "#/components/schemas/CallResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCallsId /calls/{id}/recording: get: tags: - Calls summary: A link to the call's recording, valid for 5 minutes description: | Made on request and never stored: fetch a fresh one each time. The link is a signed storage URL that stops working at expires_at. 404 recording_not_available when there is none (recording is off for your organization, or it is past retention). Needs calls:read. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: A link that works for 5 minutes content: application/json: schema: $ref: "#/components/schemas/RecordingLinkResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such call) or recording_not_available headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c recording_not_available: summary: recording_not_available value: error: type: invalid_request_error code: recording_not_available message: "The call has no recording: recording is off for the organization, or it is past retention." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found - recording_not_available "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable (recordings can't be reached right now) headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: getCallsIdRecording /calls/{id}/transcript: get: tags: - Calls summary: The call's transcript description: | The lines in order: speaker ai, lead or agent (the person who took the call), with a name and a time. ?format=text answers plain text, one "Name: text" line per turn. Needs calls:read. parameters: - in: path name: id required: true schema: type: string format: uuid - in: query name: format schema: type: string enum: - json - text default: json responses: "200": description: The transcript, or plain text with ?format=text content: application/json: schema: $ref: "#/components/schemas/TranscriptResponse" text/plain: schema: type: string example: |- AI: Hi, this is Alex from Example Solar. Lead: Hi. headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCallsIdTranscript /campaigns: get: tags: - Campaigns summary: List campaigns description: The campaigns this key can use, page by page (cursor = the next_cursor you were given). Needs campaigns:read. parameters: - in: query name: cursor schema: type: string - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 responses: "200": description: A page of campaigns content: application/json: schema: $ref: "#/components/schemas/CampaignListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCampaigns /campaigns/{campaignId}/leads: post: tags: - Leads summary: Add a lead (older address) description: The same checks, queue and reply as POST /leads, with the campaign in the path. customFields is still accepted (it is merged into fields). Use POST /leads for new work. parameters: - in: path name: campaignId required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: - phone additionalProperties: false properties: phone: type: string maxLength: 32 external_id: type: string maxLength: 200 name: type: string maxLength: 200 email: type: string maxLength: 254 address: type: string maxLength: 500 fields: type: object additionalProperties: type: string customFields: type: object additionalProperties: type: string consent: $ref: "#/components/schemas/Consent" call_now: type: boolean dry_run: type: boolean example: external_id: crm-10442 phone: "+15550100001" name: Dana Smith call_now: true consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote responses: "200": description: A dry run, or a re-queued lead content: application/json: schema: $ref: "#/components/schemas/LeadAcceptedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "201": description: Accepted (see POST /leads) content: application/json: schema: $ref: "#/components/schemas/LeadAcceptedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request or invalid_phone headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c invalid_phone: summary: invalid_phone value: error: type: invalid_request_error code: invalid_phone message: The phone number is not a valid number. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request - invalid_phone "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: duplicate_lead, campaign_closed, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: duplicate_lead: summary: duplicate_lead value: error: type: invalid_request_error code: duplicate_lead message: A lead with this phone number (or external_id) already exists in this campaign. `lead_id` names it. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c campaign_closed: summary: campaign_closed value: error: type: invalid_request_error code: campaign_closed message: The campaign is completed and takes no new leads. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - duplicate_lead - campaign_closed - idempotency_mismatch - idempotency_in_progress "422": description: on_dnc_list, number_retired, consent_required or number_not_allowed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: on_dnc_list: summary: on_dnc_list value: error: type: invalid_request_error code: on_dnc_list message: The number is on the organization's Do Not Call list. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_retired: summary: number_retired value: error: type: invalid_request_error code: number_retired message: The number was retired in this campaign after repeated failed calls. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c consent_required: summary: consent_required value: error: type: invalid_request_error code: consent_required message: This campaign requires consent on every lead. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_not_allowed: summary: number_not_allowed value: error: type: invalid_request_error code: number_not_allowed message: "A premium-rate or international number (including +1 Caribbean numbers) is not dialed for this organization. `reason` says which: premium or international." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - on_dnc_list - number_retired - consent_required - number_not_allowed "429": description: queue_full, lead_rate_limited, test_flows_busy, rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: queue_full: summary: queue_full value: error: type: rate_limit_error code: queue_full message: The campaign already has 5,000 API leads waiting to be called. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c lead_rate_limited: summary: lead_rate_limited value: error: type: rate_limit_error code: lead_rate_limited message: Too many new leads a minute on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c test_flows_busy: summary: test_flows_busy value: error: type: rate_limit_error code: test_flows_busy message: "Test mode only: this test key already has 20 sample calls running. Retry after Retry-After seconds." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - queue_full - lead_rate_limited - test_flows_busy - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postCampaignsCampaignIdLeads get: tags: - Leads summary: List a campaign's leads (older list) description: | A campaign's leads, page by page (cursor = the next_cursor you were given). A live key gets the older lead shape here; GET /leads with campaign_id gives the lead object and is the one to use for new work. Needs leads:read. parameters: - in: path name: campaignId required: true schema: type: string format: uuid - in: query name: cursor schema: type: string - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: search schema: type: string maxLength: 200 description: Part of a name, phone or email. responses: "200": description: A page of leads content: application/json: schema: $ref: "#/components/schemas/CampaignLeadListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:read, or the campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCampaignsCampaignIdLeads /campaigns/{campaignId}/leads/batch: post: tags: - Leads summary: Add up to 60 leads (older address) description: The same as POST /leads/batch, with the campaign in the path. parameters: - in: path name: campaignId required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: - leads additionalProperties: false properties: dry_run: type: boolean leads: type: array minItems: 1 maxItems: 60 items: type: object required: - phone properties: phone: type: string external_id: type: string name: type: string email: type: string address: type: string fields: type: object additionalProperties: type: string customFields: type: object additionalProperties: type: string consent: $ref: "#/components/schemas/Consent" call_now: type: boolean example: leads: - external_id: crm-10443 phone: "+15550100002" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote responses: "200": description: A result per lead (see POST /leads/batch) content: application/json: schema: $ref: "#/components/schemas/LeadBatchResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: lead_rate_limited, rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: lead_rate_limited: summary: lead_rate_limited value: error: type: rate_limit_error code: lead_rate_limited message: Too many new leads a minute on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - lead_rate_limited - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postCampaignsCampaignIdLeadsBatch /campaigns/{id}: get: tags: - Campaigns summary: Get a campaign description: Needs campaigns:read. A test key sees the id and name only. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: The campaign content: application/json: schema: $ref: "#/components/schemas/CampaignResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (campaigns:read, or the campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getCampaignsId /campaigns/{id}/activate: post: tags: - Campaigns summary: Start a campaign description: | Starts (or restarts) dialing. The campaign needs an SDR and must be a draft or paused. A test key changes nothing and answers what the status would be. Needs campaigns:write. parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Started content: application/json: schema: $ref: "#/components/schemas/CampaignStatusResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (the campaign can't start from its status, or has no SDR) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (campaigns:write, or the campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postCampaignsIdActivate /campaigns/{id}/pause: post: tags: - Campaigns summary: Pause a campaign description: Stops new calls. Calls already up carry on. Leads you add while it is paused are kept (status held) and dialed when it starts again. A test key changes nothing. Needs campaigns:write. parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Paused content: application/json: schema: $ref: "#/components/schemas/CampaignStatusResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (the campaign isn't running) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (campaigns:write, or the campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postCampaignsIdPause /dnc: get: tags: - DNC summary: List your Do Not Call list description: Page by page (cursor = the next_cursor you were given). Needs dnc:read. parameters: - in: query name: cursor schema: type: string - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: search schema: type: string maxLength: 200 description: Part of a phone number. responses: "200": description: A page of entries content: application/json: schema: $ref: "#/components/schemas/DncListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getDnc post: tags: - DNC summary: Add a number to the list description: No campaign of your organization dials it again. Your leads with this number get a lead.opted_out event. Needs dnc:write. requestBody: required: true content: application/json: schema: type: object required: - phone additionalProperties: false properties: phone: type: string example: phone: "+12125557812" responses: "201": description: Added content: application/json: schema: $ref: "#/components/schemas/DncEntryResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request or invalid_phone headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c invalid_phone: summary: invalid_phone value: error: type: invalid_request_error code: invalid_phone message: The phone number is not a valid number. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request - invalid_phone "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "409": description: duplicate_dnc_entry, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: duplicate_dnc_entry: summary: duplicate_dnc_entry value: error: type: invalid_request_error code: duplicate_dnc_entry message: This number is already on the Do Not Call list. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - duplicate_dnc_entry - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postDnc parameters: - $ref: "#/components/parameters/IdempotencyKey" /dnc/{id}: delete: tags: - DNC summary: Take a number off the list description: Needs dnc:write. Be sure the person asked for it; we can call the number again after this. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: The entry that was removed content: application/json: schema: $ref: "#/components/schemas/DncEntryResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: deleteDncId /dnc/batch: post: tags: - DNC summary: Add up to 100 numbers to the list description: Each number is added on its own; errors lists the ones that weren't (bad or already there). Needs dnc:write. requestBody: required: true content: application/json: schema: type: object required: - phones additionalProperties: false properties: phones: type: array minItems: 1 maxItems: 100 items: type: string example: phones: - "+12125557812" - "+13105557845" responses: "200": description: How many were added content: application/json: schema: $ref: "#/components/schemas/DncBatchResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (no numbers, or more than 100) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postDncBatch parameters: - $ref: "#/components/parameters/IdempotencyKey" /dnc/check: get: tags: - DNC summary: Is this number on the list? description: Needs dnc:read. parameters: - in: query name: phone required: true schema: type: string example: "+12125557812" description: The number to check, in any common format. URL-encode a leading plus (%2B); an unencoded one arrives as a space and is read as a plus. responses: "200": description: The answer. normalizedPhone is the number in E.164 form, as the list stores it; null when the number couldn't be read (the value as sent was then matched exactly, so onDncList false does not mean it is safe to call). content: application/json: schema: $ref: "#/components/schemas/DncCheckResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (phone missing or sent more than once) or invalid_phone headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c invalid_phone: summary: invalid_phone value: error: type: invalid_request_error code: invalid_phone message: The phone number is not a valid number. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request - invalid_phone "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getDncCheck /events: get: tags: - Events summary: List events description: > Every event we sent or would have sent, newest first, kept 30 days. Keyset-paged: pass the last event's id as `starting_after` for the next page. A test key sees only test events (`livemode: false`), a live key only live ones. Needs the `events:read` permission; a key limited to some campaigns sees only their events. parameters: - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 50 - in: query name: starting_after schema: type: string example: evt_3fQ9xK2mZpL8vN1cR7tY4wBa description: The id of the last event on the previous page. - in: query name: type schema: type: string example: call.completed,lead.queued description: One event type, a comma-separated list, or the parameter repeated. - in: query name: created[gte] schema: type: string example: 2026-10-06T00:00:00Z description: Created at or after (ISO 8601 or unix seconds). - in: query name: created[lte] schema: type: string description: Created at or before (ISO 8601 or unix seconds). - in: query name: campaign_id schema: type: string format: uuid - in: query name: object_id schema: type: string description: Only events about this call or lead. responses: "200": description: A page of events, newest first content: application/json: schema: $ref: "#/components/schemas/EventListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (a bad filter, an unknown type, or a starting_after that isn't one of your events) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (events:read, or a campaign outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign_id) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getEvents /events/{id}: get: tags: - Events summary: Get one event description: > The same envelope a webhook carries. Needs `events:read`. Another organization's event, or one of the other mode (test/live), is 404. parameters: - in: path name: id required: true schema: type: string example: evt_3fQ9xK2mZpL8vN1cR7tY4wBa responses: "200": description: The event, in the same envelope a webhook carries content: application/json: schema: $ref: "#/components/schemas/EventResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (events:read, or the event's campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getEventsId /exports: post: tags: - Exports summary: Make an export file description: | Leads, call history or analytics as a file, with a download link. Needs leads:read and calls:read, on a key for every campaign. A test key gets a sample file. requestBody: required: true content: application/json: schema: type: object required: - exportType additionalProperties: false properties: exportType: type: string enum: - leads - call_history - analytics filters: type: object additionalProperties: false properties: campaignId: type: string format: uuid startDate: type: string example: 2026-10-01 description: YYYY-MM-DD endDate: type: string example: 2026-10-06 description: YYYY-MM-DD example: exportType: call_history filters: startDate: 2026-10-01 endDate: 2026-10-06 responses: "200": description: The export and its download link content: application/json: schema: $ref: "#/components/schemas/ExportCreatedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:read and calls:read, on a key for every campaign) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postExports parameters: - $ref: "#/components/parameters/IdempotencyKey" get: tags: - Exports summary: List your exports description: Needs leads:read and calls:read, on a key for every campaign. A test key has none. responses: "200": description: Your exports content: application/json: schema: $ref: "#/components/schemas/ExportListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getExports /leads: post: tags: - Leads summary: Add a lead (speed to lead) description: | Checks the lead first: a valid +1 number, your Do Not Call list, the campaign's retired numbers, duplicates (by external_id or phone), consent if the campaign asks for it, number rules (no premium or international numbers) and the 5,000 waiting-lead limit. If it passes, the lead goes straight into the campaign's dial queue. A call_now lead is dialed before the campaign's other leads, oldest first, as the campaign's lines free up. Outside the lead's calling hours it is scheduled for the next window. A paused or not-started campaign holds the lead and dials it when the campaign runs, and so does a reached spend cap. A refused lead isn't saved. place_in_line and estimated_wait_seconds are estimates. With dry_run true every check runs and the lead isn't saved. Needs leads:write. requestBody: required: true content: application/json: schema: type: object required: - campaign_id - phone additionalProperties: false properties: campaign_id: type: string format: uuid external_id: type: string maxLength: 200 description: Your own ID for the lead. The same external_id twice in a campaign is a duplicate. phone: type: string maxLength: 32 description: US or Canadian number. +1 and 10 digits is best; (212) 555-7812 is fine too. Numbers in the 555-0100 to 555-0199 range are refused as made up (test mode takes its magic numbers). name: type: string maxLength: 200 email: type: string maxLength: 254 address: type: string maxLength: 500 fields: type: object additionalProperties: type: string maxLength: 2000 description: Your custom fields, at most 50. The campaign's script can use them. consent: $ref: "#/components/schemas/Consent" call_now: type: boolean description: Dial ahead of the campaign's other leads. Defaults to the campaign's setting. dry_run: type: boolean description: Run every check and answer, without saving the lead. example: campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 external_id: crm-10442 phone: "+15550100001" name: Dana Smith email: dana@example.com fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote call_now: true responses: "200": description: A dry run (not saved), or a lead that already existed and was put back in the queue (requeued true) content: application/json: schema: $ref: "#/components/schemas/LeadAcceptedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "201": description: Accepted. status says what happens next. content: application/json: schema: $ref: "#/components/schemas/LeadAcceptedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request or invalid_phone headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c invalid_phone: summary: invalid_phone value: error: type: invalid_request_error code: invalid_phone message: The phone number is not a valid number. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request - invalid_phone "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:write, or the campaign is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no such campaign) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: duplicate_lead, campaign_closed, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: duplicate_lead: summary: duplicate_lead value: error: type: invalid_request_error code: duplicate_lead message: A lead with this phone number (or external_id) already exists in this campaign. `lead_id` names it. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c campaign_closed: summary: campaign_closed value: error: type: invalid_request_error code: campaign_closed message: The campaign is completed and takes no new leads. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - duplicate_lead - campaign_closed - idempotency_mismatch - idempotency_in_progress "422": description: on_dnc_list, number_retired, consent_required or number_not_allowed (premium or international; reason says which) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: on_dnc_list: summary: on_dnc_list value: error: type: invalid_request_error code: on_dnc_list message: The number is on the organization's Do Not Call list. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_retired: summary: number_retired value: error: type: invalid_request_error code: number_retired message: The number was retired in this campaign after repeated failed calls. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c consent_required: summary: consent_required value: error: type: invalid_request_error code: consent_required message: This campaign requires consent on every lead. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c number_not_allowed: summary: number_not_allowed value: error: type: invalid_request_error code: number_not_allowed message: "A premium-rate or international number (including +1 Caribbean numbers) is not dialed for this organization. `reason` says which: premium or international." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - on_dnc_list - number_retired - consent_required - number_not_allowed "429": description: queue_full, lead_rate_limited, call_limit_reached, test_flows_busy, rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: queue_full: summary: queue_full value: error: type: rate_limit_error code: queue_full message: The campaign already has 5,000 API leads waiting to be called. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c lead_rate_limited: summary: lead_rate_limited value: error: type: rate_limit_error code: lead_rate_limited message: Too many new leads a minute on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c call_limit_reached: summary: call_limit_reached value: error: type: rate_limit_error code: call_limit_reached message: The lead has had 3 calls started by the API in the last 24 hours. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c test_flows_busy: summary: test_flows_busy value: error: type: rate_limit_error code: test_flows_busy message: "Test mode only: this test key already has 20 sample calls running. Retry after Retry-After seconds." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - queue_full - lead_rate_limited - call_limit_reached - test_flows_busy - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postLeads parameters: - $ref: "#/components/parameters/IdempotencyKey" get: tags: - Leads summary: Find a lead by external_id, or list leads description: | With external_id: the one lead carrying your ID, as `{ data: lead }`. external_id is unique per campaign, not per organization: a match in two of the key's campaigns is 409 ambiguous_external_id with `candidates` ([{ id, campaign_id }]); add campaign_id to pick one. Without it: the key's leads, newest first, keyset-paged (`starting_after` = the last lead's id), as `{ data: [lead], meta: { next_cursor, has_more } }`. With a status filter a page can hold fewer than `limit` leads while has_more is true; keep paging with next_cursor. place_in_line is only given on a single-lead read. status is one of: new, queued, scheduled, held, dialing, on_call, callback_scheduled, done, out_of_queue. parameters: - in: query name: external_id schema: type: string maxLength: 200 - in: query name: campaign_id schema: type: string format: uuid - in: query name: status schema: type: string enum: - new - queued - scheduled - held - dialing - on_call - callback_scheduled - done - out_of_queue - in: query name: created[gte] schema: type: string example: 2026-10-06T00:00:00Z description: Created at or after (ISO 8601 or unix seconds). - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 20 - in: query name: starting_after schema: type: string format: uuid responses: "200": description: With external_id, the one lead. Without it, a page of leads. content: application/json: schema: oneOf: - $ref: "#/components/schemas/LeadResponse" - $ref: "#/components/schemas/LeadListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (a bad filter, or a starting_after that isn't one of this key's leads) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:read, or a campaign_id outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (no lead with this external_id in the key's campaigns) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: ambiguous_external_id, with candidates headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: ambiguous_external_id: summary: ambiguous_external_id value: error: type: invalid_request_error code: ambiguous_external_id message: This external_id matches leads in more than one campaign. `candidates` lists them; add campaign_id (Story 34-7). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - ambiguous_external_id "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getLeads /leads/{id}: get: tags: - Leads summary: Get a lead - where it is and its calls description: > The lead object: id, external_id, campaign_id, livemode, name, phone, email, address, fields, consent, lead_source, owner ({ id, name } of the SDR its latest call was dialed for, or null), created, updated, status, call_now, place_in_line and estimated_wait_seconds (while queued; estimates), scheduled_for, scheduled_reason, held_reason, callback_at, late, attempts, last_outcome (a stable word, the same as the call object's outcome) and last_outcome_label (your organization's name for it), next_dial_at, and calls (the last 10, newest first: { id, started, outcome, outcome_label, duration_seconds }). status: new (not yet queued), queued (due now), scheduled (waits for scheduled_for: calling hours, a cooldown, a retry), held (held_reason: campaign_paused, campaign_not_started, spend_cap_reached), dialing, on_call, callback_scheduled (callback_at), done (finished, not coming back), out_of_queue (taken out, opted out or on the Do Not Call list). A lead in a campaign outside the key's, in another organization, or removed is 404 not_found. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: The lead content: application/json: schema: $ref: "#/components/schemas/LeadResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:read) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getLeadsId patch: tags: - Leads summary: Update a lead description: | name, email, address (null or "" clears one), fields (merged: a key sent as "" is removed; other keys are kept), consent (replaced), external_id (only while the lead has none), call_now: false (drops the speed-to-lead priority). The phone can't be changed (phone_cannot_change): add a new lead instead. Answers the updated lead. Idempotency-Key is honoured. parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: - string - "null" maxLength: 200 email: type: - string - "null" maxLength: 254 address: type: - string - "null" maxLength: 500 fields: type: object additionalProperties: type: string description: 'Merged: a key sent as "" is removed, other keys are kept.' consent: $ref: "#/components/schemas/Consent" external_id: type: string maxLength: 200 description: Only while the lead has none. call_now: type: boolean enum: - false description: false drops the speed-to-lead priority. phone: type: string description: Can't be changed (phone_cannot_change). Add a new lead instead. example: name: Dana Smith-Lee fields: roof_age: "13" old_field: "" responses: "200": description: The updated lead content: application/json: schema: $ref: "#/components/schemas/LeadResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (nothing to update, call_now true, or external_id already set to another value - reason external_id_already_set) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:write) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: duplicate_lead, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: duplicate_lead: summary: duplicate_lead value: error: type: invalid_request_error code: duplicate_lead message: A lead with this phone number (or external_id) already exists in this campaign. `lead_id` names it. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - duplicate_lead - idempotency_mismatch - idempotency_in_progress "422": description: phone_cannot_change headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: phone_cannot_change: summary: phone_cannot_change value: error: type: invalid_request_error code: phone_cannot_change message: A lead's phone number can't be changed (Story 34-7). Add a new lead with the new number. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - phone_cannot_change "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: patchLeadsId /leads/{id}/opt_out: post: tags: - Leads summary: Opt a lead out - stop calling, add to Do Not Call description: | The number goes on the organization's Do Not Call list (source "API"), so no campaign of the organization dials it again; the lead leaves the queue with the DNC outcome and its open callbacks are closed. A call in progress is NOT cut: the reply says call_in_progress true, and nothing dials the number again. Idempotent: a second opt_out answers the same, with no second Do Not Call entry. Answers the updated lead plus call_in_progress. parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: false content: application/json: schema: type: object additionalProperties: false properties: reason: type: string maxLength: 500 description: Why (kept in the audit log and on closed callbacks) example: reason: Asked to stop on our web chat responses: "200": description: The lead, plus call_in_progress content: application/json: schema: $ref: "#/components/schemas/LeadOptOutResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:write) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postLeadsIdOptOut /leads/batch: post: tags: - Leads summary: Add up to 60 leads description: | Each lead gets the same checks as POST /leads and its own result, in the order you sent them. A lead that fails doesn't stop the others. campaign_id may be on each lead or once for the batch. Each lead counts toward the key's new leads a minute. Needs leads:write. requestBody: required: true content: application/json: schema: type: object required: - leads additionalProperties: false properties: campaign_id: type: string format: uuid dry_run: type: boolean leads: type: array minItems: 1 maxItems: 60 items: type: object required: - phone additionalProperties: false properties: campaign_id: type: string format: uuid external_id: type: string maxLength: 200 phone: type: string maxLength: 32 name: type: string maxLength: 200 email: type: string maxLength: 254 address: type: string maxLength: 500 fields: type: object additionalProperties: type: string consent: $ref: "#/components/schemas/Consent" call_now: type: boolean example: campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 leads: - external_id: crm-10443 phone: "+15550100002" name: Lee Park consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote - external_id: crm-10444 phone: "+15550100003" name: Sam Ortiz consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote responses: "200": description: "A result per lead: { index, ok: true, lead } or { index, ok: false, error: { code, message, param, lead_id } }" content: application/json: schema: $ref: "#/components/schemas/LeadBatchResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (more than 60 leads, or a malformed lead) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (leads:write, or the batch's campaign_id is outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (the batch's campaign_id) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: lead_rate_limited, rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: lead_rate_limited: summary: lead_rate_limited value: error: type: rate_limit_error code: lead_rate_limited message: Too many new leads a minute on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - lead_rate_limited - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postLeadsBatch parameters: - $ref: "#/components/parameters/IdempotencyKey" /usage: get: tags: - Usage summary: Usage for a month description: > API requests, leads added, calls, billable minutes and their cost for the month so far (or a past month), in your organization's time zone. Minutes are the bill's own rule (rounded up per call) and `cost_usd` is those minutes at your rate, so the month's total matches your bill. Updated every 5 minutes (`updated`). A test key sees its test counts (`livemode: false`, never billed). A key limited to some campaigns sees only their leads, calls and minutes, plus its own requests. Needs the `usage:read` permission. parameters: - in: query name: period schema: type: string example: 2026-10 default: current description: "`current` (the month so far) or a month, YYYY-MM." - in: query name: group_by schema: type: string enum: - key - campaign - day description: Split the totals by API key, campaign or day. responses: "200": description: > The month's totals, and with group_by one group per key, campaign or day carrying the same counts plus its key_id / key_name, campaign_id / campaign_name, or day. content: application/json: schema: $ref: "#/components/schemas/UsageResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (a bad period or group_by) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (usage:read) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getUsage /webhook_endpoints: get: tags: - Webhooks summary: List webhook endpoints description: The endpoints for the key's mode (test or live) within its campaigns. Needs webhooks:read. responses: "200": description: Your endpoints content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhookEndpoints post: tags: - Webhooks summary: Create a webhook endpoint description: | Where we send events. HTTPS only, and the address must be on the public internet. The endpoint's mode is the key's: a test key's endpoint gets test events only. The secret (whsec_...) is in this reply only. Every delivery is signed with it in the CallView-Signature header (see the Webhooks guide). At most 10 endpoints per organization. Needs webhooks:write, plus the read permission of every event's data: leads:read for lead.created, lead.queued, lead.opted_out, lead.late and callback.booked; calls:read for call.*, lead.interested, handover.accepted and voicemail.left (403 permission_denied names the one missing). requestBody: required: true content: application/json: schema: type: object required: - url - events additionalProperties: false properties: url: type: string maxLength: 2048 example: https://crm.example.com/callview events: type: array minItems: 1 maxItems: 50 items: type: string example: - call.completed - lead.interested campaign_ids: type: - array - "null" items: type: string format: uuid description: Only these campaigns. null or left out = every campaign (needs a key for every campaign). example: url: https://crm.example.com/callview events: - call.completed - lead.interested responses: "201": description: Created. Keep the secret; it is not shown again. content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointWithSecretResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (an http:// or private address, or an unknown event type) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied, or limit_reached (10 endpoints) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c limit_reached: summary: limit_reached value: error: type: invalid_request_error code: limit_reached message: A plan limit was reached (for example, webhook endpoints per organization). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied - limit_reached "404": description: not_found (a campaign in campaign_ids) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable (the secret can't be stored right now) headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhookEndpoints parameters: - $ref: "#/components/parameters/IdempotencyKey" /webhook_endpoints/{id}: get: tags: - Webhooks summary: Get a webhook endpoint description: Needs webhooks:read. Another organization's endpoint, or one of the other mode, is 404. responses: "200": description: The endpoint (never its secret) content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied (webhooks:read, or the endpoint covers campaigns outside the key's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhookEndpointsId parameters: - in: path name: id required: true schema: type: string format: uuid patch: tags: - Webhooks summary: Change a webhook endpoint description: url, events, campaign_ids (null = every campaign) or status (active or paused). A new address is checked like a new endpoint's. Needs webhooks:write; changing url, events or campaign_ids also needs the read permission of every event the endpoint takes (as at creation). requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: url: type: string maxLength: 2048 events: type: array minItems: 1 maxItems: 50 items: type: string campaign_ids: type: - array - "null" items: type: string format: uuid status: type: string enum: - active - paused example: events: - call.completed - lead.interested - lead.opted_out responses: "200": description: The changed endpoint content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: patchWebhookEndpointsId parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" delete: tags: - Webhooks summary: Delete a webhook endpoint description: The endpoint and its delivery history go. Events stay in GET /events. Needs webhooks:write. responses: "200": description: Deleted content: application/json: schema: $ref: "#/components/schemas/DeletedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: deleteWebhookEndpointsId parameters: - in: path name: id required: true schema: type: string format: uuid /webhook_endpoints/{id}/deliveries: get: tags: - Webhooks summary: An endpoint's deliveries description: | Each delivery is one event sent (or waiting to be sent) to this endpoint: its status, how many tries (7 at most, over 24 hours), your last answer (the first 4 KB) and the times. Newest first, page by page (starting_after = the next_cursor you were given). Needs webhooks:read. parameters: - in: path name: id required: true schema: type: string format: uuid - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 25 - in: query name: starting_after schema: type: string format: uuid - in: query name: status schema: type: string enum: - pending - sent - failed - gave_up - skipped_paused responses: "200": description: A page of deliveries content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryListResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request (a bad filter, or a starting_after that isn't one of this endpoint's) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhookEndpointsIdDeliveries /webhook_endpoints/{id}/deliveries/{delivery_id}/resend: post: tags: - Webhooks summary: Send a delivery again description: A new delivery with the same event id (so your side can skip it if it already has it) and a fresh signature. A paused endpoint has to be resumed first. Needs webhooks:write. responses: "202": description: Queued. It goes out within a second or two. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found (the endpoint or the delivery) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: endpoint_paused, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: endpoint_paused: summary: endpoint_paused value: error: type: invalid_request_error code: endpoint_paused message: The webhook endpoint is paused. Resume it (POST /webhook_endpoints/{id}/resume), then re-send or send the test event. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - endpoint_paused - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhookEndpointsIdDeliveriesDeliveryIdResend parameters: - in: path name: delivery_id required: true schema: type: string - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" /webhook_endpoints/{id}/resume: post: tags: - Webhooks summary: Resume a paused endpoint description: With resend_skipped true, the deliveries skipped while it was paused (up to 1,000, newest first) are sent again with their original event ids. Needs webhooks:write. requestBody: required: false content: application/json: schema: type: object additionalProperties: false properties: resend_skipped: type: boolean default: false example: resend_skipped: true responses: "200": description: The endpoint, and how many deliveries were queued again content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointResumedResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhookEndpointsIdResume parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" /webhook_endpoints/{id}/roll_secret: post: tags: - Webhooks summary: Roll the signing secret description: | A new secret, shown once. The old one keeps signing too (two v1 values in the header) for grace_hours, so you can switch over without missing anything. Needs webhooks:write. requestBody: required: false content: application/json: schema: type: object additionalProperties: false properties: grace_hours: type: integer minimum: 0 maximum: 168 default: 24 example: grace_hours: 24 responses: "200": description: The endpoint and its new secret content: application/json: schema: $ref: "#/components/schemas/WebhookEndpointWithSecretResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable (the secret can't be stored right now) headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhookEndpointsIdRollSecret parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" /webhook_endpoints/{id}/test: post: tags: - Webhooks summary: Send a test event description: | Sends one sample of any event type to this endpoint, so you can check your receiver. It is the event's example in a real envelope with a new evt_ id, livemode false and "sample": true, signed with this endpoint's secret just like a real delivery, and retried like one. It shows in the endpoint's deliveries. It is not an event, so GET /events doesn't list it. A paused endpoint has to be resumed first. Needs webhooks:write. requestBody: required: true content: application/json: schema: type: object required: - type additionalProperties: false properties: type: type: string example: call.completed description: An event type, for example call.completed. example: type: call.completed responses: "202": description: Queued. It goes out within a second or two. content: application/json: schema: $ref: "#/components/schemas/WebhookDeliveryWithEventResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request (an unknown type) headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "409": description: endpoint_paused, idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: endpoint_paused: summary: endpoint_paused value: error: type: invalid_request_error code: endpoint_paused message: The webhook endpoint is paused. Resume it (POST /webhook_endpoints/{id}/resume), then re-send or send the test event. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - endpoint_paused - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhookEndpointsIdTest parameters: - in: path name: id required: true schema: type: string format: uuid - $ref: "#/components/parameters/IdempotencyKey" /webhooks: get: tags: - Webhooks summary: List webhooks (old) deprecated: true description: Replaced by GET /webhook_endpoints. Still answers its old shape, with a Deprecation header. responses: "200": description: The old list content: application/json: schema: $ref: "#/components/schemas/LegacyResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhooks post: tags: - Webhooks summary: Create a webhook (old) deprecated: true description: Replaced by POST /webhook_endpoints. Still answers its old shape, with a Deprecation header. The secret is in this reply only. Needs the read permission of every event's data, as POST /webhook_endpoints does. requestBody: required: true content: application/json: schema: type: object required: - url - events additionalProperties: false properties: url: type: string events: type: array items: type: string campaignId: type: - string - "null" format: uuid enabled: type: boolean default: true responses: "201": description: Created content: application/json: schema: $ref: "#/components/schemas/LegacyResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" Idempotent-Replayed: $ref: "#/components/headers/Idempotent-Replayed" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied or limit_reached headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c limit_reached: summary: limit_reached value: error: type: invalid_request_error code: limit_reached message: A plan limit was reached (for example, webhook endpoints per organization). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied - limit_reached "409": description: idempotency_mismatch, idempotency_in_progress headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: idempotency_mismatch: summary: idempotency_mismatch value: error: type: idempotency_error code: idempotency_mismatch message: This Idempotency-Key was already used with a different request. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c idempotency_in_progress: summary: idempotency_in_progress value: error: type: idempotency_error code: idempotency_in_progress message: A request with this Idempotency-Key is still running. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - idempotency_mismatch - idempotency_in_progress "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error "503": description: service_unavailable headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: service_unavailable: summary: service_unavailable value: error: type: api_error code: service_unavailable message: A service we depend on is unavailable. Retry later. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - service_unavailable operationId: postWebhooks parameters: - $ref: "#/components/parameters/IdempotencyKey" /webhooks/{id}: delete: tags: - Webhooks summary: Delete a webhook (old) deprecated: true description: Replaced by DELETE /webhook_endpoints/{id}. parameters: - in: path name: id required: true schema: type: string format: uuid responses: "200": description: Deleted content: application/json: schema: $ref: "#/components/schemas/LegacyResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: deleteWebhooksId /webhooks/{id}/deliveries: get: tags: - Webhooks summary: A webhook's deliveries (old) deprecated: true description: Replaced by GET /webhook_endpoints/{id}/deliveries. A delivery's payload is left out unless the key can read that event's data (leads:read or calls:read, or events:read). parameters: - in: path name: id required: true schema: type: string format: uuid - in: query name: limit schema: type: integer minimum: 1 maximum: 100 default: 25 responses: "200": description: The deliveries content: application/json: schema: $ref: "#/components/schemas/LegacyResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "404": description: not_found headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: not_found: summary: not_found value: error: type: invalid_request_error code: not_found message: No such object or endpoint (or it belongs to someone else). param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - not_found "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhooksIdDeliveries /webhooks/events: get: tags: - Webhooks summary: The event catalog (old) deprecated: true description: Every event type with a description and an example. The guide's event reference has the same list. responses: "200": description: The catalog content: application/json: schema: $ref: "#/components/schemas/LegacyResponse" headers: Request-Id: $ref: "#/components/headers/Request-Id" RateLimit-Limit: $ref: "#/components/headers/RateLimit-Limit" RateLimit-Remaining: $ref: "#/components/headers/RateLimit-Remaining" RateLimit-Reset: $ref: "#/components/headers/RateLimit-Reset" "400": description: invalid_request headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: invalid_request: summary: invalid_request value: error: type: invalid_request_error code: invalid_request message: "The request is malformed: a missing or unknown field, a bad value, a body over 1 MB, a batch over 60 leads, or over 100 numbers for Do Not Call." param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - invalid_request "401": description: authentication_failed headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: authentication_failed: summary: authentication_failed value: error: type: authentication_error code: authentication_failed message: The key ID or secret is missing, wrong, revoked, expired or disabled. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - authentication_failed "403": description: permission_denied headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: permission_denied: summary: permission_denied value: error: type: permission_error code: permission_denied message: The key is not allowed to do this. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - permission_denied "429": description: rate_limited, too_many_concurrent_requests headers: Request-Id: $ref: "#/components/headers/Request-Id" Retry-After: $ref: "#/components/headers/Retry-After" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: rate_limited: summary: rate_limited value: error: type: rate_limit_error code: rate_limited message: Too many requests a minute for this key or the organization's plan. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c too_many_concurrent_requests: summary: too_many_concurrent_requests value: error: type: rate_limit_error code: too_many_concurrent_requests message: Too many requests at the same time on this key. Retry after Retry-After seconds. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - rate_limited - too_many_concurrent_requests "500": description: internal_error headers: Request-Id: $ref: "#/components/headers/Request-Id" content: application/json: schema: $ref: "#/components/schemas/PublicError" examples: internal_error: summary: internal_error value: error: type: api_error code: internal_error message: Something went wrong on our side. param: null request_id: req_6f1c2a9b0d3e4f5a6b7c8d9e0f1a2b3c x-error-codes: - internal_error operationId: getWebhooksEvents webhooks: lead.created: post: summary: lead.created description: >- A lead was added: through POST /leads, or one Add Lead in the app. CSV imports do not send it. Sent when: - POST /leads accepted a new lead - A person added one lead in the app operationId: event_lead_created tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: lead.created data: type: object properties: object: $ref: "#/components/schemas/Lead" required: - object example: id: evt_leadcreatedxxxxxxxxxxxxx type: lead.created created: 2026-10-06T16:58:04Z livemode: true api_version: 2026-10-01 data: object: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T16:58:04.000Z status: queued call_now: true place_in_line: null estimated_wait_seconds: null scheduled_for: null scheduled_reason: null held_reason: null callback_at: null late: false attempts: 0 last_outcome: null last_outcome_label: null next_dial_at: null calls: [] livemode: true responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." lead.queued: post: summary: lead.queued description: >- A lead was put in the dialing queue, right after lead.created (or when POST /leads re-queued an existing lead). status says queued, scheduled or held, with scheduled_for. Sent when: - POST /leads accepted a lead - POST /leads re-queued a lead last sent longer ago than the duplicate window operationId: event_lead_queued tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: lead.queued data: type: object properties: object: $ref: "#/components/schemas/Lead" required: - object example: id: evt_leadqueuedxxxxxxxxxxxxxx type: lead.queued created: 2026-10-06T16:58:04Z livemode: true api_version: 2026-10-01 data: object: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T16:58:04.000Z status: queued call_now: true place_in_line: null estimated_wait_seconds: null scheduled_for: null scheduled_reason: null held_reason: null callback_at: null late: false attempts: 0 last_outcome: null last_outcome_label: null next_dial_at: null calls: [] livemode: true responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." lead.interested: post: summary: lead.interested description: >- The AI saw buying intent. intent carries what the lead said (excerpt) and who the call is offered to (the ready SDRs first, else the closers). Sent when: - The AI detected buying intent during the call operationId: event_lead_interested tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: lead.interested data: type: object properties: object: allOf: - $ref: "#/components/schemas/ApiCall" - type: object properties: intent: type: object properties: at: type: string format: date-time excerpt: type: string confidence: type: - number - "null" offered_to: type: array items: type: object properties: id: type: - string - "null" name: type: string role: type: string enum: - sdr - closer required: - intent required: - object example: id: evt_leadinterestedxxxxxxxxxx type: lead.interested created: 2026-10-06T16:59:02Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: in_progress outcome: null outcome_label: null note: null duration_seconds: null started: 2026-10-06T16:58:06.000Z answered: 2026-10-06T16:58:14.000Z ended: null updated: 2026-10-06T16:59:02.000Z handled_by: id: null name: AI role: ai owner: null tth_seconds: null callback_at: null recording_available: false transcript_available: false started_by: type: api api_key_id: key_example intent: at: 2026-10-06T16:59:02.000Z excerpt: Yes, I'd like to hear what it would cost for my house. confidence: 0.92 offered_to: - id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: SDR_NAME role: sdr responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." lead.opted_out: post: summary: lead.opted_out description: >- The lead's number went on the Do Not Call list. opt_out.source says how: api, ai (the AI's tool during the call), outcome (a DNC outcome), manual, bulk or sms (a STOP reply). One event per lead of yours with that number. Sent when: - POST /leads/{id}/opt_out, or the DNC endpoints - The AI took the number off the list on a call - A DNC outcome - Mark DNC, the DNC page or bulk DNC in the app - A STOP reply by text operationId: event_lead_opted_out tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: lead.opted_out data: type: object properties: object: allOf: - $ref: "#/components/schemas/Lead" - type: object properties: opt_out: type: object properties: source: type: string enum: - api - ai - outcome - manual - bulk - sms at: type: string format: date-time required: - opt_out required: - object example: id: evt_leadoptedoutxxxxxxxxxxxx type: lead.opted_out created: 2026-10-06T17:01:40Z livemode: true api_version: 2026-10-01 data: object: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T17:01:40.000Z status: out_of_queue call_now: true place_in_line: null estimated_wait_seconds: null scheduled_for: null scheduled_reason: null held_reason: null callback_at: null late: false attempts: 0 last_outcome: dnc last_outcome_label: DNC next_dial_at: null calls: [] livemode: true opt_out: source: ai at: 2026-10-06T17:01:40.000Z responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." lead.late: post: summary: lead.late description: >- A speed-to-lead lead was still waiting for its call after the campaign's late minutes (default 15). It is still called; late is true. Sent when: - The late sweep stamped the lead (every 30 s) operationId: event_lead_late tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: lead.late data: type: object properties: object: $ref: "#/components/schemas/Lead" required: - object example: id: evt_leadlatexxxxxxxxxxxxxxxx type: lead.late created: 2026-10-06T17:13:04Z livemode: true api_version: 2026-10-01 data: object: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T17:13:04.000Z status: queued call_now: true place_in_line: null estimated_wait_seconds: null scheduled_for: null scheduled_reason: null held_reason: null callback_at: null late: true attempts: 0 last_outcome: null last_outcome_label: null next_dial_at: null calls: [] livemode: true responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." call.started: post: summary: call.started description: |- A call to the lead started dialing (the call record exists). Sent when: - The dialer, speed to lead, POST /calls or a person dialed the lead operationId: event_call_started tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: call.started data: type: object properties: object: $ref: "#/components/schemas/ApiCall" required: - object example: id: evt_callstartedxxxxxxxxxxxxx type: call.started created: 2026-10-06T16:58:06Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: ringing outcome: null outcome_label: null note: null duration_seconds: null started: 2026-10-06T16:58:06.000Z answered: null ended: null updated: 2026-10-06T16:58:06.000Z handled_by: id: null name: AI role: ai owner: null tth_seconds: null callback_at: null recording_available: false transcript_available: false started_by: type: api api_key_id: key_example responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." call.answered: post: summary: call.answered description: >- The far end picked up. answered_by is person, machine (a voicemail box or a phone menu) or unknown (nothing checked). Sent when: - The answering-machine check decided - The voicemail detector decided (or 20 s passed with no mailbox) - A person on our side picked the call up directly operationId: event_call_answered tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: call.answered data: type: object properties: object: allOf: - $ref: "#/components/schemas/ApiCall" - type: object properties: answered_by: type: string enum: - person - machine - unknown required: - answered_by required: - object example: id: evt_callansweredxxxxxxxxxxxx type: call.answered created: 2026-10-06T16:58:14Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: in_progress outcome: null outcome_label: null note: null duration_seconds: null started: 2026-10-06T16:58:06.000Z answered: 2026-10-06T16:58:14.000Z ended: null updated: 2026-10-06T16:58:14.000Z handled_by: id: null name: AI role: ai owner: null tth_seconds: null callback_at: null recording_available: false transcript_available: false started_by: type: api api_key_id: key_example answered_by: person responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." call.completed: post: summary: call.completed description: >- The outcome is final: outcome, the note, duration, handled_by, owner, and the API paths for the recording and transcript. An AI-only call sends it after the after-call check; a call a person handled sends it when they file the outcome (or after 10 minutes with none: outcome other, note "No outcome was filed"). A later correction sends it again with the same id, a newer updated and revision 2, 3 ... Sent when: - The after-call check filed an AI-only call's outcome - A person filed the outcome - 10 minutes passed with no outcome filed - The outcome was corrected later operationId: event_call_completed tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: call.completed data: type: object properties: object: allOf: - $ref: "#/components/schemas/ApiCall" - type: object properties: revision: type: integer minimum: 1 recording_path: type: - string - "null" description: GET it for a 5-minute recording link transcript_path: type: - string - "null" required: - revision - recording_path - transcript_path required: - object example: id: evt_callcompletedxxxxxxxxxxx type: call.completed created: 2026-10-06T17:05:20Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: ended outcome: interested outcome_label: Interested note: Wants a quote for a 6 kW system; home owner, roof replaced 2019. duration_seconds: 412 started: 2026-10-06T16:58:06.000Z answered: 2026-10-06T16:58:14.000Z ended: 2026-10-06T17:04:58.000Z updated: 2026-10-06T17:05:20.000Z handled_by: id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: SDR_NAME role: sdr owner: null tth_seconds: 9.3 callback_at: null recording_available: true transcript_available: true started_by: type: api api_key_id: key_example revision: 1 recording_path: /api/v1/external/calls/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/recording transcript_path: /api/v1/external/calls/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/transcript responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." handover.accepted: post: summary: handover.accepted description: >- A person took the call: handled_by names them (an SDR or a closer), tth_seconds is how long it took from the intent. Sent when: - An SDR bridged or took over the call - A closer pressed 1 operationId: event_handover_accepted tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: handover.accepted data: type: object properties: object: $ref: "#/components/schemas/ApiCall" required: - object example: id: evt_handoveracceptedxxxxxxxx type: handover.accepted created: 2026-10-06T16:59:11Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: in_progress outcome: null outcome_label: null note: null duration_seconds: null started: 2026-10-06T16:58:06.000Z answered: 2026-10-06T16:58:14.000Z ended: null updated: 2026-10-06T16:59:11.300Z handled_by: id: 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d name: SDR_NAME role: sdr owner: null tth_seconds: 9.3 callback_at: null recording_available: false transcript_available: false started_by: type: api api_key_id: key_example responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." voicemail.left: post: summary: voicemail.left description: >- A voicemail was delivered. Never sent for a message that was not delivered. Sent when: - The voicemail agent reported the message delivered, confirmed after the call operationId: event_voicemail_left tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: voicemail.left data: type: object properties: object: $ref: "#/components/schemas/ApiCall" required: - object example: id: evt_voicemailleftxxxxxxxxxxx type: voicemail.left created: 2026-10-06T16:58:54Z livemode: true api_version: 2026-10-01 data: object: id: e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b object: call livemode: true lead: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 name: LEAD_NAME phone: "+15555550142" campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 direction: outbound status: ended outcome: voicemail outcome_label: Voicemail note: null duration_seconds: 48 started: 2026-10-06T16:58:06.000Z answered: null ended: 2026-10-06T16:58:54.000Z updated: 2026-10-06T16:58:54.000Z handled_by: id: null name: AI role: ai owner: null tth_seconds: null callback_at: null recording_available: false transcript_available: false started_by: type: api api_key_id: key_example responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours." callback.booked: post: summary: callback.booked description: >- A day and time to call the lead back was booked. callback.at is UTC; callback.timezone is the lead's. Sent when: - The AI booked it on the call - Nobody took an interested lead and it was filed as a callback - A person booked it operationId: event_callback_booked tags: - Events security: [] parameters: - in: header name: CallView-Signature required: true description: "Our signature: t=,v1=.\" with your endpoint's secret>. During a secret roll there are two v1 values. Check it before you trust the body (see the Webhooks guide)." schema: type: string example: t=1791306131,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd requestBody: required: true content: application/json: schema: allOf: - $ref: "#/components/schemas/Event" - type: object properties: type: type: string const: callback.booked data: type: object properties: object: allOf: - $ref: "#/components/schemas/Lead" - type: object properties: callback: type: object properties: at: type: string format: date-time timezone: type: - string - "null" required: - callback required: - object example: id: evt_callbackbookedxxxxxxxxxx type: callback.booked created: 2026-10-06T17:02:10Z livemode: true api_version: 2026-10-01 data: object: id: 2b8e4c1d-9f3a-4b7e-8c21-6a5d4e3f2b10 external_id: crm-10442 campaign_id: 7c1f2b9e-4a3d-4e8f-9b21-5d6a7e8f9a01 name: LEAD_NAME phone: "+15555550142" email: lead@example.com address: 1 Example Street, Springfield fields: roof_age: "12" consent: source: web_form agreed_at: 2026-10-06T16:58:02Z url: https://example.com/quote lead_source: Example CRM owner: null created: 2026-10-06T16:58:04.000Z updated: 2026-10-06T17:02:10.000Z status: callback_scheduled call_now: true place_in_line: null estimated_wait_seconds: null scheduled_for: null scheduled_reason: null held_reason: null callback_at: 2026-10-07T18:30:00.000Z late: false attempts: 0 last_outcome: null last_outcome_label: null next_dial_at: null calls: [] livemode: true callback: at: 2026-10-07T18:30:00.000Z timezone: America/New_York responses: "200": description: "Answer with any 2xx within 10 seconds. Anything else, or no answer in time, is tried again: 7 tries over 24 hours."