{ "openapi": "3.1.0", "info": { "title": "ZicReach API", "version": "1.0" }, "servers": [ { "url": "https://app.zicreach.com/api/v1" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearer": [] } ], "tags": [ { "name": "Account", "description": "The workspace your API key belongs to: its plan, remaining credits and what it holds." }, { "name": "Campaigns", "description": "Create campaigns, change their content and schedule, add leads, and launch, pause or resume them. A new campaign starts as a draft." }, { "name": "Replies", "description": "Replies that arrived in the Unibox, with the AI classification of each one." }, { "name": "Email accounts", "description": "The mailboxes your campaigns send from, with their daily limit, reputation and warmup health. Mailboxes are connected in the app." }, { "name": "Blacklist", "description": "Addresses that are never emailed. Unsubscribes land here automatically; add your own opt-outs straight from a form." }, { "name": "Opportunities", "description": "Deals created from replies, with their stage and value." }, { "name": "Analytics", "description": "The numbers behind the Analytics page: totals, rates, a day-by-day series and breakdowns by campaign and mailbox." }, { "name": "Webhooks", "description": "Get told the moment something happens. Subscribe a URL to an event; we POST a JSON payload to it. The shape Zapier and Make expect." }, { "name": "Lead lists", "description": "Tables of leads in the Leads Engine. A deleted list goes to Trash and can be restored for 90 days." }, { "name": "Leads", "description": "People in your lists. Suppressed addresses and addresses already in the workspace are refused." }, { "name": "Lead records", "description": "Every person, company and job this workspace has brought in, from any list, import or search, one record per real lead. Read-only. Contact details come from your own copy of each lead." }, { "name": "Find people and companies", "description": "Search the ZicReach directory. A search returns a count and a preview without contact details; import turns it into a new list, within your plan's row limit." } ], "paths": { "/account": { "get": { "tags": [ "Account" ], "summary": "Get the workspace", "description": "Returns the workspace, its plan and its remaining credits.", "operationId": "get-account", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "workspace": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Acme Outbound", "created_at": "2026-09-01T10:00:00Z" }, "plan": "Growth", "credits": { "balance": 19450 }, "counts": { "campaigns": 6, "email_accounts": 4, "lists": 11 } } } } } } } } }, "/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "Campaigns, newest first.", "operationId": "get-campaigns", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "draft, active, paused or completed.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Results per page, up to 100. Default 25.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "draft", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } }, "post": { "tags": [ "Campaigns" ], "summary": "Create a campaign", "description": "Creates a draft campaign. Everything except name, subject_lines and email_bodies is optional.", "operationId": "post-campaigns", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "draft", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "subject_lines": { "type": "array", "description": "One to five subject lines. More than one is an A/B test." }, "email_bodies": { "type": "array", "description": "One to five bodies. Merge fields like {{first_name|there}} work." }, "timezone": { "type": "string", "description": "IANA timezone, for example Europe/London." }, "send_days": { "type": "array", "description": "Any of mon, tue, wed, thu, fri, sat, sun." }, "send_window_start": { "type": "string", "description": "HH:MM in the campaign timezone." }, "send_window_end": { "type": "string", "description": "HH:MM in the campaign timezone." }, "delay_between_emails": { "type": "integer", "description": "Seconds between emails from one mailbox, 30 to 3600." }, "follow_up_enabled": { "type": "boolean", "description": "Send follow-ups." }, "follow_up_delay_days": { "type": "integer", "description": "Days between follow-ups, 1 to 60." }, "max_follow_ups": { "type": "integer", "description": "At most this many follow-ups, 0 to 5." }, "track_opens": { "type": "boolean", "description": "Track opens and link clicks." }, "email_account_ids": { "type": "array", "description": "Mailboxes to send from." } }, "required": [ "name", "subject_lines", "email_bodies" ] } } } } } }, "/campaigns/{id}": { "get": { "tags": [ "Campaigns" ], "summary": "Get a campaign", "description": "One campaign with its settings and running totals.", "operationId": "get-campaigns-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "draft", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } } }, "patch": { "tags": [ "Campaigns" ], "summary": "Update a campaign", "description": "Send only the fields to change. Accepts the same fields as create.", "operationId": "patch-campaigns-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "draft", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign name." }, "subject_lines": { "type": "array", "description": "Replaces the subject lines." }, "email_bodies": { "type": "array", "description": "Replaces the bodies." }, "send_window_start": { "type": "string", "description": "HH:MM." }, "send_window_end": { "type": "string", "description": "HH:MM." } }, "required": [] } } } } } }, "/campaigns/{id}/launch": { "post": { "tags": [ "Campaigns" ], "summary": "Launch a campaign", "description": "Starts sending. Refused with 422 and a list of blockers when the campaign is not ready (no recipients, no mailbox, no credits).", "operationId": "post-campaigns-id-launch", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Campaign launched.", "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "active", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } } } }, "/campaigns/{id}/pause": { "post": { "tags": [ "Campaigns" ], "summary": "Pause a campaign", "description": "Stops sending until resumed. Nothing is lost.", "operationId": "post-campaigns-id-pause", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Campaign paused.", "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "paused", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } } } }, "/campaigns/{id}/resume": { "post": { "tags": [ "Campaigns" ], "summary": "Resume a campaign", "description": "Continues a paused campaign.", "operationId": "post-campaigns-id-resume", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Campaign resumed.", "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "active", "campaign_type": "standard", "schedule_type": "immediate", "scheduled_at": null, "subject_lines": [ "Quick question, {{first_name|there}}" ], "email_bodies": [ "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..." ], "send_window": { "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ], "timezone": "Europe/London" }, "follow_up": { "enabled": true, "delay_days": 3, "max": 3 }, "stop_on_reply": true, "stats": { "total_leads": 240, "sent": 0, "opened": 0, "clicked": 0, "replied": 0, "bounced": 0 }, "created_at": "2026-09-20T08:00:00Z" } } } } } } } }, "/campaigns/{id}/leads": { "get": { "tags": [ "Campaigns" ], "summary": "List campaign recipients", "description": "Recipients and where each one is in the sequence.", "operationId": "get-campaigns-id-leads", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "pending, active, sent, replied, bounced, unsubscribed or completed.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Up to 200. Default 50.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "company": "Example Ltd", "status": "active", "current_step": 1, "last_sent_at": "2026-09-22T09:14:00Z", "opened_at": null, "clicked_at": null, "replied_at": null, "bounced_at": null } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } }, "post": { "tags": [ "Campaigns" ], "summary": "Add leads to a campaign", "description": "Adds a whole list (optionally filtered) or specific leads. Suppressed addresses, duplicates and people contacted too recently are skipped.", "operationId": "post-campaigns-id-leads", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "added": 240, "skipped": 12, "cooling": 3, "total_recipients": 240 } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "description": "Add the leads of this list. Required unless lead_ids is sent." }, "lead_ids": { "type": "array", "description": "Add these leads, up to 1,000. Required unless list_id is sent." }, "company": { "type": "string", "description": "With list_id: only leads at this company." }, "industry": { "type": "string", "description": "With list_id: only this industry." }, "job_title": { "type": "string", "description": "With list_id: only titles containing this." }, "location": { "type": "string", "description": "With list_id: only this location." } }, "required": [] } } } } } }, "/campaigns/{id}/stats": { "get": { "tags": [ "Campaigns" ], "summary": "Get campaign stats", "description": "Totals, rates, A/B variants and the last 14 days of sends for one campaign.", "operationId": "get-campaigns-id-stats", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "campaign": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "active" }, "totals": { "recipients": 240, "sent": 212, "delivered": 209, "opened": 71, "clicked": 8, "replied": 6, "bounced": 3, "unsubscribed": 1, "pending": 28, "failed": 0 }, "rates": { "open": 34, "click": 3.8, "reply": 2.9, "bounce": 1.4, "unsubscribe": 0.5, "progress": 88.3 }, "variants": [ { "index": 0, "subject": "Quick question, {{first_name|there}}", "sent": 212, "replied": 6, "reply_rate": 2.9 } ], "daily": [ { "date": "2026-09-24", "sent": 40 } ] } } } } } } } }, "/replies": { "get": { "tags": [ "Replies" ], "summary": "List replies", "description": "Replies, newest first.", "operationId": "get-replies", "parameters": [ { "name": "campaign_id", "in": "query", "required": false, "description": "Only replies to this campaign.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "required": false, "description": "Only unread replies.", "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "required": false, "description": "Up to 100. Default 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "campaign_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email_account_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "from": "jane@example.com", "subject": "Re: Quick question, Jane", "snippet": "This looks interesting. Can we talk on Thursday?", "reply_type": "interested", "is_read": false, "received_at": "2026-09-24T10:31:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } } }, "/replies/{id}": { "get": { "tags": [ "Replies" ], "summary": "Get a reply", "description": "One reply, including its full body.", "operationId": "get-replies-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reply id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "campaign_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email_account_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "from": "jane@example.com", "subject": "Re: Quick question, Jane", "snippet": "This looks interesting. Can we talk on Thursday?", "reply_type": "interested", "is_read": false, "received_at": "2026-09-24T10:31:00Z", "body": "Hi Sara,\n\nThis looks interesting. Can we talk on Thursday?\n\nJane" } } } } } } } }, "/replies/{id}/read": { "post": { "tags": [ "Replies" ], "summary": "Mark a reply as read", "description": "Marks the reply as read in the Unibox.", "operationId": "post-replies-id-read", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reply id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Marked as read.", "data": { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "campaign_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email_account_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "from": "jane@example.com", "subject": "Re: Quick question, Jane", "snippet": "This looks interesting. Can we talk on Thursday?", "reply_type": "interested", "is_read": true, "received_at": "2026-09-24T10:31:00Z" } } } } } } } }, "/email-accounts": { "get": { "tags": [ "Email accounts" ], "summary": "List email accounts", "description": "Every mailbox in the workspace.", "operationId": "get-email-accounts", "parameters": [ { "name": "active", "in": "query", "required": false, "description": "Only active (true) or paused (false) mailboxes.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email": "sara@acme.io", "display_name": "Sara Khan", "provider": "google", "is_active": true, "daily_send_limit": 40, "sent_today": 12, "reputation_score": 92.5, "warmup": { "enabled": true, "health_score": 97 }, "created_at": "2026-09-01T10:00:00Z" } ] } } } } } } }, "/email-accounts/{id}": { "get": { "tags": [ "Email accounts" ], "summary": "Get an email account", "description": "One mailbox.", "operationId": "get-email-accounts-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email": "sara@acme.io", "display_name": "Sara Khan", "provider": "google", "is_active": true, "daily_send_limit": 40, "sent_today": 12, "reputation_score": 92.5, "warmup": { "enabled": true, "health_score": 97 }, "created_at": "2026-09-01T10:00:00Z" } } } } } } } }, "/email-accounts/{id}/pause": { "post": { "tags": [ "Email accounts" ], "summary": "Pause a mailbox", "description": "Stops the mailbox sending campaign emails until resumed.", "operationId": "post-email-accounts-id-pause", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Mailbox paused. It will not send until resumed.", "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email": "sara@acme.io", "display_name": "Sara Khan", "provider": "google", "is_active": false, "daily_send_limit": 40, "sent_today": 12, "reputation_score": 92.5, "warmup": { "enabled": true, "health_score": 97 }, "created_at": "2026-09-01T10:00:00Z" } } } } } } } }, "/email-accounts/{id}/resume": { "post": { "tags": [ "Email accounts" ], "summary": "Resume a mailbox", "description": "Lets the mailbox send again.", "operationId": "post-email-accounts-id-resume", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mailbox id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Mailbox resumed.", "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "email": "sara@acme.io", "display_name": "Sara Khan", "provider": "google", "is_active": true, "daily_send_limit": 40, "sent_today": 12, "reputation_score": 92.5, "warmup": { "enabled": true, "health_score": 97 }, "created_at": "2026-09-01T10:00:00Z" } } } } } } } }, "/suppressions": { "get": { "tags": [ "Blacklist" ], "summary": "List suppressed addresses", "description": "Newest first.", "operationId": "get-suppressions", "parameters": [ { "name": "per_page", "in": "query", "required": false, "description": "Up to 200. Default 50.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "email": "optout@example.com", "reason": "unsubscribed", "created_at": "2026-09-20T12:00:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } }, "post": { "tags": [ "Blacklist" ], "summary": "Suppress an address", "description": "The address is never emailed again by any campaign in this workspace.", "operationId": "post-suppressions", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "message": "Address suppressed." } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The address to suppress." }, "reason": { "type": "string", "description": "Why, for your records. Default manual." } }, "required": [ "email" ] } } } } } }, "/opportunities": { "get": { "tags": [ "Opportunities" ], "summary": "List opportunities", "description": "Newest first.", "operationId": "get-opportunities", "parameters": [ { "name": "stage", "in": "query", "required": false, "description": "conversation, meeting, proposal, won or lost.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only this campaign.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "campaign_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "contact_name": "Jane Doe", "company": "Example Ltd", "stage": "meeting", "value": 12000, "currency": "USD", "closed_at": null, "created_at": "2026-09-23T15:02:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } } }, "/stats/overview": { "get": { "tags": [ "Analytics" ], "summary": "Get the overview", "description": "All-time totals for the workspace: sent is every email, contacted is people.", "operationId": "get-stats-overview", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "campaigns_active": 3, "sent": 13100, "contacted": 8420, "opened": 2911, "replied": 214, "open_rate": 35.1, "reply_rate": 2.6, "suppressed": 57 } } } } } } } }, "/stats/report": { "get": { "tags": [ "Analytics" ], "summary": "Get a report", "description": "Totals, rates and a day-by-day series for a date range of up to a year. sent counts every email (follow-ups included) on the day it went out; contacted counts people; rates are per person contacted.", "operationId": "get-stats-report", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Start date, YYYY-MM-DD. Default 30 days ago.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "End date, YYYY-MM-DD. Default today.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only this campaign.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "from": "2026-08-27", "to": "2026-09-25", "totals": { "sent": 1640, "contacted": 1002, "opened": 318, "clicked": 41, "replied": 25, "bounced": 9 }, "rates": { "open": 32, "click": 4.1, "reply": 2.5, "bounce": 0.9 }, "daily": [ { "date": "2026-09-24", "sent": 141, "contacted": 86, "opened": 30, "clicked": 3, "replied": 2, "bounced": 1 } ], "campaigns": [ { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "active", "sent": 1050, "contacted": 640, "opened": 201, "clicked": 22, "replied": 17, "bounced": 5, "reply_rate": 2.7, "open_rate": 31.7 } ], "accounts": [ { "email": "sara@acme.io", "sent": 830, "contacted": 510, "opened": 160, "replied": 13, "bounced": 4, "reply_rate": 2.6, "bounce_rate": 0.8 } ], "reply_types": { "interested": 9, "not_interested": 7, "out_of_office": 6, "unclassified": 3 }, "opportunities": { "count": 4, "value": 38000, "won": 1, "won_value": 12000, "currency": "USD" } } } } } } } } }, "/stats/campaigns/{id}": { "get": { "tags": [ "Analytics" ], "summary": "Get campaign stats", "description": "Same as GET /campaigns/{id}/stats.", "operationId": "get-stats-campaigns-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "campaign": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Q4 founders", "status": "active" }, "totals": { "recipients": 240, "sent": 212, "delivered": 209, "opened": 71, "clicked": 8, "replied": 6, "bounced": 3, "unsubscribed": 1, "pending": 28, "failed": 0 }, "rates": { "open": 34, "click": 3.8, "reply": 2.9, "bounce": 1.4, "unsubscribe": 0.5, "progress": 88.3 }, "variants": [ { "index": 0, "subject": "Quick question, {{first_name|there}}", "sent": 212, "replied": 6, "reply_rate": 2.9 } ], "daily": [ { "date": "2026-09-24", "sent": 40 } ] } } } } } } } }, "/hooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List events", "description": "Every event you can subscribe to.", "operationId": "get-hooks-events", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "key": "lead.replied", "label": "A recipient replied" }, { "key": "lead.bounced", "label": "A message hard-bounced" }, { "key": "lead.unsubscribed", "label": "A recipient unsubscribed" }, { "key": "lead.opened", "label": "A recipient opened a message" }, { "key": "lead.clicked", "label": "A recipient clicked a link" }, { "key": "campaign.completed", "label": "A campaign finished sending" } ] } } } } } } }, "/hooks/sample": { "get": { "tags": [ "Webhooks" ], "summary": "Get a sample payload", "description": "An example of what an event delivers, for mapping fields.", "operationId": "get-hooks-sample", "parameters": [ { "name": "event", "in": "query", "required": false, "description": "Event key. Default lead.replied.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "event": "lead.replied", "created_at": "2026-09-24T10:31:00Z", "data": { "lead_id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "company": "Example Ltd" } } ] } } } } } } }, "/hooks": { "post": { "tags": [ "Webhooks" ], "summary": "Subscribe", "description": "Starts sending an event to your URL. The URL must be https.", "operationId": "post-hooks", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "event": "lead.replied", "target": "https://hooks.example.com/zicreach" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "Where to POST events. https only." }, "event": { "type": "string", "description": "One event key from List events." } }, "required": [ "target_url", "event" ] } } } } } }, "/hooks/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Unsubscribe", "description": "Stops the subscription.", "operationId": "delete-hooks-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Unsubscribed." } } } } } } }, "/lists": { "get": { "tags": [ "Lead lists" ], "summary": "List lead lists", "description": "Every list with its lead count.", "operationId": "get-lists", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "SaaS founders UK", "description": "From a people search", "leads": 412, "created_at": "2026-09-18T09:00:00Z" } ] } } } } } }, "post": { "tags": [ "Lead lists" ], "summary": "Create a list", "description": "An empty list to add leads to.", "operationId": "post-lists", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "SaaS founders UK", "description": "From a people search", "leads": 0, "created_at": "2026-09-18T09:00:00Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "List name." }, "description": { "type": "string", "description": "What the list is for." } }, "required": [ "name" ] } } } } } }, "/lists/{id}": { "get": { "tags": [ "Lead lists" ], "summary": "Get a list", "description": "One list.", "operationId": "get-lists-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "SaaS founders UK", "description": "From a people search", "leads": 412, "created_at": "2026-09-18T09:00:00Z" } } } } } } }, "delete": { "tags": [ "Lead lists" ], "summary": "Delete a list", "description": "Moves the list to Trash.", "operationId": "delete-lists-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "List id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "List moved to Trash. It can be restored for 90 days." } } } } } } }, "/leads/lists": { "get": { "tags": [ "Lead lists" ], "summary": "List lead lists (short)", "description": "Id, name and lead count only.", "operationId": "get-leads-lists", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "SaaS founders UK", "leads": 412 } ] } } } } } } }, "/leads": { "get": { "tags": [ "Leads" ], "summary": "List leads", "description": "Newest first.", "operationId": "get-leads", "parameters": [ { "name": "list_id", "in": "query", "required": false, "description": "Only this list.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Lead status, for example new.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "description": "Up to 100. Default 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "company": "Example Ltd", "job_title": "Founder & CEO", "phone": null, "website": "example.com", "linkedin_url": "https://www.linkedin.com/in/janedoe", "location": "London, United Kingdom", "industry": "Software", "status": "new", "source": "api", "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "custom_fields": { "icebreaker": "Loved your talk at SaaStr" }, "created_at": "2026-09-18T09:00:00Z" } ], "meta": { "current_page": 1, "last_page": 1, "total": 1 } } } } } } }, "post": { "tags": [ "Leads" ], "summary": "Create a lead", "description": "Adds one lead to a list.", "operationId": "post-leads", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "company": "Example Ltd", "job_title": "Founder & CEO", "phone": null, "website": "example.com", "linkedin_url": "https://www.linkedin.com/in/janedoe", "location": "London, United Kingdom", "industry": "Software", "status": "new", "source": "api", "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "custom_fields": { "icebreaker": "Loved your talk at SaaStr" }, "created_at": "2026-09-18T09:00:00Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address." }, "list_id": { "type": "string", "description": "The list to add to." }, "first_name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "company": { "type": "string", "description": "Company name." }, "job_title": { "type": "string", "description": "Job title." }, "phone": { "type": "string", "description": "Phone number." }, "website": { "type": "string", "description": "Company website." }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL." }, "location": { "type": "string", "description": "City or country." }, "industry": { "type": "string", "description": "Industry." }, "custom_fields": { "type": "object", "description": "Your own fields, usable as merge fields." } }, "required": [ "email", "list_id" ] } } } } } }, "/leads/bulk": { "post": { "tags": [ "Leads" ], "summary": "Create leads in bulk", "description": "Up to 500 leads in one call. Duplicates and suppressed addresses are counted and skipped.", "operationId": "post-leads-bulk", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "created": 480, "duplicate": 15, "suppressed": 5 } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "description": "The list to add to." }, "leads": { "type": "array", "description": "Leads, each with email and any of the lead fields." } }, "required": [ "list_id", "leads" ] } } } } } }, "/leads/{id}": { "get": { "tags": [ "Leads" ], "summary": "Get a lead", "description": "One lead.", "operationId": "get-leads-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "company": "Example Ltd", "job_title": "Founder & CEO", "phone": null, "website": "example.com", "linkedin_url": "https://www.linkedin.com/in/janedoe", "location": "London, United Kingdom", "industry": "Software", "status": "new", "source": "api", "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "custom_fields": { "icebreaker": "Loved your talk at SaaStr" }, "created_at": "2026-09-18T09:00:00Z" } } } } } } }, "patch": { "tags": [ "Leads" ], "summary": "Update a lead", "description": "Send only the fields to change. custom_fields are merged, not replaced. The email cannot be changed.", "operationId": "patch-leads-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "company": "Example Ltd", "job_title": "Founder & CEO", "phone": null, "website": "example.com", "linkedin_url": "https://www.linkedin.com/in/janedoe", "location": "London, United Kingdom", "industry": "Software", "status": "new", "source": "api", "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "custom_fields": { "icebreaker": "Loved your talk at SaaStr" }, "created_at": "2026-09-18T09:00:00Z" } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name." }, "last_name": { "type": "string", "description": "Last name." }, "company": { "type": "string", "description": "Company name." }, "job_title": { "type": "string", "description": "Job title." }, "phone": { "type": "string", "description": "Phone number." }, "website": { "type": "string", "description": "Company website." }, "linkedin_url": { "type": "string", "description": "LinkedIn profile URL." }, "location": { "type": "string", "description": "City or country." }, "industry": { "type": "string", "description": "Industry." }, "custom_fields": { "type": "object", "description": "Your own fields, usable as merge fields." } }, "required": [] } } } } }, "delete": { "tags": [ "Leads" ], "summary": "Delete a lead", "description": "Removes the lead.", "operationId": "delete-leads-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "message": "Lead deleted." } } } } } } }, "/owned-leads": { "get": { "tags": [ "Lead records" ], "summary": "List lead records", "description": "In record id order. Pass next back as after for the following page.", "operationId": "get-owned-leads", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "person, company or job.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "The next value of the previous page.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Up to 100. Default 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": 1042, "type": "person", "source": "csv", "acquired_at": "2026-10-02 10:00:00", "lead_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "name": "Jane Doe", "title": "Founder & CEO", "company": "Example Ltd", "domain": "example.com", "email": "jane@example.com" } ], "next": 1043 } } } } } } }, "/owned-leads/{id}": { "get": { "tags": [ "Lead records" ], "summary": "Get a lead record", "description": "One record this workspace holds; any other id is 404.", "operationId": "get-owned-leads-id", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Record id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": 1042, "type": "person", "name": "Jane Doe", "company": "Example Ltd" } } } } } } } }, "/search/people": { "get": { "tags": [ "Find people and companies" ], "summary": "Search people", "description": "Count and a 25-row preview. Filters are arrays: titles[]=CEO&countries[]=United Kingdom.", "operationId": "get-search-people", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free text: name, title or company.", "schema": { "type": "string" } }, { "name": "titles", "in": "query", "required": false, "description": "Job titles, up to 12.", "schema": { "type": "array" } }, { "name": "seniorities", "in": "query", "required": false, "description": "Any of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern.", "schema": { "type": "array" } }, { "name": "countries", "in": "query", "required": false, "description": "Countries, up to 12.", "schema": { "type": "array" } }, { "name": "industries", "in": "query", "required": false, "description": "Industries, up to 12 (on plans with People search).", "schema": { "type": "array" } }, { "name": "companies", "in": "query", "required": false, "description": "Company names or domains, up to 25.", "schema": { "type": "array" } }, { "name": "company_mode", "in": "query", "required": false, "description": "With companies: current, previous or either. Default current.", "schema": { "type": "string" } }, { "name": "total", "in": "query", "required": false, "description": "How many people to take, up to your plan limit. Default 100.", "schema": { "type": "integer" } }, { "name": "per_company", "in": "query", "required": false, "description": "At most this many per company. Default 10.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "total": 1840, "preview": [ { "first_name": "Jane", "last_name": "Doe", "job_title": "Founder & CEO", "seniority": "Owner / founder", "company": "Example Ltd", "domain": "example.com", "location": "London, United Kingdom", "has_email": true } ] } } } } } } } }, "/search/people/import": { "post": { "tags": [ "Find people and companies" ], "summary": "Import a people search", "description": "Runs the search and saves the results as a new list. Same filters as Search people, in the body.", "operationId": "post-search-people-import", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "list_name": "UK SaaS founders", "matched": 100, "imported": 91, "duplicate": 4, "suppressed": 1, "unsendable": 4 } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "list_name": { "type": "string", "description": "Name for the new list." }, "q": { "type": "string", "description": "Free text: name, title or company." }, "titles": { "type": "array", "description": "Job titles, up to 12." }, "seniorities": { "type": "array", "description": "Any of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern." }, "countries": { "type": "array", "description": "Countries, up to 12." }, "industries": { "type": "array", "description": "Industries, up to 12 (on plans with People search)." }, "companies": { "type": "array", "description": "Company names or domains, up to 25." }, "company_mode": { "type": "string", "description": "With companies: current, previous or either. Default current." }, "total": { "type": "integer", "description": "How many people to take, up to your plan limit. Default 100." }, "per_company": { "type": "integer", "description": "At most this many per company. Default 10." } }, "required": [] } } } } } }, "/search/companies": { "get": { "tags": [ "Find people and companies" ], "summary": "Search companies", "description": "Count and a 25-row preview.", "operationId": "get-search-companies", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free text: company name or domain.", "schema": { "type": "string" } }, { "name": "industries", "in": "query", "required": false, "description": "Industries.", "schema": { "type": "array" } }, { "name": "countries", "in": "query", "required": false, "description": "Countries.", "schema": { "type": "array" } }, { "name": "job_title", "in": "query", "required": false, "description": "Companies hiring for this title.", "schema": { "type": "string" } }, { "name": "sizes", "in": "query", "required": false, "description": "Employee bands: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+.", "schema": { "type": "array" } }, { "name": "total", "in": "query", "required": false, "description": "How many companies to take, up to your plan limit. Default 100.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "total": 312, "preview": [ { "name": "Example Ltd", "domain": "example.com", "industry": "Software", "size": "51-200", "location": "London, United Kingdom", "open_roles": 6 } ] } } } } } } } }, "/search/companies/import": { "post": { "tags": [ "Find people and companies" ], "summary": "Import a company search", "description": "Saves the matching companies as a new list, one row per company.", "operationId": "post-search-companies-import", "parameters": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "list_id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10", "list_name": "Hiring SaaS companies", "matched": 100, "imported": 100, "duplicate": 0, "failed": 0 } } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "list_name": { "type": "string", "description": "Name for the new list." }, "q": { "type": "string", "description": "Free text: company name or domain." }, "industries": { "type": "array", "description": "Industries." }, "countries": { "type": "array", "description": "Countries." }, "job_title": { "type": "string", "description": "Companies hiring for this title." }, "sizes": { "type": "array", "description": "Employee bands: 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+." }, "total": { "type": "integer", "description": "How many companies to take, up to your plan limit. Default 100." } }, "required": [] } } } } } } } }