{ "openapi": "3.1.0", "info": { "title": "Senders REST API", "version": "1.5.0", "description": "Read your Senders lead lists, leads, campaigns, prospects, mailbox status and email replies; add leads to lists and campaigns and manage Do Not Contact; search for people and buy their contact details; get every new reply as a signed webhook. Only the prospecting endpoints spend credits, always within max_spend_credits and the account daily API spend cap. Human docs: https://senders.ai/api-docs", "contact": { "email": "support@senders.co" } }, "servers": [ { "url": "https://mcp.senders.ai/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Leads" }, { "name": "Replies" }, { "name": "Campaigns" }, { "name": "Prospects" }, { "name": "Mailboxes" }, { "name": "Suppression" }, { "name": "Prospecting" }, { "name": "Webhooks" } ], "paths": { "/lists": { "get": { "tags": [ "Leads" ], "operationId": "listLists", "summary": "Your lead lists, newest first", "description": "Scope: leads:read", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/List" } } } } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Leads" ], "operationId": "createList", "summary": "Create a lead list", "description": "Scope: leads:write. Up to 1,000 lists per account.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreate" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "lead_count": { "type": "integer" } } } } } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lists/{id}/leads": { "get": { "tags": [ "Leads" ], "operationId": "listLeads", "summary": "Leads in a list, oldest first, cursor-paged", "description": "Scope: leads:read. format=csv returns text/csv with X-Has-More and X-Next-Cursor headers.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List id", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1-500", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page; omit for the first page", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Only items added at or after this time (UTC). YYYY-MM-DD or ISO 8601.", "schema": { "type": "string", "examples": [ "2026-10-01", "2026-10-01T09:00:00Z" ] } }, { "name": "max_priority", "in": "query", "required": false, "description": "Only leads with research priority 1..N", "schema": { "type": "integer", "minimum": 1 } }, { "name": "format", "in": "query", "required": false, "description": "csv for a CSV download", "schema": { "type": "string", "enum": [ "csv" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadPage" } }, "text/csv": { "schema": { "type": "string" } } } }, "404": { "description": "No such list on this account (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid parameter (bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Leads" ], "operationId": "addListLeads", "summary": "Add up to 500 leads to a list", "description": "Scope: leads:write. Invalid, personal-domain and duplicate leads are skipped and counted.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "List id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAddResult" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such list on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/leads/{id}": { "get": { "tags": [ "Leads" ], "operationId": "getLead", "summary": "One lead", "description": "Scope: leads:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Lead" } } } } } }, "404": { "description": "No such lead on this account (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/replies": { "get": { "tags": [ "Replies" ], "operationId": "listReplies", "summary": "Inbound email replies, newest first (order=asc for syncing), cursor-paged", "description": "Scope: replies:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Items per page, 1-500", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page; omit for the first page", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "desc (default): newest first, cursor pages to older replies. asc: oldest first, the saved cursor returns only newer replies.", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "since", "in": "query", "required": false, "description": "Only items received at or after this time (UTC). YYYY-MM-DD or ISO 8601.", "schema": { "type": "string", "examples": [ "2026-10-01", "2026-10-01T09:00:00Z" ] } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only replies to this campaign", "schema": { "type": "integer" } }, { "name": "sentiment", "in": "query", "required": false, "description": "Filter by sentiment", "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "auto_reply" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyPage" } } } }, "400": { "description": "Invalid parameter (bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns": { "get": { "tags": [ "Campaigns" ], "operationId": "listCampaigns", "summary": "Campaigns with stats, newest first", "description": "Scope: campaigns:read. Archived campaigns only with status=archived. Stats refresh at most once a minute.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Campaigns per page, 1-50", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page; omit for the first page", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "desc (default): newest first, cursor pages to older. asc: oldest first, cursor returns only newer (for syncing).", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "archived" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid parameter (bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "operationId": "getCampaign", "summary": "One campaign with stats and per-step counts", "description": "Scope: campaigns:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CampaignDetail" } } } } } }, "404": { "description": "No such campaign on this account (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospects": { "get": { "tags": [ "Prospects" ], "operationId": "listProspects", "summary": "Prospects, newest first, cursor-paged", "description": "Scope: prospects:read", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Prospects per page, 1-500", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page; omit for the first page", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "desc (default): newest first, cursor pages to older. asc: oldest first, cursor returns only newer (for syncing).", "schema": { "type": "string", "enum": [ "desc", "asc" ], "default": "desc" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only this campaign", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Prospect status", "schema": { "type": "string", "enum": [ "pending", "contacted", "replied", "bounced", "unsubscribed", "dnc", "held", "meeting_booked" ] } }, { "name": "lead_status", "in": "query", "required": false, "description": "Lead status", "schema": { "type": "string", "enum": [ "interested", "meeting_booked", "not_interested", "out_of_office", "wrong_person", "closed" ] } }, { "name": "since", "in": "query", "required": false, "description": "Only prospects added at or after this time (UTC)", "schema": { "type": "string", "examples": [ "2026-10-01", "2026-10-01T09:00:00Z" ] } }, { "name": "replied_since", "in": "query", "required": false, "description": "Only prospects who replied at or after this time (UTC)", "schema": { "type": "string", "examples": [ "2026-10-01", "2026-10-01T09:00:00Z" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Prospect" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid parameter (bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospects/{id}": { "get": { "tags": [ "Prospects" ], "operationId": "getProspect", "summary": "One prospect", "description": "Scope: prospects:read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Prospect id", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Prospect" } } } } } }, "404": { "description": "No such prospect on this account (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mailboxes": { "get": { "tags": [ "Mailboxes" ], "operationId": "listMailboxes", "summary": "Sending mailboxes: status and 7-day health, never credentials", "description": "Scope: mailboxes:read. Retired mailboxes are left out. Refreshed at most once a minute.", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } } } } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{id}/leads": { "post": { "tags": [ "Campaigns" ], "operationId": "enrollLeads", "summary": "Add up to 500 people to a campaign", "description": "Scope: leads:write. Active campaign: step 1 is scheduled immediately. People already known to the account are skipped with a reason (never moved or re-contacted). 2,000 per account per UTC day.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "description": "Campaign id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollResult" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such campaign on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/suppressions": { "post": { "tags": [ "Suppression" ], "operationId": "addSuppressions", "summary": "Add up to 100 addresses to Do Not Contact", "description": "Scope: suppression:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionsBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionsResult" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/suppressions/{email}": { "delete": { "tags": [ "Suppression" ], "operationId": "removeSuppression", "summary": "Lift a hand-added Do Not Contact entry", "description": "Scope: suppression:write. Bounces, spam complaints, opt-outs and failed verifications return 409 protected_suppression.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "email", "in": "path", "required": true, "description": "Address (URL-encoded)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "email": { "type": "string" }, "removed": { "type": "boolean" }, "still_globally_suppressed": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on the list (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/suppressions/domains": { "post": { "tags": [ "Suppression" ], "operationId": "addDomainBlocks", "summary": "Block up to 100 domains (Do Not Prospect)", "description": "Scope: suppression:write. Personal email domains are refused.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainsResult" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/suppressions/domains/{domain}": { "delete": { "tags": [ "Suppression" ], "operationId": "removeDomainBlock", "summary": "Unblock a domain", "description": "Scope: suppression:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "domain", "in": "path", "required": true, "description": "Domain", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domain": { "type": "string" }, "removed": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not on the list (not_found)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospecting/search": { "post": { "tags": [ "Prospecting" ], "operationId": "searchPeople", "summary": "Queue a people search (free, asynchronous)", "description": "Scope: prospecting:run. Always answers 202 with a job_id; fetch GET /prospecting/jobs/{id}. At most 5 searches waiting per account (429 too_many_searches_queued).", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchBody" } } } }, "responses": { "202": { "description": "Queued", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuedSearch" } } } }, "400": { "description": "bad_request, idempotency_key_required or max_spend_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospecting/enrich": { "post": { "tags": [ "Prospecting" ], "operationId": "enrichPeople", "summary": "Get emails for up to 10 contacts (spends credits)", "description": "Scope: prospecting:run. 1 credit per contact found; 0 for contacts already bought or not found. Never more than max_spend_credits, never past the daily API spend cap.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionsResult" } } } }, "400": { "description": "bad_request, idempotency_key_required or max_spend_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "spend_cap_reached or estimate_exceeds_max_spend: refused before anything was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospecting/acquire": { "post": { "tags": [ "Prospecting" ], "operationId": "acquirePeople", "summary": "Enrich up to 10 contacts and add them to a list (spends credits)", "description": "Scope: prospecting:run. As enrich, plus everyone found with an email is added to list_id.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquireBody" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" }, "X-RateLimit-Write-Limit": { "schema": { "type": "integer" }, "description": "Write requests per minute per token" }, "X-RateLimit-Write-Remaining": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuppressionsResult" } } } }, "400": { "description": "bad_request, idempotency_key_required or max_spend_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "spend_cap_reached or estimate_exceeds_max_spend: refused before anything was charged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such list on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospecting/quote": { "get": { "tags": [ "Prospecting" ], "operationId": "quoteEnrichment", "summary": "Price of enriching N contacts, and what is left of the API spend cap", "description": "Scope: prospecting:run. Free; nothing is reserved.", "parameters": [ { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid parameter (bad_request)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prospecting/jobs/{id}": { "get": { "tags": [ "Prospecting" ], "operationId": "getSearchJob", "summary": "Result of a queued search", "description": "Scope: prospecting:run", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "queued_at": { "type": [ "string", "null" ], "format": "date-time" }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/SearchPerson" } }, "total": { "type": "integer" }, "dnp_filtered": { "type": "integer" }, "credits_charged": { "type": "integer" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "No such job on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhooks", "summary": "Your reply webhook endpoints", "description": "Scope: webhooks:manage", "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhook", "summary": "Add a reply webhook endpoint", "description": "Scope: webhooks:manage. Returns the signing secret ONCE. Up to 5 per account.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string" } } } ] }, "note": { "type": "string" } } } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhook", "summary": "Delete an endpoint", "description": "Scope: webhooks:manage. Pending deliveries to it are dropped.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } } } } } } } }, "404": { "description": "No such webhook on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhook", "summary": "Send a signed test delivery now", "description": "Scope: webhooks:manage. 5 a minute per account.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "http_status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "delivery_id": { "type": [ "string", "null" ] } } } } } } } }, "404": { "description": "No such webhook on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "New signing secret", "description": "Scope: webhooks:manage. Returned once. The old secret keeps signing X-Senders-Signature-Previous for 24 hours.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "secret": { "type": "string" }, "previous_secret_valid_until": { "type": "string", "format": "date-time" } } }, "note": { "type": "string" } } } } } }, "404": { "description": "No such webhook on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/enable": { "post": { "tags": [ "Webhooks" ], "operationId": "enableWebhook", "summary": "Turn an endpoint back on", "description": "Scope: webhooks:manage. Also resets its failure count.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "404": { "description": "No such webhook on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "Delivery log, newest first (30 days)", "description": "Scope: webhooks:manage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed", "dead" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "No such webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token (unauthorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing scope (forbidden), paused account (account_inactive) or plan without the API (feature_not_enabled)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (rate_limited, daily_limit). Wait Retry-After seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/deliveries/{delivery_id}/redeliver": { "post": { "tags": [ "Webhooks" ], "operationId": "redeliverWebhook", "summary": "Send a failed or dead delivery again", "description": "Scope: webhooks:manage. 100 a day per account; 409 not_redeliverable for other states.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Per-token requests per minute" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this minute for this token" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time when the minute window resets" }, "X-RateLimit-Daily-Limit": { "schema": { "type": "integer" }, "description": "Account requests per UTC day" }, "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" }, "description": "Requests left today for the account" }, "X-Request-Id": { "schema": { "type": "string" }, "description": "Quote this to support" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "404": { "description": "No such webhook on this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Invalid body or missing Idempotency-Key (bad_request, idempotency_key_required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, wrong or revoked token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing write permission, inactive account, or feature not enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "busy, conflict, idempotency_in_progress (retry) or a final conflict such as campaign_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 1 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Body not JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or daily limit", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Writes paused because rate limiting is unavailable; retry after Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token from Settings > API (starts with snd_live_). Header only." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "account_inactive", "feature_not_enabled", "not_found", "method_not_allowed", "rate_limited", "daily_limit", "busy", "payload_too_large", "unsupported_media_type", "service_unavailable", "idempotency_key_required", "idempotency_key_reused", "idempotency_in_progress", "internal_error", "conflict", "campaign_closed", "protected_suppression", "limit_reached", "daily_enroll_limit", "max_spend_required", "spend_cap_reached", "estimate_exceeds_max_spend", "search_busy", "too_many_searches_queued", "invalid_url", "not_redeliverable" ] }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } }, "List": { "type": "object", "required": [ "id", "name", "lead_count" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "lead_count": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "Outreach": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_contacted", "pending", "contacted", "replied", "bounced", "unsubscribed", "dnc", "held", "meeting_booked" ] }, "lead_status": { "type": [ "string", "null" ], "enum": [ "interested", "meeting_booked", "not_interested", "out_of_office", "wrong_person", "closed", null ] }, "reply_sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "negative", "neutral", "auto_reply", null ] }, "last_contacted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "replied_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "Lead": { "type": "object", "required": [ "id", "list_id", "email_status", "contact_channel", "outreach" ], "properties": { "id": { "type": "integer" }, "list_id": { "type": "integer" }, "priority": { "type": [ "integer", "null" ], "description": "1 = best" }, "segment": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "signal_summary": { "type": [ "string", "null" ] }, "reach": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "email_status": { "type": "string", "enum": [ "verified", "catch_all", "risky", "invalid", "personal", "unverified", "none" ] }, "contact_channel": { "type": "string", "enum": [ "email", "linkedin", "form", "dm", "mgmt", "other", "none" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "alt_contact": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "outreach": { "$ref": "#/components/schemas/Outreach" }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "Reply": { "type": "object", "required": [ "id", "thread_id", "channel", "received_at", "lead" ], "properties": { "id": { "type": "integer" }, "thread_id": { "type": "integer" }, "channel": { "type": "string", "enum": [ "email" ] }, "received_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "negative", "neutral", "auto_reply", null ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": "string", "description": "Plain text of the new message, quoted history removed. Taken from the stored text part, else the HTML part, else the text saved on the original send. If removing quoted history would leave nothing, the whole message is returned instead. Empty only when no text was stored at all. Byte order marks and leading blank lines are removed." }, "body_html": { "type": [ "string", "null" ], "description": "Sanitized HTML of the new message (allowlisted tags, scripts and remote images removed, quoted chain dropped). Null when the reply had no HTML part or it could not be sanitized." }, "lead": { "type": "object", "properties": { "prospect_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "lead_status": { "type": [ "string", "null" ] } } }, "campaign": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] } } } ] } } }, "LeadPage": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor after the last item. Save it to resume; null only when the page is empty and no cursor was sent." } } }, "ReplyPage": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reply" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor after the last item. Save it to resume; null only when the page is empty and no cursor was sent." } } }, "CampaignStats": { "type": "object", "properties": { "prospects": { "type": "integer" }, "contacted": { "type": "integer", "description": "Prospects sent at least one email" }, "sent": { "type": "integer", "description": "Emails that left; our replies not counted" }, "delivered": { "type": "integer", "description": "sent minus bounced" }, "bounced": { "type": "integer", "description": "Prospects whose email bounced" }, "replied": { "type": "integer", "description": "Prospects who replied" }, "positive_replies": { "type": "integer" }, "meetings_booked": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "opened": { "type": [ "integer", "null" ], "description": "null = not measured" }, "clicked": { "type": [ "integer", "null" ], "description": "null = not measured" }, "reply_rate": { "type": [ "number", "null" ], "description": "replied / contacted, percent" }, "bounce_rate": { "type": [ "number", "null" ], "description": "bounced / sent, percent" } } }, "Campaign": { "type": "object", "required": [ "id", "name", "status", "type", "stats" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "completed", "archived" ] }, "type": { "type": "string", "enum": [ "single_step", "multi_step" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "stats": { "$ref": "#/components/schemas/CampaignStats" } } }, "CampaignStep": { "type": "object", "properties": { "step": { "type": "integer" }, "delay_days": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "scheduled": { "type": "integer" }, "sent": { "type": "integer" }, "pending": { "type": "integer" }, "skipped": { "type": "integer" }, "failed": { "type": "integer" } } }, "CampaignDetail": { "allOf": [ { "$ref": "#/components/schemas/Campaign" }, { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStep" } } } } ] }, "Prospect": { "type": "object", "required": [ "id", "email", "status" ], "properties": { "id": { "type": "integer" }, "campaign_id": { "type": [ "integer", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "name": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "contacted", "replied", "bounced", "unsubscribed", "dnc", "held", "meeting_booked" ] }, "lead_status": { "type": [ "string", "null" ], "enum": [ "interested", "meeting_booked", "not_interested", "out_of_office", "wrong_person", "closed", null ] }, "reply_sentiment": { "type": [ "string", "null" ], "enum": [ "positive", "negative", "neutral", "auto_reply", null ] }, "last_contacted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "replied_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "Mailbox": { "type": "object", "required": [ "id", "email", "status" ], "properties": { "id": { "type": "integer" }, "email": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "warming", "active", "paused", "disconnected" ] }, "role": { "type": "string", "enum": [ "primary", "backup" ] }, "provider": { "type": "string", "enum": [ "imap", "gmail", "outlook", "unipile", "nylas", "smtp" ] }, "connection": { "type": "string", "enum": [ "ok", "auth_failed" ] }, "daily_limit": { "type": "integer" }, "target_daily_limit": { "type": "integer" }, "warmup_day": { "type": "integer" }, "warming_external": { "type": "boolean" }, "send_interval_minutes": { "type": "integer" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "last_reply_check_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" }, "sent_7d": { "type": "integer" }, "bounced_7d": { "type": "integer" }, "bounce_rate_7d": { "type": [ "number", "null" ] }, "health": { "type": "string", "enum": [ "good", "warning", "critical" ] } } }, "LeadInput": { "type": "object", "required": [], "properties": { "email": { "type": "string", "format": "email", "maxLength": 253, "description": "Required for campaigns" }, "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "title": { "type": "string", "maxLength": 200 }, "organization": { "type": "string", "maxLength": 200 }, "linkedin_url": { "type": "string", "maxLength": 500 }, "timezone": { "type": "string", "description": "IANA name, campaigns only" }, "custom_fields": { "type": "object", "maxProperties": 50, "description": "Up to 50 keys ([A-Za-z0-9_]{1,64}), scalar values, 16 KB total", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } }, "additionalProperties": false }, "LeadsBody": { "type": "object", "required": [ "leads" ], "properties": { "leads": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/LeadInput" } } } }, "ListCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "notes": { "type": "string", "maxLength": 2000 } } }, "ListAddResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "list_id": { "type": "integer" }, "added": { "type": "integer" }, "skipped": { "type": "object", "properties": { "duplicate": { "type": "integer" }, "invalid_email": { "type": "integer" }, "personal_domain": { "type": "integer" } } } } } } }, "EnrollResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "campaign_id": { "type": "integer" }, "added": { "type": "integer" }, "scheduled": { "type": "integer" }, "skipped_count": { "type": "integer" }, "skipped_reasons": { "type": "object", "additionalProperties": { "type": "integer" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "reason": { "type": "string", "enum": [ "already_in_campaign", "in_other_campaign", "previously_contacted", "previously_replied", "on_hold", "suppressed", "do_not_prospect", "personal_domain", "duplicate_in_request" ] } } } }, "note": { "type": "string" } } } } }, "SuppressionsBody": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "email" } }, "reason": { "type": "string", "enum": [ "manual", "unsubscribe" ], "default": "manual" } } }, "SuppressionsResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "added": { "type": "integer" }, "already_suppressed": { "type": "integer" }, "invalid": { "type": "array", "items": { "type": "string" } }, "not_processed": { "type": "array", "items": { "type": "string" }, "description": "Not reached within the time budget; send again" } } } } }, "DomainsBody": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "string" }, { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "reason": { "type": "string", "enum": [ "competitor", "customer", "partner", "client_account", "other" ] }, "company_name": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 500 } } } ] } } } }, "DomainsResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blocked": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "reason": { "type": "string", "enum": [ "invalid_domain", "consumer_domain" ] } } } } } } } }, "SearchBody": { "type": "object", "properties": { "titles": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "seniorities": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "locations": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "company_size": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "hq_locations": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "exclude_hq_locations": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "industries": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "exclude_industries": { "type": "array", "maxItems": 20, "items": { "type": "string", "maxLength": 100 } }, "domain": { "type": "string", "maxLength": 253 }, "per_page": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, "description": "At least one filter is required." }, "SearchPerson": { "type": "object", "properties": { "contact_id": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name_hint": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "employee_count": { "type": [ "integer", "null" ] }, "location": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "has_email": { "type": "boolean" } } }, "SearchResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "$ref": "#/components/schemas/SearchPerson" } }, "total": { "type": "integer" }, "dnp_filtered": { "type": "integer" }, "credits_charged": { "type": "integer" } } } } }, "QueuedSearch": { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued" ] }, "message": { "type": "string" } } } } }, "EnrichBody": { "type": "object", "required": [ "contact_ids", "max_spend_credits" ], "properties": { "contact_ids": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9_\\-]{1,64}$" } }, "max_spend_credits": { "type": "integer", "minimum": 1, "description": "Hard limit for this request. Must not exceed what is left of the API spend cap today." } } }, "AcquireBody": { "allOf": [ { "$ref": "#/components/schemas/EnrichBody" }, { "type": "object", "required": [ "list_id" ], "properties": { "list_id": { "type": "integer", "description": "One of your people lists" } } } ] }, "EnrichedPerson": { "type": "object", "properties": { "contact_id": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "email_status": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "credits_charged": { "type": "integer" } } }, "EnrichResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "$ref": "#/components/schemas/EnrichedPerson" } }, "credits_charged": { "type": "integer" }, "max_spend_credits": { "type": "integer" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_found_or_unavailable", "error" ] } } } }, "not_processed": { "type": "array", "items": { "type": "string" } }, "stopped_because": { "type": [ "string", "null" ], "enum": [ "max_spend_reached", "insufficient_credits", "time_budget", null ] }, "api_cap_remaining": { "type": "integer" } } } } }, "AcquireResult": { "type": "object", "properties": { "data": { "type": "object", "properties": { "people": { "type": "array", "items": { "$ref": "#/components/schemas/EnrichedPerson" } }, "credits_charged": { "type": "integer" }, "max_spend_credits": { "type": "integer" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_found_or_unavailable", "error" ] } } } }, "not_processed": { "type": "array", "items": { "type": "string" } }, "stopped_because": { "type": [ "string", "null" ], "enum": [ "max_spend_reached", "insufficient_credits", "time_budget", null ] }, "api_cap_remaining": { "type": "integer" }, "list": { "type": "object", "properties": { "list_id": { "type": "integer" }, "added": { "type": "integer" }, "skipped": { "type": "object", "properties": { "duplicate": { "type": "integer" }, "personal_domain": { "type": "integer" }, "invalid_email": { "type": "integer" } } }, "error": { "type": "string" } } } } } } }, "Quote": { "type": "object", "properties": { "data": { "type": "object", "properties": { "contacts": { "type": "integer" }, "credits_per_contact": { "type": "integer" }, "max_credits": { "type": "integer" }, "note": { "type": "string" }, "api_daily_cap": { "type": "integer" }, "api_spent_today": { "type": "integer" }, "api_cap_remaining": { "type": "integer" } } } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "reply.received" ] } }, "active": { "type": "boolean" }, "disabled_reason": { "type": [ "string", "null" ] }, "consecutive_failures": { "type": "integer" }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status": { "type": [ "integer", "null" ] }, "secret_rotated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookCreate": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "maxLength": 1000, "description": "Public https:// URL on port 443" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "reply.received" ] } } } }, "WebhookDelivery": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "dead" ] }, "attempts": { "type": "integer" }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ReplyReceivedEvent": { "type": "object", "required": [ "version", "event", "fired_at", "delivery_id", "data" ], "properties": { "version": { "type": "string", "enum": [ "v1" ] }, "event": { "type": "string", "enum": [ "reply.received", "test" ] }, "fired_at": { "type": "string", "format": "date-time" }, "delivery_id": { "type": "string" }, "data": { "$ref": "#/components/schemas/Reply" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8-100 characters, unique per request (e.g. a UUID). Same key + same body within 24h replays the first answer; same key + different body = 422.", "schema": { "type": "string", "minLength": 8, "maxLength": 100, "pattern": "^[A-Za-z0-9_\\-:.]{8,100}$" } } } }, "webhooks": { "reply.received": { "post": { "summary": "A new reply arrived", "description": "POSTed to each active endpoint. Verify X-Senders-Signature: \"sha256=\" + HMAC-SHA256(secret, \"{X-Senders-Timestamp}.{raw body}\"). Answer 2xx within 10s. Retried on network errors, 408, 429 and 5xx (1m, 5m, 30m, 2h, 6h, 24h); other answers are not retried.", "parameters": [ { "name": "X-Senders-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Senders-Delivery", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Senders-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Senders-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Senders-Signature-Previous", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyReceivedEvent" } } } }, "responses": { "2XX": { "description": "Received" } } } } } }