{ "openapi": "3.1.0", "info": { "title": "Coldreach API", "version": "1.0.0", "description": "The Coldreach public API allows you to programmatically access your campaigns, accounts, and analytics." }, "servers": [ { "url": "https://api.coldreach.ai", "description": "Production" } ], "tags": [ { "name": "Authentication", "description": "Verify your API key" }, { "name": "Campaigns", "description": "Campaign targeting, qualified accounts, sequences, and contacts" }, { "name": "Accounts", "description": "Account lookup and exclusion" }, { "name": "Jobs", "description": "Job opening search" }, { "name": "Assignments", "description": "Sequence assignment actions" }, { "name": "Raw Operations", "description": "Low-level operations for external callers providing their own messaging content" }, { "name": "Analytics", "description": "Organization-level analytics" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Organization API key in the format `{orgId}.{secret}`" } }, "schemas": { "Signal": { "type": "object", "properties": { "name": { "type": "string" }, "updated": { "type": [ "string", "null" ] }, "freshness": { "type": [ "string", "null" ] }, "score": { "type": "number" }, "contextual": { "type": "string" } }, "required": [ "name", "updated", "freshness", "score" ] }, "Account": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "domain": { "type": "string" }, "website": { "type": "string" }, "linkedin-url": { "type": "string" }, "score": { "type": "number" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "updated": { "type": [ "string", "null" ] }, "freshness": { "type": [ "string", "null" ] }, "score": { "type": "number" }, "contextual": { "type": "string" } }, "required": [ "name", "updated", "freshness", "score" ] } } }, "required": [ "id", "domain", "score", "signals" ] }, "ICP": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "signals": { "type": "array", "items": { "type": "string" } }, "accounts_count": { "type": "number" } }, "required": [ "id", "name", "signals", "accounts_count" ] }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "last_seen_at": { "type": "string" }, "first_seen_at": { "type": "string" }, "status": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "domain", "title", "url", "last_seen_at", "first_seen_at", "status", "location", "description" ] }, "CampaignSummary": { "type": "object", "properties": { "id": { "type": "number", "description": "Campaign ID (ICP ID)" }, "provider": { "type": [ "string", "null" ], "description": "Provider when all campaign sequences use the same provider; otherwise null" }, "providers": { "type": "array", "items": { "type": "string" }, "description": "Providers used by this campaign's sequences" }, "sequence_ids": { "type": "array", "items": { "type": "number" }, "description": "Provider sequence IDs belonging to this campaign" }, "icp_id": { "type": "number", "description": "Deprecated alias of id" }, "icp_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "steps_count": { "type": "number" }, "stats": { "type": "object", "properties": { "sent": { "type": "number" }, "opened": { "type": "number" }, "clicked": { "type": "number" }, "bounced": { "type": "number" }, "unsubscribed": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "sent", "opened", "clicked", "bounced", "unsubscribed", "blocked" ] } }, "required": [ "id", "provider", "providers", "sequence_ids", "icp_id", "icp_name", "created_at", "steps_count", "stats" ] }, "CampaignDetail": { "type": "object", "properties": { "id": { "type": "number", "description": "Campaign ID (ICP ID)" }, "provider": { "type": [ "string", "null" ], "description": "Provider when all campaign sequences use the same provider; otherwise null" }, "providers": { "type": "array", "items": { "type": "string" }, "description": "Providers used by this campaign's sequences" }, "sequence_ids": { "type": "array", "items": { "type": "number" }, "description": "Provider sequence IDs belonging to this campaign" }, "icp_id": { "type": "number", "description": "Deprecated alias of id" }, "icp_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "steps_count": { "type": "number" }, "stats": { "type": "object", "properties": { "sent": { "type": "number" }, "opened": { "type": "number" }, "clicked": { "type": "number" }, "bounced": { "type": "number" }, "unsubscribed": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "sent", "opened", "clicked", "bounced", "unsubscribed", "blocked" ] }, "contacts": { "type": "object", "properties": { "pending_approval": { "type": "number" }, "scheduled": { "type": "number" }, "in_progress": { "type": "number" }, "completed": { "type": "number" }, "replied": { "type": "number" } }, "required": [ "pending_approval", "scheduled", "in_progress", "completed", "replied" ] } }, "required": [ "id", "provider", "providers", "sequence_ids", "icp_id", "icp_name", "created_at", "steps_count", "stats", "contacts" ] }, "CampaignContact": { "type": "object", "properties": { "assignment_id": { "type": "number" }, "contact": { "type": "object", "properties": { "id": { "type": "number" }, "email": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_domain": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "first_name", "last_name", "full_name", "title", "linkedin_url", "company_name", "company_domain" ] }, "status": { "type": "string" }, "approved_at": { "type": [ "string", "null" ] }, "sequenced_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "bounced_at": { "type": [ "string", "null" ] }, "unsubscribed_at": { "type": [ "string", "null" ] } }, "required": [ "assignment_id", "contact", "status", "approved_at", "sequenced_at", "completed_at", "bounced_at", "unsubscribed_at" ] }, "CampaignMessage": { "type": "object", "properties": { "id": { "type": "number" }, "assignment_id": { "type": "number" }, "type": { "type": "string", "enum": [ "sent", "received", "forward" ] }, "step_type": { "type": "string" }, "step_index": { "type": [ "number", "null" ] }, "variant_index": { "type": [ "number", "null" ] }, "response_type": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "open_count": { "type": "number" }, "sender_email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "assignment_id", "type", "step_type", "step_index", "variant_index", "response_type", "subject", "body", "open_count", "sender_email", "created_at" ] }, "AnalyticsOverview": { "type": "object", "properties": { "total_campaigns": { "type": "number" }, "total_contacts_sent": { "type": "number" }, "total_contacts_opened": { "type": "number" }, "total_contacts_replied": { "type": "number" }, "total_contacts_scheduled": { "type": "number" }, "total_bounced": { "type": "number" }, "total_unsubscribed": { "type": "number" } }, "required": [ "total_campaigns", "total_contacts_sent", "total_contacts_opened", "total_contacts_replied", "total_contacts_scheduled", "total_bounced", "total_unsubscribed" ] }, "Error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "parameters": {} }, "paths": { "/public/v1/auth": { "get": { "tags": [ "Authentication" ], "summary": "Verify API key", "description": "Verify that your API key is valid and you are authenticated.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Authentication status", "content": { "application/json": { "schema": { "type": "object", "properties": { "signed_in": { "type": "boolean" } }, "required": [ "signed_in" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}/accounts": { "get": { "tags": [ "Campaigns" ], "summary": "List campaign accounts", "description": "Paginate through qualified accounts for a specific campaign, including their signal scores.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "default": 0 }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "default": 25 }, "required": false, "name": "take", "in": "query" } ], "responses": { "200": { "description": "Paginated list of qualified accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "domain": { "type": "string" }, "website": { "type": "string" }, "linkedin-url": { "type": "string" }, "score": { "type": "number" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "updated": { "type": [ "string", "null" ] }, "freshness": { "type": [ "string", "null" ] }, "score": { "type": "number" }, "contextual": { "type": "string" } }, "required": [ "name", "updated", "freshness", "score" ] } } }, "required": [ "id", "domain", "score", "signals" ] } } }, "required": [ "accounts" ] } } } }, "400": { "description": "Invalid campaign ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "Get account details", "description": "Look up a specific account by domain or ID, optionally filtered by ICP signals. At least one of `domain` or `id` must be provided.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "domain", "in": "query" }, { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "query" }, { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "icpId", "in": "query" } ], "responses": { "200": { "description": "Account details with signals", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "name": { "type": "string" }, "domain": { "type": "string" }, "website": { "type": "string" }, "linkedin-url": { "type": "string" }, "score": { "type": "number" }, "signals": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "updated": { "type": [ "string", "null" ] }, "freshness": { "type": [ "string", "null" ] }, "score": { "type": "number" }, "contextual": { "type": "string" } }, "required": [ "name", "updated", "freshness", "score" ] } } }, "required": [ "id", "domain", "score", "signals" ] } } } }, "400": { "description": "Missing required query parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/accounts/exclude": { "post": { "tags": [ "Accounts" ], "summary": "Exclude an account", "description": "Mark an account as excluded (misfit). Excluded accounts will not be suggested for outreach.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "description": "Account to exclude", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_url": { "type": "string" }, "company_name": { "type": "string" }, "company_linkedin_url": { "type": "string" } }, "required": [ "company_url" ] } } } }, "responses": { "200": { "description": "Account excluded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing company_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/jobs/{domain}": { "get": { "tags": [ "Jobs" ], "summary": "Search job openings", "description": "Search recent job openings for a company domain with cursor-based pagination.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "domain", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "default": 100 }, "required": false, "name": "take", "in": "query" } ], "responses": { "200": { "description": "Job openings with pagination cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "next": { "type": "number" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "last_seen_at": { "type": "string" }, "first_seen_at": { "type": "string" }, "status": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "domain", "title", "url", "last_seen_at", "first_seen_at", "status", "location", "description" ] } } }, "required": [ "domain", "next", "jobs" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/assignments/{id}/reply": { "post": { "tags": [ "Assignments" ], "summary": "Reply to an assignment", "description": "Send a reply to a contact assignment in a sequence. The recipient email is auto-derived from the contact if not provided.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" } ], "requestBody": { "description": "Reply content", "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "plain_text": { "type": "boolean", "default": false, "description": "Set to true when body is plain text. The API will convert it to safe HTML before sending email replies." }, "to": { "type": "string" }, "cc": { "type": "string" }, "bcc": { "type": "string" } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "Reply sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Invalid assignment ID or missing body", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Assignment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "List all campaigns for your organization with statistics aggregated across their provider sequences. Response IDs are campaign (ICP) IDs.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of campaigns", "content": { "application/json": { "schema": { "type": "object", "properties": { "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Campaign ID (ICP ID)" }, "provider": { "type": [ "string", "null" ], "description": "Provider when all campaign sequences use the same provider; otherwise null" }, "providers": { "type": "array", "items": { "type": "string" }, "description": "Providers used by this campaign's sequences" }, "sequence_ids": { "type": "array", "items": { "type": "number" }, "description": "Provider sequence IDs belonging to this campaign" }, "icp_id": { "type": "number", "description": "Deprecated alias of id" }, "icp_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "steps_count": { "type": "number" }, "stats": { "type": "object", "properties": { "sent": { "type": "number" }, "opened": { "type": "number" }, "clicked": { "type": "number" }, "bounced": { "type": "number" }, "unsubscribed": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "sent", "opened", "clicked", "bounced", "unsubscribed", "blocked" ] } }, "required": [ "id", "provider", "providers", "sequence_ids", "icp_id", "icp_name", "created_at", "steps_count", "stats" ] } } }, "required": [ "campaigns" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get campaign details", "description": "Get detailed information about a campaign by campaign (ICP) ID, including contact status aggregated across all provider sequences.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Campaign details with contact breakdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Campaign ID (ICP ID)" }, "provider": { "type": [ "string", "null" ], "description": "Provider when all campaign sequences use the same provider; otherwise null" }, "providers": { "type": "array", "items": { "type": "string" }, "description": "Providers used by this campaign's sequences" }, "sequence_ids": { "type": "array", "items": { "type": "number" }, "description": "Provider sequence IDs belonging to this campaign" }, "icp_id": { "type": "number", "description": "Deprecated alias of id" }, "icp_name": { "type": "string" }, "created_at": { "type": [ "string", "null" ] }, "steps_count": { "type": "number" }, "stats": { "type": "object", "properties": { "sent": { "type": "number" }, "opened": { "type": "number" }, "clicked": { "type": "number" }, "bounced": { "type": "number" }, "unsubscribed": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "sent", "opened", "clicked", "bounced", "unsubscribed", "blocked" ] }, "contacts": { "type": "object", "properties": { "pending_approval": { "type": "number" }, "scheduled": { "type": "number" }, "in_progress": { "type": "number" }, "completed": { "type": "number" }, "replied": { "type": "number" } }, "required": [ "pending_approval", "scheduled", "in_progress", "completed", "replied" ] } }, "required": [ "id", "provider", "providers", "sequence_ids", "icp_id", "icp_name", "created_at", "steps_count", "stats", "contacts" ] } } } }, "400": { "description": "Invalid campaign ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}/contacts": { "get": { "tags": [ "Campaigns" ], "summary": "List campaign contacts", "description": "Paginate through contacts in a campaign by campaign (ICP) ID across all provider sequences. Optionally filter by contact status.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "default": 0 }, "required": false, "name": "skip", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "maximum": 100, "default": 25 }, "required": false, "name": "take", "in": "query" }, { "schema": { "type": "string", "enum": [ "scheduled", "in-progress", "completed", "replied", "bounced", "unsubscribed" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Paginated list of campaign contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assignment_id": { "type": "number" }, "contact": { "type": "object", "properties": { "id": { "type": "number" }, "email": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_domain": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "first_name", "last_name", "full_name", "title", "linkedin_url", "company_name", "company_domain" ] }, "status": { "type": "string" }, "approved_at": { "type": [ "string", "null" ] }, "sequenced_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "bounced_at": { "type": [ "string", "null" ] }, "unsubscribed_at": { "type": [ "string", "null" ] } }, "required": [ "assignment_id", "contact", "status", "approved_at", "sequenced_at", "completed_at", "bounced_at", "unsubscribed_at" ] } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "data", "total", "skip", "take" ] } } } }, "400": { "description": "Invalid campaign ID or status filter", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}/messages": { "get": { "tags": [ "Campaigns" ], "summary": "List campaign messages", "description": "Paginate through messages sent and received across all provider sequences in a campaign, addressed by campaign (ICP) ID.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "default": 0 }, "required": false, "name": "skip", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "maximum": 100, "default": 25 }, "required": false, "name": "take", "in": "query" } ], "responses": { "200": { "description": "Paginated list of campaign messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "assignment_id": { "type": "number" }, "type": { "type": "string", "enum": [ "sent", "received", "forward" ] }, "step_type": { "type": "string" }, "step_index": { "type": [ "number", "null" ] }, "variant_index": { "type": [ "number", "null" ] }, "response_type": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "open_count": { "type": "number" }, "sender_email": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "assignment_id", "type", "step_type", "step_index", "variant_index", "response_type", "subject", "body", "open_count", "sender_email", "created_at" ] } }, "total": { "type": "number" }, "skip": { "type": "number" }, "take": { "type": "number" } }, "required": [ "data", "total", "skip", "take" ] } } } }, "400": { "description": "Invalid campaign ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Campaign not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}/raw/contacts": { "post": { "tags": [ "Raw Operations" ], "summary": "Upsert contacts with pre-provided variables", "description": "Upserts contacts into a campaign with pre-written snippet values. By default, existing contact data is updated and ineligible contacts are skipped. Set existingContactPolicy to preserve to assign a known contact without changing its persisted data. Use bypass flags to selectively override specific eligibility rules.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" } ], "requestBody": { "description": "Contacts to upsert with variable values and eligibility options", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "fullName": { "type": "string" }, "title": { "type": "string" }, "linkedinUrl": { "type": "string" }, "companyDomain": { "type": "string" }, "companyName": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "email" ] }, "minItems": 1, "maxItems": 1000 }, "triggerIntake": { "type": "boolean", "default": true }, "skipIneligible": { "type": "boolean", "default": true }, "existingContactPolicy": { "type": "string", "enum": [ "update", "preserve" ], "default": "update", "description": "Whether existing contact data should be updated from the request or preserved unchanged." }, "bypassCooldownOtherSequences": { "type": "boolean", "default": false }, "bypassGlobalExcluded": { "type": "boolean", "default": false }, "takeoverUnapproved": { "type": "boolean", "default": false } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "Upsert result with counts, skipped contacts, and any errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number", "description": "Number of new contacts created" }, "updated": { "type": "number", "description": "Number of existing contacts updated" }, "skipped": { "type": "number", "description": "Number of contacts skipped" }, "assignmentIds": { "type": "array", "items": { "type": "number" }, "description": "IDs of newly created assignments" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "error": { "type": "string" } }, "required": [ "email", "error" ] }, "description": "Per-contact validation errors" }, "skippedContacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "cooldown_same_sequence", "cooldown_other_sequences", "unapproved", "replied", "blocked", "globally_excluded", "provider_incompatible:missing_email", "provider_incompatible:missing_linkedin_url", "provider_incompatible:personal_email_not_allowed", "provider_incompatible:missing_first_name", "provider_incompatible:failed_email_verification", "duplicate_in_request" ] } } }, "required": [ "email", "reasons" ] }, "description": "Contacts that were skipped due to ineligibility, with reasons" } }, "required": [ "created", "updated", "skipped", "assignmentIds", "errors", "skippedContacts" ] } } } }, "400": { "description": "Validation errors (e.g. unknown variable keys)", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "number", "description": "Number of new contacts created" }, "updated": { "type": "number", "description": "Number of existing contacts updated" }, "skipped": { "type": "number", "description": "Number of contacts skipped" }, "assignmentIds": { "type": "array", "items": { "type": "number" }, "description": "IDs of newly created assignments" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "error": { "type": "string" } }, "required": [ "email", "error" ] }, "description": "Per-contact validation errors" }, "skippedContacts": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "cooldown_same_sequence", "cooldown_other_sequences", "unapproved", "replied", "blocked", "globally_excluded", "provider_incompatible:missing_email", "provider_incompatible:missing_linkedin_url", "provider_incompatible:personal_email_not_allowed", "provider_incompatible:missing_first_name", "provider_incompatible:failed_email_verification", "duplicate_in_request" ] } } }, "required": [ "email", "reasons" ] }, "description": "Contacts that were skipped due to ineligibility, with reasons" } }, "required": [ "created", "updated", "skipped", "assignmentIds", "errors", "skippedContacts" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Campaign not found or has no sequences", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/campaigns/{id}/raw/contacts/check-eligibility": { "post": { "tags": [ "Raw Operations" ], "summary": "Check contact eligibility for a campaign", "description": "Check whether contacts are eligible to be added to a campaign's sequence. Returns per-contact eligibility status with reasons for ineligibility (cooldown, already in another sequence, replied, blocked, or globally excluded). Use this before upserting contacts to avoid adding ineligible ones.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "id", "in": "path" } ], "requestBody": { "description": "List of emails to check eligibility for", "content": { "application/json": { "schema": { "type": "object", "properties": { "bypassCooldownOtherSequences": { "type": "boolean", "default": false }, "bypassGlobalExcluded": { "type": "boolean", "default": false }, "takeoverUnapproved": { "type": "boolean", "default": false }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "emails" ] } } } }, "responses": { "200": { "description": "Per-contact eligibility results with summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "cooldown_same_sequence", "cooldown_other_sequences", "unapproved", "replied", "blocked", "globally_excluded" ] } } }, "required": [ "email", "eligible", "reasons" ] } }, "summary": { "type": "object", "properties": { "total": { "type": "number" }, "eligible": { "type": "number" }, "ineligible": { "type": "number" }, "cooldown_same_sequence": { "type": "number" }, "cooldown_other_sequences": { "type": "number" }, "unapproved": { "type": "number" }, "replied": { "type": "number" }, "blocked": { "type": "number" }, "globally_excluded": { "type": "number" } }, "required": [ "total", "eligible", "ineligible", "cooldown_same_sequence", "cooldown_other_sequences", "unapproved", "replied", "blocked", "globally_excluded" ] } }, "required": [ "results", "summary" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "description": "Campaign not found or has no sequences", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "/public/v1/analytics/overview": { "get": { "tags": [ "Analytics" ], "summary": "Get analytics overview", "description": "Get high-level analytics for your organization: total campaigns, contacts sent/opened/replied, bounced, and unsubscribed counts.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Analytics overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_campaigns": { "type": "number" }, "total_contacts_sent": { "type": "number" }, "total_contacts_opened": { "type": "number" }, "total_contacts_replied": { "type": "number" }, "total_contacts_scheduled": { "type": "number" }, "total_bounced": { "type": "number" }, "total_unsubscribed": { "type": "number" } }, "required": [ "total_campaigns", "total_contacts_sent", "total_contacts_opened", "total_contacts_replied", "total_contacts_scheduled", "total_bounced", "total_unsubscribed" ] } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } } }, "webhooks": {} }