{ "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\nfor the next page. Needs calls:read; a key limited to some campaigns\nsees only their calls.\n\nDeprecated for one release: offset and status (and a limit over\n100) still answer the old list shape, with a Deprecation header.\n", "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\n(the same queue as POST /leads with call_now): it is dialed next,\nnever above the campaign's lines. The same checks and the same reply\nas POST /leads: dialing, queued (with the place in line), scheduled\n(outside the lead's calling hours) or held (a paused campaign).\nDo Not Call, calling hours and the other dialing rules always apply.\nAt most 3 API-started calls per lead in 24 hours. Needs calls:write.\n", "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\nlink is a signed storage URL that stops working at expires_at.\n404 recording_not_available when there is none (recording is off\nfor your organization, or it is past retention). Needs calls:read.\n", "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\nthe call), with a name and a time. ?format=text answers plain text,\none \"Name: text\" line per turn. Needs calls:read.\n", "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.\nLead: 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\ngiven). A live key gets the older lead shape here; GET /leads with\ncampaign_id gives the lead object and is the one to use for new work.\nNeeds leads:read.\n", "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\ndraft or paused. A test key changes nothing and answers what the status\nwould be. Needs campaigns:write.\n", "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.\n", "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.\n", "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\nleads:read and calls:read, on a key for every campaign. A test key gets\na sample file.\n", "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\ncampaign's retired numbers, duplicates (by external_id or phone),\nconsent if the campaign asks for it, number rules (no premium or\ninternational numbers) and the 5,000 waiting-lead limit. If it passes,\nthe lead goes straight into the campaign's dial queue.\n\nA call_now lead is dialed before the campaign's other leads, oldest\nfirst, as the campaign's lines free up. Outside the lead's calling\nhours it is scheduled for the next window. A paused or not-started\ncampaign holds the lead and dials it when the campaign runs, and so\ndoes a reached spend cap. A refused lead isn't saved. place_in_line\nand estimated_wait_seconds are estimates.\n\nWith dry_run true every check runs and the lead isn't saved. Needs\nleads:write.\n", "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 }`.\nexternal_id is unique per campaign, not per organization: a match in\ntwo of the key's campaigns is 409 ambiguous_external_id with\n`candidates` ([{ id, campaign_id }]); add campaign_id to pick one.\n\nWithout it: the key's leads, newest first, keyset-paged\n(`starting_after` = the last lead's id), as\n`{ data: [lead], meta: { next_cursor, has_more } }`. With a status\nfilter a page can hold fewer than `limit` leads while has_more is\ntrue; keep paging with next_cursor. place_in_line is only given on\na single-lead read.\n\nstatus is one of: new, queued, scheduled, held, dialing, on_call,\ncallback_scheduled, done, out_of_queue.\n", "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,\nemail, address, fields, consent, lead_source, owner ({ id, name } of\nthe SDR its latest call was dialed for, or null), created, updated,\nstatus, call_now, place_in_line and estimated_wait_seconds (while\nqueued; estimates), scheduled_for, scheduled_reason, held_reason,\ncallback_at, late, attempts, last_outcome (a stable word, the\nsame as the call object's outcome) and last_outcome_label (your\norganization's name for it), next_dial_at, and calls (the last 10,\nnewest first: { id, started, outcome, outcome_label, duration_seconds }).\n\nstatus: new (not yet queued), queued (due now), scheduled (waits\nfor scheduled_for: calling hours, a cooldown, a retry), held\n(held_reason: campaign_paused, campaign_not_started,\nspend_cap_reached), dialing, on_call, callback_scheduled\n(callback_at), done (finished, not coming back), out_of_queue\n(taken out, opted out or on the Do Not Call list).\n\nA lead in a campaign outside the key's, in another organization, or\nremoved is 404 not_found.\n", "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\nsent as \"\" is removed; other keys are kept), consent (replaced),\nexternal_id (only while the lead has none), call_now: false (drops\nthe speed-to-lead priority). The phone can't be changed\n(phone_cannot_change): add a new lead instead. Answers the updated\nlead. Idempotency-Key is honoured.\n", "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\n\"API\"), so no campaign of the organization dials it again; the lead\nleaves the queue with the DNC outcome and its open callbacks are\nclosed. A call in progress is NOT cut: the reply says\ncall_in_progress true, and nothing dials the number again.\nIdempotent: a second opt_out answers the same, with no second Do\nNot Call entry. Answers the updated lead plus call_in_progress.\n", "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\nthe order you sent them. A lead that fails doesn't stop the others.\ncampaign_id may be on each lead or once for the batch. Each lead\ncounts toward the key's new leads a minute. Needs leads:write.\n", "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.\n", "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.\n", "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\ninternet. The endpoint's mode is the key's: a test key's endpoint gets\ntest events only. The secret (whsec_...) is in this reply only. Every\ndelivery is signed with it in the CallView-Signature header (see the\nWebhooks guide). At most 10 endpoints per organization. Needs\nwebhooks:write, plus the read permission of every event's data:\nleads:read for lead.created, lead.queued, lead.opted_out, lead.late\nand callback.booked; calls:read for call.*, lead.interested,\nhandover.accepted and voicemail.left (403 permission_denied names\nthe one missing).\n", "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\nendpoint: its status, how many tries (7 at most, over 24 hours), your\nlast answer (the first 4 KB) and the times. Newest first, page by page\n(starting_after = the next_cursor you were given). Needs webhooks:read.\n", "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\nin the header) for grace_hours, so you can switch over without missing\nanything. Needs webhooks:write.\n", "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\nyour receiver. It is the event's example in a real envelope with a new\nevt_ id, livemode false and \"sample\": true, signed with this endpoint's\nsecret just like a real delivery, and retried like one. It shows in the\nendpoint's deliveries. It is not an event, so GET /events doesn't list\nit. A paused endpoint has to be resumed first. Needs webhooks:write.\n", "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.\n\nSent when:\n\n- POST /leads accepted a new lead\n- 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.\n\nSent when:\n\n- POST /leads accepted a lead\n- 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).\n\nSent when:\n\n- 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.\n\nSent when:\n\n- POST /leads/{id}/opt_out, or the DNC endpoints\n- The AI took the number off the list on a call\n- A DNC outcome\n- Mark DNC, the DNC page or bulk DNC in the app\n- 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.\n\nSent when:\n\n- 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).\n\nSent when:\n\n- 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).\n\nSent when:\n\n- The answering-machine check decided\n- The voicemail detector decided (or 20 s passed with no mailbox)\n- 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 ...\n\nSent when:\n\n- The after-call check filed an AI-only call's outcome\n- A person filed the outcome\n- 10 minutes passed with no outcome filed\n- 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.\n\nSent when:\n\n- An SDR bridged or took over the call\n- 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.\n\nSent when:\n\n- 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.\n\nSent when:\n\n- The AI booked it on the call\n- Nobody took an interested lead and it was filed as a callback\n- 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." } } } } } }