{ "openapi": "3.1.0", "info": { "title": "API Explorer", "description": "The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the \"Try it\" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text.", "version": "2.0.0" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "def-0": { "title": "Account", "description": "An email account that can be used to send campaigns", "x-tags": [ "Schemas", "Account" ], "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the account", "format": "email", "example": "user@example.com" }, "timestamp_created": { "type": "string", "description": "Timestamp when the account was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.723Z" }, "timestamp_updated": { "type": "string", "description": "Timestamp when the account was last updated", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.723Z" }, "first_name": { "type": "string", "description": "First name associated with the account", "example": "John" }, "last_name": { "type": "string", "description": "Last name associated with the account", "example": "Doe" }, "warmup": { "type": "object", "description": "Warmup configuration for the account", "properties": { "limit": { "type": "number", "description": "Email sending limit for the account", "example": 100 }, "advanced": { "type": "object", "description": "Advanced settings for the account", "properties": { "warm_ctd": { "type": "boolean", "description": "Whether the account is in warm CTD mode", "example": false }, "open_rate": { "type": "number", "description": "Email open rate for the account", "example": 0.95 }, "important_rate": { "type": "number", "description": "Important email rate for the account", "example": 0.8 }, "read_emulation": { "type": "boolean", "description": "Whether read emulation is enabled", "example": true }, "spam_save_rate": { "type": "number", "description": "Spam save rate for the account", "example": 0.02 }, "weekday_only": { "type": "boolean", "description": "Whether to send emails only on weekdays", "example": true } } }, "warmup_custom_ftag": { "type": "string", "description": "Custom tag for the account", "example": "warmup" }, "increment": { "type": "string", "enum": [ "disabled", "0", "1", "2", "3", "4" ], "x-enumDescriptions": { "0": "0", "1": "1", "2": "2", "3": "3", "4": "4", "disabled": "Disabled" }, "description": "Daily increment added to the sending limit, starting from 0, until the full daily limit is reached (slow ramp). Gradually increases sending volume to improve deliverability. Set to `disabled` to send at the full daily limit from day one.", "example": "disabled" }, "reply_rate": { "type": "number", "description": "Reply rate for the account", "example": 0.1 } } }, "added_by": { "type": [ "null", "string" ], "description": "User ID who added the account", "readOnly": true, "format": "uuid", "example": "019e0e40-2a63-7e31-8919-0d081e8c4d7e" }, "daily_limit": { "type": [ "null", "number" ], "description": "Daily email sending limit", "example": 100 }, "modified_by": { "type": [ "null", "string" ], "description": "User ID who last modified the account", "readOnly": true, "format": "uuid", "example": "019e0e40-2a63-7e31-8919-0d0937416f6f" }, "tracking_domain_name": { "type": [ "null", "string" ], "description": "Tracking domain", "example": "example.com" }, "tracking_domain_status": { "type": [ "null", "string" ], "description": "Tracking domain status", "example": "active" }, "status": { "type": "number", "description": "Current status of the account", "readOnly": true, "enum": [ 1, 2, 3, -1, -2, -3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Temporarily paused for maintenance; will be automatically resumed shortly", "-1": "Connection Error", "-2": "Soft Bounce Error", "-3": "Sending Error" }, "example": 1 }, "enable_slow_ramp": { "type": [ "null", "boolean" ], "description": "Whether to enable slow ramp up for sending limits", "example": false }, "inbox_placement_test_limit": { "type": [ "null", "number" ], "description": "The limit for inbox placement tests", "minimum": 0, "example": 10 }, "organization": { "type": "string", "description": "Organization ID that owns this account", "readOnly": true, "format": "uuid", "example": "019e0e40-2a63-7e31-8919-0d0a20addc74" }, "timestamp_last_used": { "type": [ "null", "string" ], "description": "Timestamp when the account was last used", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.723Z" }, "warmup_status": { "type": "number", "description": "Current warmup status of the account", "readOnly": true, "enum": [ 0, 1, -1, -2, -3 ], "x-enumDescriptions": { "0": "Paused", "1": "Active", "-1": "Banned", "-2": "Spam Folder Unknown", "-3": "Permanent Suspension" }, "example": 1 }, "status_message": { "type": "object", "description": "Status message for the account", "readOnly": true, "properties": { "code": { "type": "string", "example": "EENVELOPE" }, "command": { "type": "string", "example": "DATA" }, "response": { "type": "string", "example": "550-5.4.5 Daily user sending limit exceeded. For more information on Gmai" }, "e_message": { "type": "string", "example": "error: data command failed: 550-5.4.5 daily user sending limit exceeded" }, "responseCode": { "type": "number", "example": 550 } }, "additionalProperties": true }, "timestamp_warmup_start": { "type": [ "null", "string" ], "description": "Timestamp when warmup was started", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.723Z" }, "provider_code": { "type": "number", "description": "Provider code for the account. Please make sure to specify the right provider code, otherwise your account will not work.", "enum": [ 1, 2, 3, 4, 8 ], "x-enumDescriptions": { "1": "Custom IMAP/SMTP", "2": "Google", "3": "Microsoft", "4": "AWS", "8": "AirMail" }, "example": 2 }, "setup_pending": { "type": "boolean", "description": "Whether account setup is pending", "readOnly": true, "example": false }, "warmup_pool_id": { "type": [ "null", "string" ], "description": "ID of the warmup pool this account belongs to", "readOnly": true, "format": "uuid", "example": "019e0e40-2a63-7e31-8919-0d0b0c90f734" }, "is_managed_account": { "type": "boolean", "description": "Whether this is a managed account", "readOnly": true, "example": false }, "dfy_password_changed": { "type": [ "null", "boolean" ], "description": "Whether DFY password has been changed", "readOnly": true, "example": false }, "stat_warmup_score": { "type": [ "null", "number" ], "description": "Warmup score for the account", "readOnly": true, "example": 85 }, "sending_gap": { "type": "number", "description": "The gap between emails sent from this account in minutes (minimum wait time when used with multiple campaigns)", "minimum": 0, "maximum": 1440, "example": 10 }, "signature": { "type": [ "null", "string" ], "description": "Email signature for the account", "example": "Best regards, John Doe" }, "autofix_failed": { "type": [ "null", "boolean" ], "description": "Whether automatic reconnection attempts have failed. null = in progress, true = failed, false = succeeded.", "readOnly": true, "example": false } }, "required": [ "email", "timestamp_created", "timestamp_updated", "first_name", "last_name", "organization", "warmup_status", "provider_code", "setup_pending", "is_managed_account" ], "additionalProperties": false }, "def-1": { "title": "Campaign", "description": "A campaign that can be sent to a list of recipients", "x-tags": [ "Schemas", "Campaign" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the campaign", "readOnly": true, "format": "uuid", "example": "019e0e40-2a04-7f00-88ba-0d179dd98e69" }, "name": { "type": "string", "description": "Name of the campaign", "example": "My First Campaign" }, "pl_value": { "type": [ "null", "number" ], "description": "Value of every positive lead", "example": 100 }, "status": { "type": "number", "description": "Campaign Status", "readOnly": true, "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 }, "is_evergreen": { "type": [ "null", "boolean" ], "description": "Whether the campaign is evergreen", "example": false }, "campaign_schedule": { "type": "object", "description": "Campaign schedule", "properties": { "start_date": { "type": [ "null", "string" ], "format": "date", "description": "Start date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "end_date": { "type": [ "null", "string" ], "format": "date", "description": "End date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "My Schedule" }, "timing": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "09:00" }, "to": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "17:00" } }, "required": [ "from", "to" ] }, "days": { "type": "object", "minProperties": 1, "properties": { "0": { "type": "boolean", "example": true }, "1": { "type": "boolean", "example": true }, "2": { "type": "boolean", "example": true }, "3": { "type": "boolean", "example": true }, "4": { "type": "boolean", "example": true }, "5": { "type": "boolean", "example": false }, "6": { "type": "boolean", "example": false } } }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "example": "Etc/GMT+12" } }, "required": [ "name", "timing", "days", "timezone" ] }, "minItems": 1 } }, "required": [ "schedules" ] }, "sequences": { "type": "array", "description": "List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array", "items": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ], "x-enumDescriptions": { "email": "This steps represents an email" }, "description": "Type of step. This has to be 'email' always - it's the only supported type for now", "example": "email" }, "delay": { "type": "number", "description": "The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).", "example": 2 }, "delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.", "example": "days" }, "pre_delay": { "type": "number", "description": "The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).", "example": 2 }, "pre_delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.", "example": "days" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "example": "Hello {{firstName}}" }, "body": { "type": "string", "example": "Hey {{firstName}},\n\nI hope you are doing well." }, "v_disabled": { "type": "boolean", "description": "Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant", "example": true } }, "required": [ "subject", "body" ] } } }, "required": [ "type", "delay", "variants" ] } } }, "required": [ "steps" ] } }, "timestamp_created": { "type": "string", "description": "Timestamp when the campaign was created", "readOnly": true, "example": "2026-05-09T19:39:06.629Z" }, "timestamp_updated": { "type": "string", "description": "Timestamp when the campaign was last updated", "readOnly": true, "example": "2026-05-09T19:39:06.629Z" }, "email_gap": { "type": [ "null", "number" ], "description": "The gap between emails in minutes", "example": 10 }, "random_wait_max": { "type": [ "null", "number" ], "description": "The maximum random wait time in minutes", "example": 10 }, "text_only": { "type": [ "null", "boolean" ], "description": "Whether the campaign is text only", "example": false }, "first_email_text_only": { "type": [ "null", "boolean" ], "description": "Whether the campaign is send the first email as a text only", "example": false }, "email_list": { "type": "array", "description": "List of accounts to use for sending emails", "items": { "type": "string", "example": "john@doe.com" } }, "daily_limit": { "type": [ "null", "number" ], "description": "The daily limit for sending emails", "example": 100 }, "stop_on_reply": { "type": [ "null", "boolean" ], "description": "Whether to stop the campaign on reply", "example": false }, "email_tag_list": { "type": "array", "description": "List of tags to use for sending emails", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91e96ef650a9" } }, "link_tracking": { "type": [ "null", "boolean" ], "description": "Whether to track links in emails", "example": true }, "open_tracking": { "type": "boolean", "description": "Whether to track opens in emails", "example": true }, "stop_on_auto_reply": { "type": [ "null", "boolean" ], "description": "Whether to stop the campaign on auto reply", "example": false }, "daily_max_leads": { "type": [ "null", "integer" ], "description": "The daily maximum new leads to contact", "minimum": 0, "example": 100 }, "prioritize_new_leads": { "type": [ "null", "boolean" ], "description": "Whether to prioritize new leads", "example": false }, "auto_variant_select": { "type": [ "null", "object" ], "description": "Auto variant select settings", "properties": { "trigger": { "type": "string", "enum": [ "reply_rate", "click_rate", "open_rate" ], "examples": [ "click_rate" ] } }, "required": [ "trigger" ] }, "match_lead_esp": { "type": [ "null", "boolean" ], "description": "Whether to match leads by ESP", "example": false }, "not_sending_status": { "type": [ "null", "number" ], "description": "Campaign not sending status", "readOnly": true, "enum": [ 1, 2, 3, 4, 99 ], "x-enumDescriptions": { "1": "Campaign is currently not within its sending schedule.", "2": "Campaign is currently waiting for a lead to process.", "3": "Campaign has reached its daily sending limit.", "4": "All sending accounts for this campaign have reached their daily sending limit.", "99": "Campaign is currently not sending due to an error. Please contact support for assistance." }, "example": 2 }, "stop_for_company": { "type": [ "null", "boolean" ], "description": "Whether to stop the campaign for the entire company(domain) when a lead replies", "example": false }, "core_variables": { "type": [ "null", "object" ], "description": "Campaign core variables", "readOnly": true, "additionalProperties": true }, "custom_variables": { "type": [ "null", "object" ], "description": "Campaign custom variables", "readOnly": true, "additionalProperties": true }, "insert_unsubscribe_header": { "type": [ "null", "boolean" ], "description": "Whether to insert an unsubscribe header in emails", "example": false }, "allow_risky_contacts": { "type": [ "null", "boolean" ], "description": "Whether to allow risky contacts", "example": false }, "disable_bounce_protect": { "type": [ "null", "boolean" ], "description": "Whether to disable bounce protection", "example": false }, "limit_emails_per_company_override": { "type": [ "null", "object" ], "description": "Overrides the workspace-wide limit emails per company setting for this campaign.", "properties": { "mode": { "type": "string", "enum": [ "custom", "disabled" ], "examples": [ "custom" ] }, "daily_limit": { "type": "number", "minimum": 1, "examples": [ 3 ] }, "scope": { "type": "string", "enum": [ "per_campaign", "across_workspace" ], "examples": [ "per_campaign" ] } }, "required": [ "mode" ] }, "cc_list": { "type": "array", "description": "List of accounts to CC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "bcc_list": { "type": "array", "description": "List of accounts to BCC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "organization": { "type": [ "null", "string" ], "description": "Organization ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91eacec5866a" }, "owned_by": { "type": [ "null", "string" ], "description": "Owner ID", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91ebee0ac63c" }, "ai_sdr_id": { "type": [ "null", "string" ], "description": "AI Sales Agent ID that created this campaign", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91ec400e40a2" }, "provider_routing_rules": { "type": "array", "description": "Auto variant select settings", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "send", "do_not_send" ], "example": "send" }, "recipient_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } }, "sender_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } } } }, "required": [ "action", "recipient_esp", "sender_esp" ] } }, "required": [ "id", "name", "status", "campaign_schedule", "timestamp_created", "timestamp_updated" ], "additionalProperties": false }, "def-2": { "title": "Email", "description": "A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox", "x-tags": [ "Schemas", "Email" ], "type": "object", "properties": { "id": { "type": "string", "description": "A Unique identifier", "readOnly": true, "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2d7e6dc7168" }, "timestamp_created": { "type": "string", "description": "Timestamp when the email was added to our database. This is not the timestamp of the email itself, since the email could have been sent at a different time. Please check the `timestamp_email` field for the timestamp of the email.", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.742Z" }, "timestamp_email": { "type": "string", "description": "The timestamp of the email, as provided by the email server. Please note that the timestamp is not always accurate, as it can be manipulated by the sender or the email server.", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.742Z" }, "message_id": { "type": "string", "description": "Unique email ID from the email server", "readOnly": true, "example": "" }, "subject": { "type": "string", "description": "Subject line of the email message", "example": "Re: Your inquiry" }, "from_address_email": { "type": [ "null", "string" ], "description": "The sender email address, populated based on the eaccount", "readOnly": true, "format": "email", "example": "sender@example.com" }, "to_address_email_list": { "type": "string", "description": "Comma-separated list of recipient email addresses", "example": "recipient@example.com" }, "cc_address_email_list": { "type": [ "null", "string" ], "description": "Comma-separated list of CC email addresses", "example": "cc@example.com" }, "bcc_address_email_list": { "type": [ "null", "string" ], "description": "Comma-separated list of BCC email addresses", "example": "bcc@example.com" }, "reply_to": { "type": [ "null", "string" ], "description": "Reply-to email address", "example": "replyto@example.com" }, "body": { "type": "object", "description": "An object containing the email body in HTML and text format", "readOnly": true, "properties": { "text": { "type": "string", "description": "Text content of the email", "example": "This is a test email" }, "html": { "type": "string", "description": "HTML content of the email", "example": "

This is a test email

" } } }, "organization_id": { "type": "string", "description": "The workspace ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2d8dfac0475" }, "campaign_id": { "type": [ "null", "string" ], "description": "The id of the campaign that the email is associated with (it can be null for manually sent emails)", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2d99dedba8b" }, "subsequence_id": { "type": [ "null", "string" ], "description": "The id of the campaign subsequence that the email is associated with (it can be null for manually sent emails)", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2dabb89af11" }, "list_id": { "type": [ "null", "string" ], "description": "The id of the list (if the lead is part of a list)", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2db8a0d5dd2" }, "lead": { "type": [ "null", "string" ], "description": "The email address of the lead that the email is associated with", "example": "jondoe@example.com" }, "lead_id": { "type": [ "null", "string" ], "description": "The lead id (if any)", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2dcb3a61f96" }, "eaccount": { "type": "string", "description": "The email account that was used to send the email. This needs to be validated to make sure it exists in the user workspace", "example": "eaccount-123" }, "ue_type": { "type": [ "null", "number" ], "description": "Email type based on the life cycle of the email", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "Sent from campaign", "2": "Received", "3": "Sent", "4": "Scheduled" }, "example": 3 }, "step": { "type": [ "null", "string" ], "description": "The campaign step that the email is associated with", "example": "step-123" }, "is_unread": { "type": [ "null", "number" ], "description": "Indicates if the email is unread", "example": 1 }, "is_auto_reply": { "type": [ "null", "number" ], "description": "Indicates if the email is an auto-reply. 0 (zero) - is false, and 1 is true", "readOnly": true, "example": 0 }, "reminder_ts": { "type": [ "null", "string" ], "description": "Timestamp for the reminder.", "format": "date-time", "example": "2026-05-09T19:39:06.742Z" }, "ai_interest_value": { "type": [ "null", "number" ], "description": "AI interest value", "example": 0.75 }, "ai_assisted": { "type": [ "null", "number" ], "description": "Indicates if AI assistance was used", "example": 1 }, "is_focused": { "type": [ "null", "number" ], "description": "Indicates if the email is focused (is in the primary tab in the Unibox)", "example": 1 }, "i_status": { "type": [ "null", "number" ], "description": "Indicates the interest status of the email", "example": 0 }, "thread_id": { "type": [ "null", "string" ], "description": "Identifier for the email thread. All the emails in the same thread have the same thread ID", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2dde327d1e5" }, "content_preview": { "type": [ "null", "string" ], "description": "A short preview of the email content (usually the first few lines of the email)", "example": "This is a preview of the email content." }, "attachment_json": { "type": [ "null", "object" ], "description": "Attachment metadata for the email. This field is null when there are no attachments.", "readOnly": true, "properties": { "files": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "filename" ], "properties": { "filename": { "type": "string", "description": "Attachment file name", "examples": [ "attachment.pdf" ] }, "size": { "type": "number", "description": "Attachment file size in bytes", "examples": [ 1927 ] }, "type": { "type": "string", "description": "Attachment MIME type", "examples": [ "application/pdf" ] }, "url": { "type": "string", "format": "uri", "description": "Download URL when available", "examples": [ "https://cdn.instantly.ai/example-attachment/file.pdf" ] }, "error": { "type": [ "null", "string" ], "description": "Error description when the attachment failed to upload", "examples": [ "Upload failed" ] } } } } }, "required": [ "files" ], "additionalProperties": false, "example": { "files": [ { "filename": "attachment", "size": 1927, "type": "text/css", "url": "https://cdn.instantly.ai/example-attachment/", "error": null } ] } }, "from_address_json": { "type": [ "null", "array" ], "description": "List of from address details" }, "to_address_json": { "type": [ "null", "array" ], "description": "List of to address details" }, "cc_address_json": { "type": [ "null", "array" ], "description": "List of CC address details" }, "ai_agent_id": { "type": [ "null", "string" ], "description": "ID of the AI agent that sent this email (if applicable)", "format": "uuid", "example": "019e0e40-2a76-7006-be72-c2de0949c3aa" } }, "required": [ "id", "timestamp_created", "timestamp_email", "message_id", "subject", "to_address_email_list", "body", "organization_id", "eaccount" ], "additionalProperties": false }, "def-3": { "title": "Email Verification", "description": "A single email verification", "x-tags": [ "Schemas", "EmailVerification" ], "type": "object", "properties": { "status": { "type": [ "null", "string" ], "description": "The request status. Do not use this field to determine the verification status. Please use `verification_status` instead to check the verification status", "readOnly": true, "enum": [ "success", "error" ], "x-enumDescriptions": { "success": "The verification was successful", "error": "The verification was unsuccessful" }, "example": "success" }, "email": { "type": "string", "description": "The email address to verify", "example": "example@example.com" }, "verification_status": { "type": "string", "description": "The verification status.", "readOnly": true, "enum": [ "pending", "verified", "invalid" ], "x-enumDescriptions": { "pending": "The verification is pending", "verified": "The verification is verified", "invalid": "The verification is invalid" }, "example": "pending" }, "catch_all": { "type": [ "boolean", "string" ], "description": "Whether this is a catch-all email address", "readOnly": true, "enum": [ true, false, "pending" ], "x-enumDescriptions": { "false": "The email is not a catch-all", "true": "The email is a catch-all", "pending": "The catch-all status is pending" }, "example": true }, "credits": { "type": [ "null", "number" ], "description": "The number of verification credits available after the verification", "readOnly": true, "example": 100 }, "credits_used": { "type": [ "null", "number" ], "description": "The number of verification credits used", "readOnly": true, "example": 1 } }, "required": [ "email", "verification_status" ], "additionalProperties": false }, "def-4": { "title": "Lead List", "description": "A list used to store leads", "x-tags": [ "Schemas", "LeadList" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the lead list", "readOnly": true, "format": "uuid", "example": "019e0e40-2a37-7997-8b57-0780506b9ba2" }, "organization_id": { "type": "string", "description": "Organization ID that owns this lead list", "readOnly": true, "format": "uuid", "example": "019e0e40-2a37-7997-8b57-07813b3cdb17" }, "has_enrichment_task": { "type": [ "null", "boolean" ], "description": "Whether this list runs the enrichment process on every added lead or not", "example": false }, "owned_by": { "type": [ "null", "string" ], "description": "User ID of the owner of this lead list. Defaults to the user that created the list", "format": "uuid", "example": "019e0e40-2a37-7997-8b57-0782a116aef9" }, "name": { "type": "string", "description": "Name of the lead list", "example": "My Lead List" }, "timestamp_created": { "type": "string", "description": "Timestamp when the lead list was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.679Z" } }, "required": [ "id", "organization_id", "name", "timestamp_created" ], "additionalProperties": false }, "def-5": { "title": "Inbox Placement Test", "description": "An inbox placement test", "x-tags": [ "Schemas", "InboxPlacementTest" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the inbox placement test", "readOnly": true, "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e3baff63a4" }, "organization_id": { "type": "string", "description": "Organization ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e4f68637aa" }, "name": { "type": "string", "description": "Name of the inbox placement test", "example": "My Inbox Placement Test" }, "delivery_mode": { "type": [ "null", "number" ], "description": "Whether to send emails one by one or all together", "enum": [ 1, 2, null ], "x-enumDescriptions": { "1": "One by one", "2": "All together" }, "example": 1 }, "description": { "type": [ "null", "string" ], "description": "Description of the inbox placement test", "example": "This is a test description" }, "schedule": { "type": "object", "description": "Specifies the date and time when the automated inbox placement tests will be sent.", "properties": { "days": { "type": "object", "description": "Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days.", "additionalProperties": { "type": "boolean", "examples": [ false ] }, "example": { "0": false, "1": false, "2": true, "3": true, "4": false, "5": false, "6": false } }, "timing": { "type": "object", "properties": { "from": { "type": "string", "description": "The time of day when the test will start (24-hour format).", "example": "02:30" } }, "description": "Timing configuration for the scheduled test." }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "description": "Timezone in which the schedule is set, in IANA timezone format.", "example": "Etc/GMT+12" } }, "example": { "days": { "2": true, "3": true }, "timing": { "from": "02:30" }, "timezone": "America/Chihuahua" } }, "type": { "type": "number", "description": "Whether the inbox placement test is a one-time test or an automated test", "enum": [ 1, 2 ], "example": 1 }, "sending_method": { "type": "number", "description": "Whether the inbox placement test will be sent from Instantly or from outside Instantly", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "From Instantly", "2": "From Outside Instantly" }, "example": 1 }, "campaign_id": { "type": [ "null", "string" ], "description": "Campaign ID", "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e516e732f9" }, "email_subject": { "type": "string", "description": "Email subject of the inbox placement test", "example": "My Email Subject" }, "email_body": { "type": "string", "description": "Email body of the inbox placement test", "example": "Hi, this is my email body" }, "emails": { "type": "array", "description": "Emails to send the inbox placement test to", "items": { "type": "string", "example": "john@doe.com" } }, "test_code": { "type": [ "null", "string" ], "description": "Code for identifying the inbox placement tests in the email body from outside Instantly", "example": "ptid_9YWg_TkNb-pz-paVrQr07" }, "tags": { "type": [ "null", "array" ], "description": "List of tag IDs to use for sending emails", "items": { "type": "string", "format": "uuid", "examples": [ "019e0e40-2a29-76cc-8980-b9e6e488a607" ] } }, "text_only": { "type": [ "null", "boolean" ], "description": "Disables open tracking", "example": true }, "recipients": { "type": "array", "readOnly": true, "items": { "type": "string", "example": "johndoe@instantly.ai" } }, "recipients_labels": { "type": "array", "description": "A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the `GET: /inbox-placement-tests/email-service-provider-options` endpoint", "items": { "type": "object", "properties": { "region": { "type": "string", "description": "The region to send emails to", "example": "North America" }, "sub_region": { "type": "string", "description": "The sub-region to send emails to", "example": "US" }, "type": { "type": "string", "description": "The type of email to send", "example": "Professional" }, "esp": { "type": "string", "description": "The Email Service Provider (ESP) to send emails to", "example": "Google" } }, "required": [ "region", "sub_region", "type", "esp" ] } }, "timestamp_created": { "type": "string", "description": "Timestamp when the inbox placement test was created", "readOnly": true, "example": "2026-05-09T19:39:06.665Z" }, "timestamp_next_run": { "type": [ "null", "string" ], "description": "Timestamp when the inbox placement test will run next", "example": "2026-05-09T19:39:06.665Z" }, "automations": { "type": [ "null", "array" ], "description": "Optional automations to trigger based on conditions", "minItems": 0, "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "condition": { "type": "string", "description": "Condition for automation trigger", "enum": [ "placement_goes_below", "placement_goes_above", "added_to_blacklists", "removed_from_blacklists" ], "examples": [ "placement_goes_below" ] }, "condition_value": { "type": [ "null", "number" ], "description": "Value for condition, if applicable", "examples": [ 80 ] } }, "required": [ "condition" ] }, "then": { "type": "object", "properties": { "webhook_url": { "type": "string", "examples": [ "https://example.com/webhook" ] }, "pause_sending_campaigns_for": { "type": "number", "description": "Number of days to pause sending campaigns for", "examples": [ 14 ] }, "pause": { "type": "boolean", "examples": [ true ] }, "enable_slow_ramp": { "type": "boolean", "examples": [ true ] }, "disable_slow_ramp": { "type": "boolean", "examples": [ true ] }, "add_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "examples": [ "019e0e40-2a2a-7b5f-baa1-75bb1404084c" ] }, "examples": [ [ "019e0e40-2a2a-7b5f-baa1-75bcf5869f13" ] ] }, "remove_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "examples": [ "019e0e40-2a2a-7b5f-baa1-75bd0cec1c31" ] } } }, "minProperties": 1, "description": "Actions to take when condition is met" } }, "required": [ "when", "then" ] } }, "status": { "type": [ "null", "number" ], "description": "Status of the inbox placement test", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed" }, "example": 1 }, "not_sending_status": { "type": [ "null", "string" ], "description": "Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.", "enum": [ "daily_limits_hit", "other" ], "x-enumDescriptions": { "daily_limits_hit": "Daily limits hit", "other": "Other reason" }, "example": "daily_limits_hit" } }, "required": [ "id", "organization_id", "name", "type", "sending_method", "email_subject", "email_body", "emails", "recipients", "timestamp_created" ], "additionalProperties": false }, "def-6": { "title": "Inbox Placement Analytics", "description": "Analytics data for individual emails in inbox placement tests", "x-tags": [ "Schemas", "InboxPlacementAnalytics" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the inbox placement analytics entry", "readOnly": true, "format": "uuid", "example": "019e0e40-2a0b-7bbe-b807-4447ad655b2d" }, "timestamp_created": { "type": "string", "description": "Timestamp when the inbox placement analytics was created", "readOnly": true, "example": "2026-05-09T19:39:06.635Z" }, "timestamp_created_date": { "type": "string", "description": "Date when the inbox placement analytics was created", "readOnly": true, "example": "2026-05-09" }, "organization_id": { "type": "string", "description": "Organization ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a0b-7bbe-b807-4448db724217" }, "test_id": { "type": "string", "description": "Inbox Placement Test ID", "format": "uuid", "example": "019e0e40-2a0b-7bbe-b807-444967f7c348" }, "is_spam": { "type": [ "null", "boolean" ], "description": "Indicates if the email landed in spam (null if not determined). Only present when record_type is 2 (received).", "example": true }, "has_category": { "type": [ "null", "boolean" ], "description": "Indicates if the email was categorized like promotions, social, etc. (null if not determined). Only present when record_type is 2 (received).", "example": true }, "sender_email": { "type": [ "null", "string" ], "description": "Email address of the sender", "example": "sender@example.com" }, "sender_esp": { "type": [ "null", "number" ], "description": "The sender ESP (Email Service Provider). Only present when record_type is 2 (received).", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "recipient_email": { "type": [ "null", "string" ], "description": "Email address of the recipient", "example": "recipient@example.com" }, "recipient_esp": { "type": [ "null", "number" ], "description": "The recipient ESP (Email Service Provider)", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "recipient_geo": { "type": [ "null", "number" ], "description": "The geographic location of the recipient", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "United States", "2": "Italy", "3": "Germany", "4": "France" }, "example": 1 }, "recipient_type": { "type": [ "null", "number" ], "description": "The type of recipient", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Professional", "2": "Personal" }, "example": 1 }, "spf_pass": { "type": [ "null", "boolean" ], "description": "Indicates if the email passed SPF validation. Only present when record_type is 2 (received).", "example": true }, "dkim_pass": { "type": [ "null", "boolean" ], "description": "Indicates if the email passed DKIM validation. Only present when record_type is 2 (received).", "example": true }, "dmarc_pass": { "type": [ "null", "boolean" ], "description": "Indicates if the email passed DMARC validation. Only present when record_type is 2 (received).", "example": true }, "smtp_ip_blacklist_report": { "type": [ "null", "object" ], "description": "Blacklist report for the SMTP IP address. Only present when record_type is 2 (received)." }, "authentication_failure_results": { "type": [ "null", "object" ], "description": "Details of authentication failures for SPF, DKIM, and DMARC. Only present when record_type is 2 (received).", "properties": { "authentication_results": { "type": "string", "description": "Authentication results", "examples": [ "Authentication-Results: smtp.local;\r\n\tdkim=pass header.d=gappssmtp.com\r\n header.b=ABC123" ] }, "dkim_signature": { "type": "string", "description": "DKIM signature", "examples": [ "DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gappssmtp.com; s=20161025;\r\n h=mime-version:from:date:message-id:subject:to; bh=ABC123; b=ABC123" ] }, "received_spf": { "type": "string", "description": "Received SPF", "examples": [ "Received-SPF: pass" ] } } }, "record_type": { "type": [ "null", "number" ], "description": "The type of record (sent or received)", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Sent", "2": "Received" }, "example": 1 } }, "required": [ "id", "timestamp_created", "timestamp_created_date", "organization_id", "test_id" ], "additionalProperties": false }, "def-7": { "title": "Inbox Placement Blacklist & SpamAssassin Report", "description": "Report data for an inbox placement test", "x-tags": [ "Schemas", "InboxPlacementBlacklist&SpamAssassinReport" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the inbox placement report entry", "readOnly": true, "format": "uuid", "example": "019e0e40-2a15-756a-b15a-d95c96a334bd" }, "timestamp_created": { "type": "string", "description": "Timestamp when the inbox placement report was created", "readOnly": true, "example": "2026-05-09T19:39:06.645Z" }, "timestamp_created_date": { "type": "string", "description": "Date when the inbox placement report was created", "readOnly": true, "example": "2026-05-09" }, "organization_id": { "type": "string", "description": "Organization ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a15-756a-b15a-d95d10c89fcb" }, "test_id": { "type": "string", "description": "Inbox Placement Test ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a15-756a-b15a-d95e9725ce9b" }, "domain_blacklist_count": { "type": [ "null", "number" ], "description": "Count of blacklists the domain is listed on", "readOnly": true, "example": 5 }, "domain": { "type": "string", "description": "Domain of the inbox placement report", "readOnly": true, "example": "growinstantly.com" }, "domain_ip": { "type": "string", "description": "IP address of the domain", "readOnly": true, "example": "192.168.1.1" }, "domain_ip_blacklist_count": { "type": [ "null", "number" ], "description": "Count of blacklists the domain IP is listed on", "readOnly": true, "example": 3 }, "spam_assassin_score": { "type": "number", "description": "SpamAssassin score for the email, indicating spam likelihood", "readOnly": true, "example": 2.5 }, "spam_assassin_report": { "type": "object", "description": "Detailed SpamAssassin analysis report", "readOnly": true, "properties": { "is_spam": { "type": "boolean", "description": "Indicates if the message is classified as spam by SpamAssassin", "example": false }, "report": { "type": "array", "description": "List of individual SpamAssassin rule evaluations", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "The section or type of the rule triggered", "example": "BODY" }, "name": { "type": "string", "description": "The name of the SpamAssassin rule", "example": "HTML_MESSAGE" }, "score": { "type": "string", "description": "The score assigned to this rule evaluation", "example": "0.0" } }, "required": [ "description", "name", "score" ] } }, "spam_score": { "type": "integer", "description": "Overall spam score assigned to the message by SpamAssassin", "example": 0 } } }, "blacklist_report": { "type": "object", "description": "Detailed blacklist report for the domain or IP", "readOnly": true, "properties": { "address": { "type": "string", "description": "The address or domain associated with the report", "example": "growinstantly.com" }, "blacklisted_count": { "type": "integer", "description": "The count of blacklists the address is listed on", "example": 5 }, "details": { "type": "array", "description": "List of individual blacklist details", "items": { "properties": { "blacklist": { "type": "string", "description": "The name of the blacklist", "example": "zen.spamhaus.org" }, "is_listed": { "type": "boolean", "description": "Whether the address is listed on this blacklist", "example": true }, "test_type": { "type": "string", "description": "The type of test", "example": "ip" } }, "type": "object" } }, "ip": { "type": "string", "description": "The IP address associated with the blacklist check", "example": "104.21.62.47" }, "is_blacklisted": { "type": "boolean", "description": "Overall status indicating if the address is blacklisted", "example": true }, "is_domain": { "type": "boolean", "description": "Whether the address is a domain", "example": true } } } }, "required": [ "id", "timestamp_created", "timestamp_created_date", "organization_id", "test_id", "domain", "domain_ip", "spam_assassin_score" ], "additionalProperties": false }, "def-9": { "title": "API Key", "description": "API Key", "x-tags": [ "Schemas", "APIKey" ], "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "format": "uuid", "example": "019e0e40-29ec-73b0-8e7c-52642754d015" }, "name": { "type": "string", "example": "My API Key" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "all:all", "all:create", "all:read", "all:update", "all:delete", "ai_agents:all", "ai_agents:create", "ai_agents:read", "ai_agents:update", "ai_agents:delete", "api_keys:all", "api_keys:create", "api_keys:read", "api_keys:update", "api_keys:delete", "audit_logs:all", "audit_logs:create", "audit_logs:read", "audit_logs:update", "audit_logs:delete", "custom_prompt_templates:all", "custom_prompt_templates:create", "custom_prompt_templates:read", "custom_prompt_templates:update", "custom_prompt_templates:delete", "account_campaign_mappings:all", "account_campaign_mappings:create", "account_campaign_mappings:read", "account_campaign_mappings:update", "account_campaign_mappings:delete", "campaigns:all", "campaigns:create", "campaigns:read", "campaigns:update", "campaigns:delete", "inbox_placement_tests:all", "inbox_placement_tests:create", "inbox_placement_tests:read", "inbox_placement_tests:update", "inbox_placement_tests:delete", "inbox_placement_analytics:all", "inbox_placement_analytics:create", "inbox_placement_analytics:read", "inbox_placement_analytics:update", "inbox_placement_analytics:delete", "inbox_placement_reports:all", "inbox_placement_reports:create", "inbox_placement_reports:read", "inbox_placement_reports:update", "inbox_placement_reports:delete", "lead_lists:all", "lead_lists:create", "lead_lists:read", "lead_lists:update", "lead_lists:delete", "leads:all", "leads:create", "leads:read", "leads:update", "leads:delete", "background-jobs:all", "background-jobs:create", "background-jobs:read", "background-jobs:update", "background-jobs:delete", "custom_tags:all", "custom_tags:create", "custom_tags:read", "custom_tags:update", "custom_tags:delete", "custom_tag_mappings:all", "custom_tag_mappings:create", "custom_tag_mappings:read", "custom_tag_mappings:update", "custom_tag_mappings:delete", "crm_actions:all", "crm_actions:create", "crm_actions:read", "crm_actions:update", "crm_actions:delete", "accounts:all", "accounts:create", "accounts:read", "accounts:update", "accounts:delete", "block_list_entries:all", "block_list_entries:create", "block_list_entries:read", "block_list_entries:update", "block_list_entries:delete", "lead-labels:all", "lead-labels:create", "lead-labels:read", "lead-labels:update", "lead-labels:delete", "email_verifications:all", "email_verifications:create", "email_verifications:read", "emails:all", "emails:create", "emails:read", "emails:update", "emails:delete", "email_templates:all", "email_templates:create", "email_templates:read", "email_templates:update", "email_templates:delete", "workspaces:all", "workspaces:create", "workspaces:read", "workspaces:update", "workspaces:delete", "workspace_billing:all", "workspace_billing:create", "workspace_billing:read", "workspace_billing:update", "workspace_billing:delete", "workspace_group_members:all", "workspace_group_members:create", "workspace_group_members:read", "workspace_group_members:update", "workspace_group_members:delete", "workspace_members:all", "workspace_members:create", "workspace_members:read", "workspace_members:update", "workspace_members:delete", "subsequences:all", "subsequences:create", "subsequences:read", "subsequences:update", "subsequences:delete", "ai_sdr:all", "ai_sdr:create", "ai_sdr:read", "ai_sdr:update", "ai_sdr:delete", "ai_sdr_replies:all", "ai_sdr_replies:create", "ai_sdr_replies:read", "ai_sdr_replies:update", "ai_sdr_replies:delete", "ai_inbox_manager_analytics:all", "ai_inbox_manager_analytics:create", "ai_inbox_manager_analytics:read", "ai_inbox_manager_analytics:update", "ai_inbox_manager_analytics:delete", "sales_flows:all", "sales_flows:create", "sales_flows:read", "sales_flows:update", "sales_flows:delete", "webhooks:all", "webhooks:create", "webhooks:read", "webhooks:update", "webhooks:delete", "webhook_events:all", "webhook_events:create", "webhook_events:read", "webhook_events:update", "webhook_events:delete", "security_tokens:all", "security_tokens:create", "security_tokens:read", "security_tokens:update", "security_tokens:delete", "dfy_email_account_orders:all", "dfy_email_account_orders:create", "dfy_email_account_orders:read", "dfy_email_account_orders:update", "dfy_email_account_orders:delete", "auth:all", "auth:create", "auth:read", "auth:update", "auth:delete" ], "example": "campaigns:create" } }, "key": { "type": "string", "readOnly": true, "example": "a1b2c3d4e5f6g7h8i9j0" }, "organization_id": { "type": "string", "readOnly": true, "format": "uuid", "example": "019e0e40-29fc-70a7-9a20-67d9edeb584d" }, "timestamp_created": { "type": "string", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.620Z" }, "timestamp_updated": { "type": "string", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.620Z" } }, "required": [ "id", "name", "scopes", "key", "organization_id", "timestamp_created", "timestamp_updated" ], "additionalProperties": false }, "def-10": { "title": "Account Campaign Mapping", "description": "Account Campaign Mapping", "x-tags": [ "Schemas", "AccountCampaignMapping" ], "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "example": "019e0e40-29e8-72b1-822e-81b908cd739e" }, "campaign_name": { "type": "string", "example": "Campaign Name" }, "timestamp_created": { "type": "string", "description": "Timestamp when the campaign was created", "readOnly": true, "example": "2026-05-09T19:39:06.600Z" }, "status": { "type": "number", "description": "Campaign Status", "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 } }, "required": [ "campaign_id", "campaign_name", "timestamp_created" ], "additionalProperties": false }, "def-11": { "title": "Lead", "description": "A lead entity representing an individual lead", "x-tags": [ "Schemas", "Lead" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the lead", "readOnly": true, "format": "uuid", "example": "019e0e40-12de-7d9a-a31b-084abffbbaa7" }, "timestamp_created": { "type": "string", "description": "Timestamp when the lead was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_updated": { "type": "string", "description": "Timestamp when the lead was last updated", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "organization": { "type": "string", "description": "Organization ID associated with the lead", "readOnly": true, "format": "uuid", "example": "019e0e40-12e1-78c6-856f-9799429512ca" }, "campaign": { "type": [ "null", "string" ], "description": "Campaign ID associated with the lead", "format": "uuid", "example": "019e0e40-12e1-78c6-856f-979aa2c7fd88" }, "status": { "type": "number", "description": "Status of the lead", "readOnly": true, "enum": [ 1, 2, 3, -1, -2, -3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed", "-1": "Bounced", "-2": "Unsubscribed", "-3": "Skipped" }, "example": 1 }, "email": { "type": [ "null", "string" ], "description": "Email address of the lead", "example": "example@example.com" }, "personalization": { "type": [ "null", "string" ], "description": "Personalization of the lead", "example": "Hello, how are you?" }, "website": { "type": [ "null", "string" ], "description": "Website of the lead", "example": "https://example.com" }, "last_name": { "type": [ "null", "string" ], "description": "Last name of the lead", "example": "Doe" }, "first_name": { "type": [ "null", "string" ], "description": "First name of the lead", "example": "John" }, "company_name": { "type": [ "null", "string" ], "description": "Company name of the lead", "example": "Example Inc." }, "job_title": { "type": [ "null", "string" ], "description": "Job title of the lead", "example": "Head of Growth" }, "phone": { "type": [ "null", "string" ], "description": "Phone number of the lead", "example": "+1234567890" }, "email_open_count": { "type": "number", "description": "Number of times the email was opened", "readOnly": true, "example": 0 }, "email_reply_count": { "type": "number", "description": "Number of times the email was replied to", "readOnly": true, "example": 0 }, "email_click_count": { "type": "number", "description": "Number of times the email was clicked", "readOnly": true, "example": 0 }, "company_domain": { "type": "string", "description": "Company domain of the lead", "readOnly": true, "example": "example.com" }, "status_summary": { "type": "object", "description": "Status summary of the lead", "readOnly": true, "properties": { "lastStep": { "type": "object", "properties": { "from": { "type": "string", "example": "campaign" }, "stepID": { "type": "string", "example": "019e0e40-12e1-78c6-856f-979b184e356e" }, "timestamp_executed": { "type": "string", "format": "date-time", "example": "2026-05-09T19:39:00.705Z" } } }, "domain_complete": { "type": "boolean", "example": true } } }, "payload": { "type": [ "null", "object" ], "description": "Lead custom variables. This object can contain any key, but the values have to be of type string, number, boolean, or null. We do NOT allow objects or arrays as values.", "readOnly": true, "properties": { "firstName": { "type": "string", "examples": [ "John" ] }, "lastName": { "type": "string", "examples": [ "Doe" ] }, "companyName": { "type": "string", "examples": [ "Acme Corp" ] }, "jobTitle": { "type": "string", "examples": [ "Head of Growth" ] }, "website": { "type": "string", "examples": [ "https://example.com" ] }, "phone": { "type": "string", "examples": [ "+1234567890" ] }, "personalization": { "type": "string", "examples": [ "Hi {{first_name}}, I noticed you work at {{company_name}}..." ] } }, "additionalProperties": { "type": [ "null", "string", "number", "boolean", "object" ] } }, "status_summary_subseq": { "type": "object", "description": "Subsequence status summary of the lead", "readOnly": true, "properties": { "from": { "type": "string", "example": "campaign" }, "stepID": { "type": "string", "example": "019e0e40-12e1-78c6-856f-979c25b29a50" }, "timestampExecuted": { "type": "string", "format": "date-time", "example": "2026-05-09T19:39:00.705Z" } } }, "last_step_from": { "type": [ "null", "string" ], "description": "Source of the last step", "readOnly": true, "example": "campaign" }, "last_step_id": { "type": [ "null", "string" ], "description": "ID of the last step", "readOnly": true, "format": "uuid", "example": "019e0e40-12e1-78c6-856f-979d36199826" }, "last_step_timestamp_executed": { "type": [ "null", "string" ], "description": "Timestamp when the last step was executed", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "email_opened_step": { "type": [ "null", "number" ], "description": "Last email step opened by the lead", "readOnly": true, "example": 1 }, "email_opened_variant": { "type": [ "null", "number" ], "description": "Last step variant opened by the lead", "readOnly": true, "example": 1 }, "email_replied_step": { "type": [ "null", "number" ], "description": "Last email step the lead has replied to", "readOnly": true, "example": 1 }, "email_replied_variant": { "type": [ "null", "number" ], "description": "Last step variant the lead has replied to", "readOnly": true, "example": 1 }, "email_clicked_step": { "type": [ "null", "number" ], "description": "Last email step the lead has clicked", "readOnly": true, "example": 1 }, "email_clicked_variant": { "type": [ "null", "number" ], "description": "Last step variant the lead has clicked", "readOnly": true, "example": 1 }, "lt_interest_status": { "type": "number", "description": "Lead interest status. It can be either a static value (check below), or a custom status interest value", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 }, "subsequence_id": { "type": [ "null", "string" ], "description": "ID of the subsequence", "readOnly": true, "example": "019e0e40-12e1-78c6-856f-979ed8db4bcd" }, "verification_status": { "type": "number", "description": "Verification status of the lead", "readOnly": true, "enum": [ 1, -1, -2, -3, -4, 11, 12 ], "x-enumDescriptions": { "1": "Verified", "11": "Pending", "12": "Pending Verification Job", "-1": "Invalid", "-2": "Risky", "-3": "Catch All", "-4": "Job Change" }, "example": 1 }, "pl_value_lead": { "type": [ "null", "string" ], "description": "Potential value of the lead", "example": "High" }, "timestamp_added_subsequence": { "type": [ "null", "string" ], "description": "Timestamp when the lead was added to the subsequence", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_last_contact": { "type": [ "null", "string" ], "description": "Timestamp of the last contact with the lead", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_last_open": { "type": [ "null", "string" ], "description": "Timestamp of the last email open", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_last_reply": { "type": [ "null", "string" ], "description": "Timestamp of the last email reply", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_last_interest_change": { "type": [ "null", "string" ], "description": "Timestamp of the last interest status change", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "timestamp_last_click": { "type": [ "null", "string" ], "description": "Timestamp of the last email click", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.705Z" }, "enrichment_status": { "type": "number", "description": "Enrichment status of the lead", "readOnly": true, "enum": [ 1, -1, 11, -2 ], "x-enumDescriptions": { "1": "Enriched", "11": "Pending", "-1": "Enrichment data not available", "-2": "Error" }, "example": 1 }, "list_id": { "type": [ "null", "string" ], "description": "List ID associated with the lead", "format": "uuid", "example": "019e0e40-12e1-78c6-856f-979f36881d5f" }, "last_contacted_from": { "type": [ "null", "string" ], "description": "Source of the last contact", "readOnly": true, "example": "email" }, "uploaded_by_user": { "type": [ "null", "string" ], "description": "ID of the user who uploaded the lead", "readOnly": true, "format": "uuid", "example": "019e0e40-12e1-78c6-856f-97a008e19dad" }, "upload_method": { "type": "string", "description": "Method used to upload the lead", "readOnly": true, "enum": [ "manual", "api", "website-visitor" ], "x-enumDescriptions": { "manual": "Manual", "api": "API", "website-visitor": "Website Visitor" }, "example": "manual" }, "assigned_to": { "type": [ "null", "string" ], "description": "ID of the user assigned to the lead", "format": "uuid", "example": "019e0e40-12e2-7a51-bfcc-4d94276e4b3a" }, "is_website_visitor": { "type": [ "null", "boolean" ], "description": "Indicates if the lead is a website visitor", "readOnly": true, "example": true }, "timestamp_last_touch": { "type": [ "null", "string" ], "description": "Timestamp of the last touch with the lead", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:00.706Z" }, "esp_code": { "type": "number", "description": "ESP code associated with the lead", "readOnly": true, "enum": [ 0, 1, 2, 3, 8, 9, 10, 12, 13, 999, 1000 ], "x-enumDescriptions": { "0": "In Queue", "1": "Google", "2": "Microsoft", "3": "Zoho", "8": "AirMail", "9": "Yahoo", "10": "Yandex", "12": "Web.de", "13": "Libero.it", "999": "Other", "1000": "Not Found" }, "example": 1 }, "esg_code": { "type": "number", "description": "ESG code associated with the lead", "readOnly": true, "enum": [ 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "In Queue", "1": "Barracuda", "2": "Mimecast", "3": "Proofpoint", "4": "Cisco" }, "example": 1 } }, "required": [ "id", "timestamp_created", "timestamp_updated", "organization", "status", "email_open_count", "email_reply_count", "email_click_count", "company_domain", "status_summary" ], "additionalProperties": false }, "def-12": { "title": "Background Job", "description": "A background job that can be used to perform long-running tasks", "x-tags": [ "Schemas", "BackgroundJob" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the background job", "readOnly": true, "example": "675266e304a8e55b17f0228b" }, "workspace_id": { "type": "string", "description": "Workspace ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a3f-7768-b9bc-99e9fa470a6a" }, "user_id": { "type": [ "null", "string" ], "description": "The id of the user that triggered the action that created the job", "readOnly": true, "format": "uuid", "example": "019e0e40-2a3f-7768-b9bc-99ea5dbaba47" }, "type": { "type": "string", "description": "Type of background job", "enum": [ "move-leads", "import-leads", "export-leads", "update-warmup-accounts", "rename-variable" ], "x-enumDescriptions": { "move-leads": "Move Leads", "import-leads": "Import Leads", "export-leads": "Export Leads", "update-warmup-accounts": "Update Warmup Accounts", "rename-variable": "Rename Variable" }, "example": "move-leads" }, "entity_id": { "type": [ "null", "string" ], "description": "The id of the entity that the job is related to", "format": "uuid", "example": "019e0e40-2a3f-7768-b9bc-99eb860fb65f" }, "entity_type": { "type": "string", "description": "Type of entity", "enum": [ "list", "campaign", "workspace" ], "x-enumDescriptions": { "list": "The entity is a lead list", "campaign": "The entity is a campaign", "workspace": "The entity is a workspace" }, "example": "list" }, "data": { "type": "object", "description": "Data about the job, used to store any additional information we need to process the job", "additionalProperties": true }, "progress": { "type": "number", "description": "Progress of the job as a percentage (from 0 to 100)", "minimum": 0, "maximum": 100, "example": 0 }, "status": { "type": "string", "description": "Job status", "enum": [ "pending", "in-progress", "success", "failed" ], "x-enumDescriptions": { "pending": "The background job is waiting in the queue to be processed", "in-progress": "The background job is being processed", "success": "The background job has been successfully processed", "failed": "The background job has failed" }, "example": "pending" }, "created_at": { "type": "string", "description": "Timestamp when the job was created", "example": "2026-05-09T19:39:06.687Z" }, "updated_at": { "type": "string", "description": "Timestamp when the job was last updated", "example": "2026-05-09T19:39:06.687Z" } }, "required": [ "id", "workspace_id", "type", "progress", "status", "created_at", "updated_at" ], "additionalProperties": false }, "def-13": { "title": "Custom Tag", "description": "A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.", "x-tags": [ "Schemas", "CustomTag" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the custom tag", "readOnly": true, "format": "uuid", "example": "019e0e40-2a48-79cf-ad50-f3d3ce0e4ba2" }, "timestamp_created": { "type": "string", "description": "Timestamp when the custom tag was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.696Z" }, "timestamp_updated": { "type": "string", "description": "Timestamp when the custom tag was last updated", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.696Z" }, "organization_id": { "type": "string", "description": "Organization ID that owns this custom tag", "readOnly": true, "format": "uuid", "example": "019e0e40-2a48-79cf-ad50-f3d486a16b3c" }, "label": { "type": "string", "description": "Display label for the custom tag", "example": "Important" }, "description": { "type": [ "null", "string" ], "description": "Detailed description of the custom tag purpose", "example": "Used for marking important items" } }, "required": [ "id", "timestamp_created", "timestamp_updated", "organization_id", "label" ], "additionalProperties": false }, "def-14": { "title": "Custom Tag Mapping", "description": "This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (`tag_id` field) with the email account (`resource_id` field). You can use it to see which tag si connected to which resource.", "x-tags": [ "Schemas", "CustomTagMapping" ], "type": "object", "properties": { "id": { "type": "string", "description": "A Unique identifier", "readOnly": true, "format": "uuid", "example": "019e0e40-2b1a-7215-85ec-f0aab4436a01" }, "tag_id": { "type": "string", "description": "ID of the tag this custom mapping belongs to", "readOnly": true, "format": "uuid", "example": "019e0e40-2b1a-7215-85ec-f0ab780116e4" }, "resource_id": { "type": "string", "description": "ID of the resource custom tag mapping belongs to, resource_type determines the type of resource", "readOnly": true, "format": "uuid", "example": "019e0e40-2b1a-7215-85ec-f0aca4524c95" }, "resource_type": { "type": "number", "description": "Resource type of custom tag, can be 1 for campaigns or 2 for accounts", "readOnly": true, "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Account", "2": "Campaign" }, "example": 1 }, "timestamp_created": { "type": "string", "description": "Timestamp when the custom tag mapping was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.906Z" }, "organization_id": { "type": "string", "description": "Organization ID that owns this custom tag mapping", "readOnly": true, "format": "uuid", "example": "019e0e40-2b1a-7215-85ec-f0ade4b26122" } }, "required": [ "id", "tag_id", "resource_id", "resource_type", "timestamp_created", "organization_id" ], "additionalProperties": false }, "def-15": { "title": "Block List Entry", "description": "A blocked email or domain", "x-tags": [ "Schemas", "BlockListEntry" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the block list entry", "readOnly": true, "format": "uuid", "example": "019e0e40-2a6a-797b-9b4c-e3364189e904" }, "timestamp_created": { "type": "string", "description": "Timestamp when the block list entry was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.730Z" }, "organization_id": { "type": "string", "description": "Organization ID that owns this block list entry", "readOnly": true, "format": "uuid", "example": "019e0e40-2a6a-797b-9b4c-e337ac81c954" }, "bl_value": { "type": "string", "description": "The email or domain to block", "example": "example.com" }, "is_domain": { "type": "boolean", "description": "Whether this entry blocks an entire domain", "readOnly": true, "example": true } }, "required": [ "id", "timestamp_created", "organization_id", "bl_value", "is_domain" ], "additionalProperties": false }, "def-16": { "title": "Lead Label", "description": "A custom label for categorizing and managing leads", "x-tags": [ "Schemas", "LeadLabel" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the custom lead label", "readOnly": true, "format": "uuid", "example": "019e0e40-2a7b-7680-9503-4d2494a4e5eb" }, "timestamp_created": { "type": "string", "description": "Timestamp when the custom lead label was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.747Z" }, "created_by": { "type": "string", "description": "User ID of the creator of this label", "readOnly": true, "format": "uuid", "example": "019e0e40-2a7b-7680-9503-4d25f8de4e5c" }, "organization_id": { "type": "string", "description": "Organization ID that owns this custom lead label", "readOnly": true, "format": "uuid", "example": "019e0e40-2a7b-7680-9503-4d26c4da1073" }, "label": { "type": "string", "description": "Display label for the custom lead label", "example": "Hot Lead" }, "interest_status_label": { "type": "string", "description": "Interest status label associated with this label", "enum": [ "positive", "negative", "neutral" ], "x-enumDescriptions": { "positive": "Positive", "negative": "Negative", "neutral": "Neutral" }, "example": "positive" }, "interest_status": { "type": "number", "description": "Interest status associated with this label. This is generated automatically by us.", "readOnly": true, "example": 1 }, "description": { "type": [ "null", "string" ], "description": "Detailed description of the custom lead label purpose", "example": "Used for marking high-priority leads" }, "use_with_ai": { "type": [ "null", "boolean" ], "description": "Whether this label should be used with AI features", "example": false } }, "required": [ "id", "timestamp_created", "created_by", "organization_id", "label", "interest_status_label", "interest_status" ], "additionalProperties": false }, "def-20": { "title": "Workspace", "description": "A workspace entity representing a workspace", "x-tags": [ "Schemas", "Workspace" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workspace", "readOnly": true, "format": "uuid", "example": "019e0e40-2a8b-7995-a5f1-2c6e34e69d37" }, "timestamp_created": { "type": "string", "description": "Timestamp when the workspace was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.763Z" }, "timestamp_updated": { "type": "string", "description": "Timestamp when the workspace was last updated", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.763Z" }, "owner": { "type": "string", "description": "User ID of the workspace owner", "readOnly": true, "format": "uuid", "example": "019e0e40-2a8b-7995-a5f1-2c6ffcd82072" }, "name": { "type": "string", "description": "Name of the workspace", "example": "My Workspace" }, "plan_id": { "type": [ "null", "string" ], "description": "Plan ID for workspace", "readOnly": true, "example": "pid_hg_v1" }, "add_unsub_to_block": { "type": [ "null", "boolean" ], "description": "Whether to add unsubscribes to block list", "example": false }, "default_opportunity_value": { "type": [ "null", "number" ], "description": "Default value for opportunities", "example": 250 }, "plan_id_leadfinder": { "type": [ "null", "string" ], "description": "Plan ID for leadfinder", "readOnly": true, "example": "pid_lf_ls_v1" }, "plan_id_verification": { "type": "object", "description": "Plan ID for verification service", "readOnly": true, "properties": { "quantity": { "type": "number", "example": 5 }, "product_id": { "type": "string", "example": "pid_verify_v1_monthly" }, "timestamp_updated": { "type": "string", "format": "date-time", "example": "2024-07-22T05:56:58.667Z" } } }, "org_logo_url": { "type": [ "null", "string" ], "description": "URL to workspace logo", "example": "https://example.com/logo.png" }, "org_client_domain": { "type": [ "null", "string" ], "description": "The domain for the white label agency mode", "readOnly": true, "example": "example.com" }, "plan_id_crm": { "type": [ "null", "string" ], "description": "Plan ID for CRM", "readOnly": true, "example": "pid_crm_v1" }, "plan_id_website_visitor": { "type": [ "null", "string" ], "description": "Plan ID for website visitor tracking", "readOnly": true, "example": "pid_wvw_v1" }, "plan_id_inbox_placement": { "type": [ "null", "string" ], "description": "Plan ID for inbox placement", "readOnly": true, "example": "pid_ip_v1" } }, "required": [ "id", "timestamp_created", "timestamp_updated", "owner", "name" ], "additionalProperties": false }, "def-23": { "title": "SuperSearch Enrichment", "description": "An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it.", "x-tags": [ "Schemas", "SuperSearchEnrichment" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrichment", "readOnly": true, "example": "01234567-89ab-cdef-0123-456789abcdef" }, "limit": { "type": [ "null", "number" ], "description": "The maximum number of leads to enrich", "example": 100 }, "organization_id": { "type": "string", "description": "Organization ID that created this enrichment", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "enrichment_payload": { "type": "object", "description": "Enrichment payload", "additionalProperties": true }, "auto_update": { "type": [ "null", "boolean" ], "description": "Whether new leads added to the resource will be automatically enriched using these same settings", "example": true }, "skip_rows_without_email": { "type": [ "null", "boolean" ], "description": "Whether the fully enriched profile enrichment will run even if we don't find an email", "example": true }, "in_progress": { "type": [ "null", "boolean" ], "description": "Whether the enrichment is in progress", "example": true }, "type": { "type": "string", "description": "Enrichment type to add to the resource", "enum": [ "work_email_enrichment", "fully_enriched_profile", "email_verification", "joblisting", "technologies", "news", "funding", "engagement_score", "ai_enrichment", "custom_flow" ], "x-enumDescriptions": { "work_email_enrichment": "Work Email Enrichment", "fully_enriched_profile": "LinkedIn Enrichment", "email_verification": "Email Verification", "joblisting": "Job Listing Enrichment", "technologies": "Technologies Enrichment", "news": "News Enrichment", "funding": "Funding Enrichment", "ai_enrichment": "AI Enrichment", "custom_flow": "Custom Flow Enrichment" }, "example": "email_verification" }, "resource_id": { "type": "string", "description": "Unique identifier for the entity to enrich leads into", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_type": { "type": "number", "description": "Type of the entity to enrich leads into", "readOnly": true, "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Campaign", "2": "List" }, "example": 1 } }, "required": [ "id", "organization_id", "resource_id", "resource_type" ], "additionalProperties": false }, "def-24": { "title": "Workspace Group Member", "description": "A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.", "x-tags": [ "Schemas", "WorkspaceGroupMember" ], "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the workspace group member", "readOnly": true, "format": "uuid", "example": "019e0e40-2aa2-7a3b-94cf-d09f1e3e68a9" }, "admin_workspace_id": { "type": "string", "description": "The id of the admin workspace", "readOnly": true, "format": "uuid", "example": "019e0e40-2aa2-7a3b-94cf-d0a0349bf111" }, "sub_workspace_id": { "type": "string", "description": "The id of the sub workspace", "format": "uuid", "example": "019e0e40-2aa2-7a3b-94cf-d0a1374c2304" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ], "x-enumDescriptions": { "pending": "The member has been invited to the workspace group but has not yet accepted the invitation.", "accepted": "The member has accepted the invitation to the workspace group.", "rejected": "The member has rejected the invitation to the workspace group." }, "example": "accepted" }, "timestamp_created": { "type": "string", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.786Z" }, "timestamp_updated": { "type": "string", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.786Z" }, "sub_workspace_name": { "type": [ "null", "string" ], "description": "The name of the sub workspace.", "readOnly": true, "example": "My Workspace" }, "admin_workspace_name": { "type": [ "null", "string" ], "description": "The name of the admin workspace.", "readOnly": true, "example": "My Workspace" } }, "required": [ "id", "admin_workspace_id", "sub_workspace_id", "status", "timestamp_created", "timestamp_updated" ], "additionalProperties": false }, "def-25": { "title": "Workspace Member", "description": "A member of a workspace with associated user details", "x-tags": [ "Schemas", "WorkspaceMember" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workspace member", "readOnly": true, "format": "uuid", "example": "019e0e40-2aaa-7e9f-9566-92747e2fe899" }, "email": { "type": "string", "description": "Email address of the workspace member", "format": "email", "example": "user@example.com" }, "user_id": { "type": "string", "description": "User ID of the workspace member", "readOnly": true, "format": "uuid", "example": "019e0e40-2aaa-7e9f-9566-92759d686b9e" }, "user_email": { "type": [ "null", "string" ], "description": "Email address of the user", "format": "email", "example": "user@example.com" }, "name": { "type": "object", "readOnly": true, "properties": { "first": { "type": "string", "description": "Workspace member first name", "example": "John" }, "last": { "type": "string", "description": "Workspace member last name", "example": "Smith" } } }, "role": { "type": "string", "description": "THe role of the workspace member defining their access level. While the \"owner\" role is listed in the enum, it cannot be created via the API, and is only assigned to the user who creates the workspace.", "enum": [ "owner", "admin", "editor", "view", "client" ], "x-enumDescriptions": { "owner": "Owner - Full access and workspace management", "admin": "Admin - Full access except workspace deletion", "editor": "Editor - Can edit but not manage workspace settings", "view": "View - Read-only access", "client": "This is a special role for users in the whitelabel (agency) view. It is not available in the API." }, "example": "editor" }, "timestamp_created": { "type": "string", "description": "Timestamp when the workspace member was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.794Z" }, "workspace_id": { "type": "string", "description": "ID of the workspace this member belongs to", "readOnly": true, "format": "uuid", "example": "019e0e40-2aaa-7e9f-9566-9276e2be75ab" }, "accepted": { "type": "boolean", "description": "Whether the member has accepted the workspace invitation", "readOnly": true, "example": false }, "issuer_id": { "type": [ "null", "string" ], "description": "ID of the user who added this member to the workspace", "readOnly": true, "format": "uuid", "example": "019e0e40-2aaa-7e9f-9566-92774d590d11" }, "permissions": { "type": [ "null", "array" ], "description": "The permissions for this workspace member. Used in the app to restrict access to certain sections", "items": { "type": "string", "enum": [ "dashboard.view", "campaigns.view", "campaigns.create", "campaigns.edit", "campaigns.delete", "organization.manage", "organization.integrations", "organization.billing", "organization.users.manage", "leadFinder.view", "customLeadLabels.create", "customLeadLabels.edit", "customLeadLabels.delete", "unibox.all", "analytics.view", "agency.manage", "accounts.view", "accounts.manage", "leadManagement.view", "leads.move", "crm.view", "websiteVisitors.view", "blocklist.manage", "preferences.manage", "inboxPlacement.view", "aiAgents.manage", "workspaceGroupMembers.invite", "workspaceGroupMembers.remove", "workspaceGroupMembers.leave" ], "examples": [ "unibox.all" ], "x-enumDescriptions": { "dashboard.view": "View the dashboard", "campaigns.view": "View campaigns", "campaigns.create": "Create campaigns", "campaigns.edit": "Edit campaigns", "campaigns.delete": "Delete campaigns", "organization.manage": "Manage organization", "organization.integrations": "Manage organization integrations", "organization.billing": "Manage organization billing", "organization.users.manage": "Manage organization users", "leadFinder.view": "View lead finder", "customLeadLabels.create": "Create custom lead labels", "customLeadLabels.edit": "Edit custom lead labels", "customLeadLabels.delete": "Delete custom lead labels", "unibox.all": "View all unibox", "analytics.view": "View analytics", "agency.manage": "Manage agency", "accounts.view": "View accounts", "accounts.manage": "Manage accounts", "leadManagement.view": "View lead management", "leads.move": "Move leads", "crm.view": "View CRM", "websiteVisitors.view": "View website visitors", "blocklist.manage": "Manage blocklist", "preferences.manage": "Manage preferences", "inboxPlacement.view": "Manage inbox placement", "aiAgents.manage": "Manage AI agents", "workspaceGroupMembers.invite": "Invite workspace group members", "workspaceGroupMembers.remove": "Remove workspace group members", "workspaceGroupMembers.leave": "Leave workspace group" } } } }, "required": [ "id", "email", "user_id", "role", "timestamp_created", "workspace_id", "accepted" ], "additionalProperties": false }, "def-26": { "title": "Campaign Subsequence", "description": "A subsequence entity representing a follow-up sequence", "x-tags": [ "Schemas", "CampaignSubsequence" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the subsequence", "readOnly": true, "format": "uuid", "example": "019e0e40-2ab6-7fd4-abd7-4e1468eb1ac7" }, "timestamp_created": { "type": "string", "description": "Timestamp when the subsequence was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.806Z" }, "parent_campaign": { "type": "string", "description": "ID of the parent campaign", "format": "uuid", "example": "019e0e40-2ab6-7fd4-abd7-4e15c5c50074" }, "workspace": { "type": "string", "description": "ID of the workspace this subsequence belongs to", "readOnly": true, "format": "uuid", "example": "019e0e40-2ab6-7fd4-abd7-4e16559cd41d" }, "status": { "type": "number", "description": "Status of the subsequence", "readOnly": true, "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft - The subsequence is in draft mode and not yet active", "1": "Active - The subsequence is currently running", "2": "Paused - The subsequence has been manually paused", "3": "Completed - The subsequence has finished running", "4": "Running Subsequences - The subsequence has active child sequences", "-99": "Account Suspended - The subsequence is suspended due to account issues", "-1": "Accounts Unhealthy - The subsequence is paused due to unhealthy sending accounts", "-2": "Bounce Protection - The subsequence is paused due to high bounce rates" }, "example": 0 }, "timestamp_leads_updated": { "type": "string", "description": "Timestamp when the leads were last updated", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.806Z" }, "name": { "type": "string", "description": "Name of the subsequence", "example": "Follow-up sequence" }, "conditions": { "type": "object", "description": "Conditions that trigger the subsequence", "properties": { "crm_status": { "type": "array", "description": "Lead CRM statuses that trigger the subsequence.", "items": { "type": "number", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 } }, "lead_activity": { "type": "array", "description": "Lead activities that trigger the subsequence.", "items": { "type": "number", "enum": [ 4, 91, 2 ], "x-enumDescriptions": { "2": "Email Opened - Triggered when a lead opens an email", "4": "Email Link Clicked - Triggered when a lead clicks a link in an email", "91": "Campaign Completed Without Reply - Triggered when a campaign completes for a lead without receiving a reply" }, "example": 4 } }, "reply_contains": { "type": "string", "example": "yes" } } }, "subsequence_schedule": { "type": "object", "description": "Schedule configuration for the subsequence", "properties": { "start_date": { "type": [ "null", "string" ], "format": "date", "description": "Start date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "end_date": { "type": [ "null", "string" ], "format": "date", "description": "End date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "My Schedule" }, "timing": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "09:00" }, "to": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "17:00" } }, "required": [ "from", "to" ] }, "days": { "type": "object", "minProperties": 1, "properties": { "0": { "type": "boolean", "example": true }, "1": { "type": "boolean", "example": true }, "2": { "type": "boolean", "example": true }, "3": { "type": "boolean", "example": true }, "4": { "type": "boolean", "example": true }, "5": { "type": "boolean", "example": false }, "6": { "type": "boolean", "example": false } } }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "example": "Etc/GMT+12" } }, "required": [ "name", "timing", "days", "timezone" ] }, "minItems": 1 } }, "required": [ "schedules" ] }, "sequences": { "type": "array", "description": "List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array", "items": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ], "x-enumDescriptions": { "email": "This steps represents an email" }, "description": "Type of step. This has to be 'email' always - it's the only supported type for now", "example": "email" }, "delay": { "type": "number", "description": "The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).", "example": 2 }, "delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.", "example": "days" }, "pre_delay": { "type": "number", "description": "The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).", "example": 2 }, "pre_delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.", "example": "days" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "example": "Hello {{firstName}}" }, "body": { "type": "string", "example": "Hey {{firstName}},\n\nI hope you are doing well." }, "v_disabled": { "type": "boolean", "description": "Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant", "example": true } }, "required": [ "subject", "body" ] } } }, "required": [ "type", "delay", "variants" ] } } }, "required": [ "steps" ] } }, "daily_limit_mode": { "type": "string", "description": "Daily limit mode for the subsequence. \"inherit\" uses the parent campaign limit, \"custom\" uses a subsequence-specific limit, \"unlimited\" bypasses the campaign-level daily limit.", "enum": [ "inherit", "custom", "unlimited" ], "example": "inherit" }, "daily_limit": { "type": [ "null", "number" ], "description": "Custom daily limit for the subsequence. Only used when `daily_limit_mode` is \"custom\".", "example": 50 }, "ignore_account_daily_limit": { "type": "boolean", "description": "When enabled, the subsequence will send even when sending accounts have reached their daily limit.", "example": false } }, "required": [ "id", "timestamp_created", "parent_campaign", "workspace", "status", "timestamp_leads_updated", "name", "conditions", "subsequence_schedule", "sequences" ], "additionalProperties": false }, "def-32": { "title": "Audit Log", "description": "Audit log records for tracking system activities", "x-tags": [ "Schemas", "AuditLog" ], "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "timestamp": { "type": "string", "description": "When the activity occurred", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.821Z" }, "organization_id": { "type": "string", "description": "Organization ID associated with the activity", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "activity_type": { "type": "number", "description": "Type of activity performed", "readOnly": true, "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ], "x-enumDescriptions": { "1": "User login", "2": "Lead deletion", "3": "Campaign deletion", "4": "Campaign launch", "5": "Campaign pause", "6": "Account addition", "7": "Account deletion", "8": "Lead moved", "9": "Lead added", "10": "Lead merged", "11": "Campaign update", "12": "Subsequence update", "18": "Webhook created", "19": "Webhook updated", "20": "Webhook marked as error", "21": "Webhook resumed", "22": "TOTP enrollment started", "23": "TOTP enabled", "24": "TOTP replacement started", "25": "TOTP replaced", "26": "TOTP disabled", "27": "MFA recovery codes generated", "28": "MFA recovery code used", "29": "MFA login challenge failed", "30": "MFA login challenge failed too many times", "31": "MFA login succeeded" }, "example": 1 }, "user_agent": { "type": [ "null", "string" ], "description": "User agent of the client that performed the activity", "readOnly": true, "example": "Mozilla/5.0..." }, "user_id": { "type": [ "null", "string" ], "description": "ID of the user who performed the activity", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "ip_address": { "type": "string", "description": "IP address from which the activity was performed", "readOnly": true, "example": "127.0.0.1" }, "from_api": { "type": "boolean", "description": "Whether the activity was performed via API", "readOnly": true, "example": false }, "affected_count": { "type": [ "null", "number" ], "description": "Number of items affected by the activity", "readOnly": true, "example": 1 }, "campaign_id": { "type": [ "null", "string" ], "description": "Associated campaign ID if applicable", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "webhook_id": { "type": [ "null", "string" ], "description": "Associated webhook ID if applicable", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "subsequence_id": { "type": [ "null", "string" ], "description": "Associated subsequence ID if applicable", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "list_id": { "type": [ "null", "string" ], "description": "Associated list ID if applicable", "readOnly": true, "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "audit_metadata": { "type": "object", "description": "Metadata about the audit log", "readOnly": true, "additionalProperties": true }, "user_name": { "type": [ "null", "string" ], "description": "Name of the user who performed the activity", "readOnly": true, "example": "John Doe" } }, "required": [ "id", "timestamp", "organization_id", "activity_type", "ip_address", "from_api" ], "additionalProperties": false }, "def-39": { "title": "Webhook", "description": "A webhook subscription for receiving event notifications", "x-tags": [ "Schemas", "Webhook" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook (UUID)", "readOnly": true, "format": "uuid", "example": "019e0e40-2aff-7253-a061-e6d37ccf9dd2" }, "organization": { "type": "string", "description": "Organization (workspace) UUID that owns this webhook", "readOnly": true, "format": "uuid", "example": "019e0e40-2b00-7e1f-9534-f6fd588ff31a" }, "campaign": { "type": [ "null", "string" ], "description": "Optional campaign UUID to filter events (null = all campaigns in workspace)", "format": "uuid", "example": "019e0e40-2b00-7e1f-9534-f6fea1b4c1b2" }, "name": { "type": [ "null", "string" ], "description": "Optional user-defined name for the webhook", "example": "Zapier Positive Replies" }, "target_hook_url": { "type": "string", "description": "Target URL to send webhook payloads", "format": "uri", "pattern": "^https?://", "example": "https://webhook.site/unique-url" }, "event_type": { "type": [ "null", "string" ], "description": "Type of event to trigger the webhook (null for custom label events). Set to \"all_events\" to subscribe to all events - including custom label events", "enum": [ "all_events", "email_sent", "email_opened", "email_link_clicked", "reply_received", "email_bounced", "lead_unsubscribed", "campaign_completed", "account_error", "lead_neutral", "lead_interested", "lead_not_interested", "lead_meeting_booked", "lead_meeting_completed", "lead_closed", "lead_out_of_office", "lead_wrong_person", "lead_no_show", "supersearch_enrichment_completed" ], "example": "email_sent" }, "custom_interest_value": { "type": [ "null", "number" ], "description": "Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)", "example": 1 }, "headers": { "type": [ "null", "object" ], "description": "Optional HTTP headers to include when delivering webhook payloads (key-value pairs)", "additionalProperties": { "type": "string", "examples": [ "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" ] }, "example": { "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" } }, "timestamp_created": { "type": "string", "description": "Timestamp when the webhook was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.880Z" }, "status": { "type": [ "null", "number" ], "description": "Webhook status: 1 = active, -1 = error (disabled due to delivery failures)", "readOnly": true, "example": 1 }, "timestamp_error": { "type": [ "null", "string" ], "description": "Timestamp when webhook was disabled due to delivery failures (null if active)", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.880Z" } }, "required": [ "id", "organization", "target_hook_url", "timestamp_created" ], "additionalProperties": false }, "def-41": { "title": "Webhook Event", "description": "A webhook event that was sent or attempted to be sent", "x-tags": [ "Schemas", "WebhookEvent" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook event (UUID)", "readOnly": true, "format": "uuid", "example": "019e0e40-2b09-717d-8b38-377df477dc29" }, "timestamp_created": { "type": "string", "description": "Timestamp when the webhook event was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.889Z" }, "timestamp_created_date": { "type": "string", "description": "Date when the webhook event was created (for partitioning)", "readOnly": true, "format": "date", "example": "2024-01-15" }, "organization_id": { "type": "string", "description": "Organization (workspace) UUID that owns this webhook event", "readOnly": true, "format": "uuid", "example": "019e0e40-2b09-717d-8b38-377e3c55c6c7" }, "payload": { "type": "object", "description": "JSON payload that was sent/attempted to be sent", "readOnly": true, "additionalProperties": true }, "success": { "type": "boolean", "description": "Whether the webhook call was successful", "readOnly": true, "example": true }, "retry_count": { "type": "number", "description": "Number of retry attempts made", "readOnly": true, "example": 0 }, "will_retry": { "type": "boolean", "description": "Whether the webhook will be retried", "readOnly": true, "example": false }, "webhook_url": { "type": "string", "description": "Target URL where the webhook was sent", "readOnly": true, "example": "https://webhook.site/unique-url" }, "status_code": { "type": [ "null", "number" ], "description": "HTTP status code received from the webhook endpoint (if any)", "readOnly": true, "example": 200 }, "error_message": { "type": [ "null", "string" ], "description": "Error message if the webhook failed", "readOnly": true, "example": "Connection timeout" }, "timestamp_next_retry": { "type": [ "null", "string" ], "description": "Timestamp for the next retry attempt (if applicable)", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.889Z" }, "retry_group_id": { "type": [ "null", "string" ], "description": "UUID for grouping retry attempts", "readOnly": true, "format": "uuid", "example": "019e0e40-2b09-717d-8b38-377f9cb05c02" }, "retry_successful": { "type": [ "null", "boolean" ], "description": "Whether the retry was successful (for retry events)", "readOnly": true, "example": true }, "lead_email": { "type": [ "null", "string" ], "description": "Email address of the lead associated with this webhook event", "readOnly": true, "example": "lead@example.com" }, "response_time_ms": { "type": [ "null", "number" ], "description": "Response time in milliseconds for the webhook call", "readOnly": true, "example": 150 } }, "required": [ "id", "timestamp_created", "timestamp_created_date", "organization_id", "success", "retry_count", "will_retry", "webhook_url" ], "additionalProperties": false }, "def-42": { "title": "DFY Email Account Order", "description": "A Done-For-You email account order", "x-tags": [ "Schemas", "DFYEmailAccountOrder" ], "type": "object", "properties": { "workspace_id": { "type": "string", "description": "ID of the workspace associated with the email account order", "readOnly": true, "example": "workspace_12345" }, "domain": { "type": "string", "description": "Domain of the email account", "readOnly": true, "example": "example.com" }, "forwarding_domain": { "type": [ "null", "string" ], "description": "Forwarding domain for the email account, if any", "example": "forward.example.com" }, "is_pre_warmed_up": { "type": [ "null", "boolean" ], "description": "Indicates if the account is pre-warmed up", "example": true }, "timestamp_cancelled": { "type": [ "null", "string" ], "description": "Timestamp when the order was cancelled, if applicable", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.893Z" }, "timestamp_created": { "type": "string", "description": "Timestamp when the order was created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.893Z" } }, "required": [ "workspace_id", "domain", "timestamp_created" ], "additionalProperties": false }, "def-43": { "title": "Custom Prompt Template", "description": "Custom prompt templates for creating custom prompts", "x-tags": [ "Schemas", "CustomPromptTemplate" ], "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "1" }, "workspace_id": { "type": "string", "readOnly": true, "format": "uuid", "example": "019e0e40-2b28-7914-9d40-75e8512a5099" }, "created_by": { "type": "string", "readOnly": true, "format": "uuid", "example": "019e0e40-2b28-7914-9d40-75e925bba79d" }, "name": { "type": "string", "example": "Prompt template name" }, "description": { "type": [ "null", "string" ], "example": "Prompt template description" }, "category": { "type": "number", "description": "Prompt Custom template category", "enum": [ 1, 2, 3, 4, 5, 6 ], "x-enumDescriptions": { "1": "Copywriting", "2": "Cleaning", "3": "Sales", "4": "Marketing", "5": "Other", "6": "Personalization" }, "example": 1 }, "properties": { "type": [ "null", "array" ], "items": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Property name" ] }, "property": { "type": "string", "examples": [ "{{property1}}" ] } } } }, "prompt": { "type": "string", "example": "Generate a name using {{property_1}} and {{property_2}} combination." }, "is_public": { "type": "boolean", "example": true }, "model_version": { "type": "string", "enum": [ "3.5", "gpt-5", "gpt-5.4", "gpt-5-mini", "gpt-5-nano", "4.0", "4.0-Omni", "gpt-4o", "o3", "gpt-4.1", "gpt-4.1-mini", "claude-3.7-sonnet", "claude-3.5-sonnet", "claude-4.5-sonnet", "r1", "grok-4", "gemini-2.0-flash", "gemini-3.0-flash", "gemini-3.0-pro", "instantly-ai-lightspeed-agent", "sonar", "sonar-pro" ], "x-enumDescriptions": { "3.5": "GPT-3.5", "gpt-5": "GPT-5", "gpt-5.4": "GPT-5.4", "gpt-5-mini": "GPT-5 Mini", "gpt-5-nano": "GPT-5 Nano", "4.0": "GPT-4.0", "4.0-Omni": "GPT-4.0 Omni", "gpt-4o": "GPT-4O", "o3": "O3", "gpt-4.1": "GPT-4.1", "gpt-4.1-mini": "GPT-4.1 Mini", "claude-3.7-sonnet": "Claude 3.7 Sonnet", "claude-3.5-sonnet": "Claude 3.5 Sonnet", "claude-4.5-sonnet": "Claude 4.5 Sonnet", "r1": "R1", "grok-4": "Grok 4", "gemini-2.0-flash": "Gemini 2.0 Flash", "gemini-3.0-flash": "Gemini 3.0 Flash", "gemini-3.0-pro": "Gemini 3.0 Pro", "sonar": "Sonar", "sonar-pro": "Sonar Pro", "instantly-ai-lightspeed-agent": "Instantly AI Lightspeed Agent" }, "example": "3.5" }, "from_shared": { "type": [ "null", "boolean" ], "example": false }, "like_count": { "type": [ "null", "number" ], "readOnly": true, "example": 50 }, "execution_count": { "type": [ "null", "number" ], "readOnly": true, "example": 20 }, "liked": { "type": [ "null", "boolean" ], "readOnly": true, "example": true }, "template_type": { "type": [ "null", "string" ], "description": "Custom Prompt template type", "enum": [ "custom", "public" ], "x-enumDescriptions": { "custom": "custom", "public": "public" }, "example": "public" }, "created_by_instantly": { "type": [ "null", "boolean" ], "readOnly": true, "example": true }, "creator": { "type": [ "null", "object" ], "readOnly": true, "properties": { "id": { "type": "string", "examples": [ "019e0e40-2b28-7914-9d40-75eacf20bffc" ] }, "payload": { "type": "object", "properties": { "name": { "type": "object", "properties": { "first": { "type": "string", "examples": [ "John" ] }, "last": { "type": "string", "examples": [ "Smith" ] } } } } } } } }, "required": [ "id", "workspace_id", "created_by", "name", "category", "prompt", "is_public" ], "additionalProperties": false }, "def-44": { "title": "Sales Flow", "description": "Manages how sales users view and interact with campaign and lead lists within the sales flow.", "x-tags": [ "Schemas", "SalesFlow" ], "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "format": "uuid", "example": "019e0e40-2b15-7d92-8b95-d535e040fb98" }, "timestamp_created": { "type": "string", "description": "Date and time when sales flow created", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.901Z" }, "organization_id": { "type": "string", "description": "Organization ID associated with the sales flow", "readOnly": true, "format": "uuid", "example": "019e0e40-2b15-7d92-8b95-d5369ab0ab84" }, "name": { "type": "string", "description": "Name of the sales flow", "example": "Smart view name" }, "is_default": { "type": [ "null", "boolean" ], "description": "Indicates whether this sales flow is set as the default one for the user or workspace.", "example": true }, "queries": { "type": "array", "description": "An object containing the sales flow queries", "items": { "type": "object", "required": [ "actionType", "values" ], "description": "Smart view query to filter leads", "properties": { "actionType": { "type": "string", "enum": [ "reply", "email-open", "last-contacted", "link-click", "lead-status", "lead-status-change" ], "example": "email-open" }, "values": { "type": "object", "properties": { "occurrence-days": { "type": "number", "example": 1 }, "occurrence-count": { "type": "object", "properties": { "condition": { "type": "string", "enum": [ "more", "less", "equal" ], "example": "more" }, "count": { "type": "number", "example": 1 } } }, "lead-status": { "type": "object", "properties": { "status": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "is", "is-not" ], "example": "is" } } } } } }, "example": { "actionType": "email-open", "values": { "occurrence-days": 1 } } } }, "created_by": { "type": "string", "description": "UUID of the user who created the sales flow.", "readOnly": true, "format": "uuid", "example": "019e0e40-2b15-7d92-8b95-d53780481fa1" }, "list_id": { "type": [ "null", "string" ], "description": "The ID of the list, can be \"all-lists\" in case of all.", "example": "019e0e40-2b15-7d92-8b95-d538f44f0f3c" }, "campaign_id": { "type": [ "null", "string" ], "description": "The ID of the campaign. Set to null when \"all-campaigns\" is passed.", "example": "019e0e40-2b15-7d92-8b95-d5399bf822bc" }, "list_name": { "type": [ "null", "string" ], "description": "The name of the list. ", "readOnly": true, "example": "List name" }, "campaign_name": { "type": [ "null", "string" ], "description": "The name of the campaign.", "readOnly": true, "example": "Campaign #1" } }, "required": [ "id", "timestamp_created", "organization_id", "name", "queries", "created_by" ], "additionalProperties": false }, "def-45": { "title": "Email Template", "description": "A campaign email template", "x-tags": [ "Schemas", "EmailTemplate" ], "type": "object", "properties": { "id": { "type": "string", "description": "A Unique identifier", "readOnly": true, "format": "uuid", "example": "019e0e40-2b31-7e89-8387-dc6144a53bbc" }, "timestamp_created": { "type": "string", "description": "Timestamp when the email template was added to our database.", "readOnly": true, "format": "date-time", "example": "2026-05-09T19:39:06.929Z" }, "body": { "type": "string", "description": "An body of the email template on html or text format", "example": "

This is a test email

" }, "name": { "type": "string", "description": "An email template name", "example": "Test Email Template" }, "subject": { "type": [ "null", "string" ], "description": "An email template subject", "example": "Test Email template Subject" }, "organization": { "type": "string", "description": "The workspace ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2b31-7e89-8387-dc621d4d5b53" } }, "required": [ "id", "timestamp_created", "body", "name", "organization" ], "additionalProperties": false }, "def-48": { "title": "Workspace Billing", "description": "Workspace Billing", "x-tags": [ "Schemas", "WorkspaceBilling" ], "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "def-49": { "title": "CRM Actions", "description": "CRM related actions", "x-tags": [ "Schemas", "CRMActions" ], "type": "object", "properties": {}, "required": [], "additionalProperties": false } } }, "paths": { "/api/v2/account-campaign-mappings/{email}": { "get": { "operationId": "getAccountCampaignMapping", "summary": "Get campaigns associated with an email", "tags": [ "AccountCampaignMapping" ], "description": "Requires one of the following scopes: `account_campaign_mappings:read`, `account_campaign_mappings:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "number", "example": 10 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "example": "2025-03-07T00:00:00.000Z" }, "in": "query", "name": "starting_after", "required": false }, { "schema": { "type": "string", "example": "user@example.com" }, "in": "path", "name": "email", "required": true, "description": "Email" } ], "responses": { "200": { "description": "The list of Account Campaign Mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Account Campaign Mapping", "items": { "$ref": "#/components/schemas/def-10" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-610f-715f-9ea4-0f8594c7eeee" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts": { "post": { "operationId": "createAccount", "summary": "Create account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:create`, `accounts:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateAccount", "description": "The Account to create", "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the account", "format": "email", "example": "user@example.com" }, "first_name": { "type": "string", "description": "First name associated with the account", "example": "John" }, "last_name": { "type": "string", "description": "Last name associated with the account", "example": "Doe" }, "warmup": { "type": "object", "description": "Warmup configuration for the account", "properties": { "limit": { "type": "number", "description": "Email sending limit for the account", "example": 100 }, "advanced": { "type": "object", "description": "Advanced settings for the account", "properties": { "warm_ctd": { "type": "boolean", "description": "Whether the account is in warm CTD mode", "example": false }, "open_rate": { "type": "number", "description": "Email open rate for the account", "example": 0.95 }, "important_rate": { "type": "number", "description": "Important email rate for the account", "example": 0.8 }, "read_emulation": { "type": "boolean", "description": "Whether read emulation is enabled", "example": true }, "spam_save_rate": { "type": "number", "description": "Spam save rate for the account", "example": 0.02 }, "weekday_only": { "type": "boolean", "description": "Whether to send emails only on weekdays", "example": true } } }, "warmup_custom_ftag": { "type": "string", "description": "Custom tag for the account", "example": "warmup" }, "increment": { "type": "string", "enum": [ "disabled", "0", "1", "2", "3", "4" ], "x-enumDescriptions": { "0": "0", "1": "1", "2": "2", "3": "3", "4": "4", "disabled": "Disabled" }, "description": "Daily increment added to the sending limit, starting from 0, until the full daily limit is reached (slow ramp). Gradually increases sending volume to improve deliverability. Set to `disabled` to send at the full daily limit from day one.", "example": "disabled" }, "reply_rate": { "type": "number", "description": "Reply rate for the account", "example": 0.1 } } }, "daily_limit": { "type": [ "number", "null" ], "description": "Daily email sending limit", "example": 100 }, "tracking_domain_name": { "type": [ "string", "null" ], "description": "Tracking domain", "example": "example.com" }, "tracking_domain_status": { "type": [ "string", "null" ], "description": "Tracking domain status", "example": "active" }, "enable_slow_ramp": { "type": [ "boolean", "null" ], "description": "Whether to enable slow ramp up for sending limits", "example": false }, "inbox_placement_test_limit": { "type": [ "number", "null" ], "description": "The limit for inbox placement tests", "minimum": 0, "example": 10 }, "provider_code": { "type": "number", "description": "Provider code for the account. Please make sure to specify the right provider code, otherwise your account will not work.", "enum": [ 1, 2, 3, 4, 8 ], "x-enumDescriptions": { "1": "Custom IMAP/SMTP", "2": "Google", "3": "Microsoft", "4": "AWS", "8": "AirMail" }, "example": 2 }, "sending_gap": { "type": "number", "description": "The gap between emails sent from this account in minutes (minimum wait time when used with multiple campaigns)", "minimum": 0, "maximum": 1440, "example": 10 }, "signature": { "type": [ "string", "null" ], "description": "Email signature for the account", "example": "Best regards, John Doe" }, "imap_username": { "type": "string", "example": "username" }, "imap_password": { "type": "string", "example": "password" }, "imap_host": { "type": "string", "example": "imap.gmail.com" }, "imap_port": { "type": "number", "example": 993 }, "smtp_username": { "type": "string", "example": "username" }, "smtp_password": { "type": "string", "example": "password" }, "smtp_host": { "type": "string", "example": "smtp.gmail.com" }, "smtp_port": { "type": "number", "example": 587 }, "reply_to": { "type": "string", "example": "reply@example.com" }, "warmup_custom_ftag": { "type": "string", "example": "warmup" }, "skip_cname_check": { "type": "boolean", "example": false } }, "required": [ "email", "first_name", "last_name", "provider_code", "imap_username", "imap_password", "imap_host", "imap_port", "smtp_username", "smtp_password", "smtp_host", "smtp_port" ], "additionalProperties": false } } }, "required": true, "description": "The Account to create" }, "responses": { "200": { "description": "The Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listAccount", "summary": "List account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "2026-01-01T00:00:00.000Z&jon@doe.com" }, "in": "query", "name": "starting_after", "required": false, "description": "Pagination cursor from `next_starting_after`, in `timestamp_created&email` format. Legacy ISO date-time cursor is still supported." }, { "schema": { "type": "string", "example": "gmail.com" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "number", "enum": [ 1, 2, 3, -1, -2, -3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Temporarily paused for maintenance; will be automatically resumed shortly", "-1": "Connection Error", "-2": "Soft Bounce Error", "-3": "Sending Error" }, "example": 1 }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "number", "enum": [ 1, 2, 3, 4, 8 ], "x-enumDescriptions": { "1": "Custom IMAP/SMTP", "2": "Google", "3": "Microsoft", "4": "AWS", "8": "AirMail" }, "example": 2 }, "in": "query", "name": "provider_code", "required": false }, { "schema": { "type": "string", "example": "019e0e40-6118-7e5b-bf94-ad4418dc1550, 019e0e40-6118-7e5b-bf94-ad458c289e05" }, "in": "query", "name": "tag_ids", "required": false, "description": "Filter accounts by tag ids. Returns accounts that have any of the specified tags assigned. You can specify multiple tag ids by separating them with a comma." }, { "schema": { "type": "string", "example": "019e0e40-6118-7e5b-bf94-ad46a6a3f335, 019e0e40-6118-7e5b-bf94-ad47f974852a" }, "in": "query", "name": "tag_ids_all", "required": false, "description": "Filter accounts by tag ids with AND logic. Returns only accounts that have all of the specified tags assigned. You can specify multiple tag ids by separating them with a comma." } ], "responses": { "200": { "description": "The list of Account", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Account", "items": { "$ref": "#/components/schemas/def-0" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6118-7e5b-bf94-ad48e3742a10" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/{email}": { "get": { "operationId": "getAccount", "summary": "Get account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "jon@doe.com" }, "in": "path", "name": "email", "required": true, "description": "The email of the account to get" } ], "responses": { "200": { "description": "The requested Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchAccount", "summary": "Patch account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name associated with the account", "example": "John" }, "last_name": { "type": "string", "description": "Last name associated with the account", "example": "Doe" }, "warmup": { "type": "object", "description": "Warmup configuration for the account", "properties": { "limit": { "type": "number", "description": "Email sending limit for the account", "example": 100 }, "advanced": { "type": "object", "description": "Advanced settings for the account", "properties": { "warm_ctd": { "type": "boolean", "description": "Whether the account is in warm CTD mode", "example": false }, "open_rate": { "type": "number", "description": "Email open rate for the account", "example": 0.95 }, "important_rate": { "type": "number", "description": "Important email rate for the account", "example": 0.8 }, "read_emulation": { "type": "boolean", "description": "Whether read emulation is enabled", "example": true }, "spam_save_rate": { "type": "number", "description": "Spam save rate for the account", "example": 0.02 }, "weekday_only": { "type": "boolean", "description": "Whether to send emails only on weekdays", "example": true } } }, "warmup_custom_ftag": { "type": "string", "description": "Custom tag for the account", "example": "warmup" }, "increment": { "type": "string", "enum": [ "disabled", "0", "1", "2", "3", "4" ], "x-enumDescriptions": { "0": "0", "1": "1", "2": "2", "3": "3", "4": "4", "disabled": "Disabled" }, "description": "Daily increment added to the sending limit, starting from 0, until the full daily limit is reached (slow ramp). Gradually increases sending volume to improve deliverability. Set to `disabled` to send at the full daily limit from day one.", "example": "disabled" }, "reply_rate": { "type": "number", "description": "Reply rate for the account", "example": 0.1 } } }, "daily_limit": { "type": [ "number", "null" ], "description": "Daily email sending limit", "example": 100 }, "tracking_domain_name": { "type": [ "string", "null" ], "description": "Tracking domain", "example": "example.com" }, "tracking_domain_status": { "type": [ "string", "null" ], "description": "Tracking domain status", "example": "active" }, "enable_slow_ramp": { "type": [ "boolean", "null" ], "description": "Whether to enable slow ramp up for sending limits", "example": false }, "inbox_placement_test_limit": { "type": [ "number", "null" ], "description": "The limit for inbox placement tests", "minimum": 0, "example": 10 }, "sending_gap": { "type": "number", "description": "The gap between emails sent from this account in minutes (minimum wait time when used with multiple campaigns)", "minimum": 0, "maximum": 1440, "example": 10 }, "signature": { "type": [ "string", "null" ], "description": "Email signature for the account", "example": "Best regards, John Doe" }, "skip_cname_check": { "type": "boolean", "example": false }, "remove_tracking_domain": { "type": "boolean", "example": false } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "example": "jon@doe.com" }, "in": "path", "name": "email", "required": true, "description": "The email of the account to update" } ], "responses": { "200": { "description": "The updated Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteAccount", "summary": "Delete account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:delete`, `accounts:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "example": "jon@doe.com" }, "in": "path", "name": "email", "required": true, "description": "The email of the account to get" } ], "responses": { "200": { "description": "The deleted Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/warmup/enable": { "post": { "operationId": "enableWarmupForAccounts", "summary": "Enable warmup for accounts", "tags": [ "Account" ], "description": "Initiates a background job to enable warmup for the specified accounts. The response will contain the initial background job object. You can monitor the job's progress by polling the `GET: /api/v2/background-jobs/:id` endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "example": "user@example.com" }, "maxItems": 100, "description": "List of emails to enable warmup accounts for. The emails should be attached to accounts in your workspace." }, "include_all_emails": { "type": "boolean", "description": "If true, it will enable warmup to all accounts", "example": true }, "excluded_emails": { "type": "array", "items": { "type": "string", "example": "user@example.com" }, "maxItems": 100, "description": "List of emails to exclude when `include_all_emails` is `true`." }, "filter": { "type": [ "object", "null" ], "description": "Optional filter to apply when `include_all_emails` is `true`. Can contain tag_id or other filter criteria.", "properties": { "tag_id": { "type": "string", "description": "The ID of the tag to filter accounts by.", "example": "019e0e40-611a-79f2-9655-3e08bc7bd794" }, "filter": { "type": [ "string", "null" ], "description": "The filter to apply to the accounts.", "enum": [ "ACC_FILTER_PAUSED", "ACC_FILTER_ERROR", "ACC_FILTER_NO_CTD", "ACC_FILTER_PW_ACCOUNTS", "ACC_FILTER_DFY", "ACC_FILTER_DFY_SETUP_PENDING", "ACC_FILTER_W_ACTIVE", "ACC_FILTER_W_PAUSED", "ACC_FILTER_W_ERROR", null ], "x-enumDescriptions": { "ACC_FILTER_PAUSED": "Paused", "ACC_FILTER_ERROR": "Has errors", "ACC_FILTER_NO_CTD": "No custom tracking domain", "ACC_FILTER_PW_ACCOUNTS": "Pre-warmed accounts", "ACC_FILTER_DFY": "DFY accounts", "ACC_FILTER_DFY_SETUP_PENDING": "DFY Setup Pending", "ACC_FILTER_W_ACTIVE": "Warmup active", "ACC_FILTER_W_PAUSED": "Warmup paused", "ACC_FILTER_W_ERROR": "Warmup has errors", "null": "No filter" }, "example": "ACC_FILTER_PAUSED" } } }, "search": { "type": "string", "description": "Optional search query to filter accounts when `include_all_emails` is `true`.", "example": "gmail.com" } } } } } }, "responses": { "200": { "description": "The requested Background Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-12" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/warmup/disable": { "post": { "operationId": "disableWarmupForAccounts", "summary": "Disable warmup for accounts", "tags": [ "Account" ], "description": "Initiates a background job to disable warmup for the specified accounts. The response will contain the initial background job object. You can monitor the job's progress by polling the `GET: /api/v2/background-jobs/:id` endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "example": "user@example.com" }, "maxItems": 100, "description": "List of emails to disable warmup accounts for. The emails should be attached to accounts in your workspace." }, "include_all_emails": { "type": "boolean", "description": "If true, it will disable warmup to all accounts", "example": true }, "excluded_emails": { "type": "array", "items": { "type": "string", "example": "user@example.com" }, "maxItems": 100, "description": "List of emails to exclude when `include_all_emails` is `true`." }, "filter": { "type": [ "object", "null" ], "description": "Optional filter to apply when `include_all_emails` is `true`. Can contain tag_id or other filter criteria.", "additionalProperties": true, "properties": { "tag_id": { "type": "string", "description": "The ID of the tag to filter accounts by.", "example": "019e0e40-611a-79f2-9655-3e0a752f57ce" }, "filter": { "type": [ "string", "null" ], "description": "The filter to apply to the accounts.", "enum": [ "ACC_FILTER_PAUSED", "ACC_FILTER_ERROR", "ACC_FILTER_NO_CTD", "ACC_FILTER_PW_ACCOUNTS", "ACC_FILTER_DFY", "ACC_FILTER_DFY_SETUP_PENDING", "ACC_FILTER_W_ACTIVE", "ACC_FILTER_W_PAUSED", "ACC_FILTER_W_ERROR", null ], "x-enumDescriptions": { "ACC_FILTER_PAUSED": "Paused", "ACC_FILTER_ERROR": "Has errors", "ACC_FILTER_NO_CTD": "No custom tracking domain", "ACC_FILTER_PW_ACCOUNTS": "Pre-warmed accounts", "ACC_FILTER_DFY": "DFY accounts", "ACC_FILTER_DFY_SETUP_PENDING": "DFY Setup Pending", "ACC_FILTER_W_ACTIVE": "Warmup active", "ACC_FILTER_W_PAUSED": "Warmup paused", "ACC_FILTER_W_ERROR": "Warmup has errors", "null": "No filter" }, "example": "ACC_FILTER_PAUSED" } } }, "search": { "type": "string", "description": "Optional search query to filter accounts when `include_all_emails` is `true`.", "example": "gmail.com" } } } } } }, "responses": { "200": { "description": "The requested Background Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-12" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/warmup-analytics": { "post": { "operationId": "getWarmupAnalytics", "summary": "Get warmup analytics", "tags": [ "Account", "Analytics" ], "description": "Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "example": "user@example.com" }, "maxItems": 100, "minItems": 1, "description": "List of emails to get warmup analytics for. The emails should be attached to accounts in your workspace." } }, "required": [ "emails" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "email_date_data": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sent": { "type": "number", "example": 100 }, "landed_inbox": { "type": "number", "example": 50 }, "landed_spam": { "type": "number", "example": 10 }, "received": { "type": "number", "example": 100 } } } } }, "aggregate_data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "sent": { "type": "number", "example": 100 }, "received": { "type": "number", "example": 100 }, "landed_inbox": { "type": "number", "example": 50 }, "landed_spam": { "type": "number", "example": 10 }, "health_score_label": { "type": "string", "example": "Good" }, "health_score": { "type": "number", "example": 90 } } } } }, "example": { "email_date_data": { "example1@example.com": { "2023-10-01": { "sent": 10, "landed_inbox": 8, "landed_spam": 2, "received": 10 }, "2023-10-02": { "sent": 5, "landed_inbox": 5, "received": 5 } }, "example2@example.com": { "2023-10-01": { "sent": 7, "landed_inbox": 7, "received": 7 } } }, "aggregate_data": { "example1@example.com": { "sent": 15, "landed_inbox": 13, "landed_spam": 2, "received": 15, "health_score_label": "87%", "health_score": 87 }, "example2@example.com": { "sent": 7, "landed_inbox": 7, "health_score_label": "100%", "health_score": 100 } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/analytics/daily": { "get": { "operationId": "getDailyAccountAnalytics", "summary": "Get daily account analytics", "tags": [ "Account", "Analytics" ], "description": "Get daily account analytics showing the number of emails sent per day for each email account. Useful for tracking daily sending activity across your accounts.", "parameters": [ { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date for the analytics period (optional). If not provided, returns data for the last 30 days." }, { "schema": { "type": "string", "example": "2024-01-31" }, "in": "query", "name": "end_date", "required": false, "description": "End date for the analytics period (optional). If not provided, defaults to current date." }, { "schema": { "type": "array", "items": { "type": "string", "example": "user@example.com" } }, "in": "query", "name": "emails", "required": false, "description": "Filter by specific email accounts (optional). If not provided, returns data for all accounts in your workspace." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date of the analytics entry, in YYYY-MM-DD format", "example": "2024-01-15" }, "email_account": { "type": "string", "description": "The email account that sent the emails", "example": "user@example.com" }, "sent": { "type": "integer", "description": "The total number of campaign emails sent on this date by this account, including emails for subsequences", "example": 150 }, "bounced": { "type": "integer", "description": "The number of emails that bounced on this date for this account for campaigns - including subsequences", "example": 3 }, "contacted": { "type": "integer", "description": "The total number of unique contacts who received an email on this date from this account", "example": 120 }, "new_leads_contacted": { "type": "integer", "description": "The total number of new leads contacted on this date from this account", "example": 50 }, "opened": { "type": "integer", "description": "The total number of opened emails on this date for this account", "example": 99 }, "unique_opened": { "type": "integer", "description": "The total number of unique opened emails on this date for this account", "example": 60 }, "replies": { "type": "integer", "description": "The total number of replies received on this date for this account", "example": 8 }, "unique_replies": { "type": "integer", "description": "The total number of unique replies received on this date for this account", "example": 7 }, "replies_automatic": { "type": "integer", "description": "The total number of automatic replies detected on this date for this account", "example": 2 }, "unique_replies_automatic": { "type": "integer", "description": "The total number of unique automatic replies detected on this date for this account", "example": 1 }, "clicks": { "type": "integer", "description": "The total number of links clicked on this date for this account", "example": 30 }, "unique_clicks": { "type": "integer", "description": "The total number of unique links clicked on this date for this account. Unique meaning from unique leads, not unique links", "example": 20 } }, "required": [ "date", "email_account", "sent", "bounced", "contacted", "new_leads_contacted", "opened", "unique_opened", "replies", "unique_replies", "replies_automatic", "unique_replies_automatic", "clicks", "unique_clicks" ] } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Start Date must be earlier than End Date" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/{email}/pause": { "post": { "operationId": "pauseAccount", "summary": "Pause an account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "user@example.com" }, "in": "path", "name": "email", "required": true, "description": "The email of the account to pause" } ], "responses": { "200": { "description": "The requested Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/{email}/resume": { "post": { "operationId": "resumeAccount", "summary": "Resume a paused account", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "user@example.com" }, "in": "path", "name": "email", "required": true, "description": "Account email" } ], "responses": { "200": { "description": "The requested Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/{email}/mark-fixed": { "post": { "operationId": "markAccountFixed", "summary": "Mark an account as fixed", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "user@example.com" }, "in": "path", "name": "email", "required": true, "description": "Account email" } ], "responses": { "200": { "description": "The requested Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-0" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/ctd/status": { "get": { "operationId": "getCtdStatus", "summary": "Get custom tracking domain status", "tags": [ "Account" ], "description": "Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "example.com" }, "in": "query", "name": "host", "required": true, "description": "Custom tracking domain host" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ssl": { "type": "boolean", "example": true }, "cname": { "type": "boolean", "example": true }, "host": { "type": "string", "example": "example.com" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Error message" }, "host": { "type": "string", "example": "example.com" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/test/vitals": { "post": { "operationId": "testAccountVitals", "summary": "Test account vitals", "tags": [ "Account", "Analytics" ], "description": "Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "string", "example": "user@example.com" } } }, "required": [] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "success_list": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "allPass": { "type": "boolean", "example": true }, "mx": { "type": "boolean", "example": true }, "spf": { "type": "boolean", "example": true }, "dkim": { "type": "boolean", "example": true }, "dmarc": { "type": "boolean", "example": true } } } }, "failure_list": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "allPass": { "type": "boolean", "example": false }, "mx": { "type": "boolean", "example": false }, "spf": { "type": "boolean", "example": false }, "dkim": { "type": "boolean", "example": false }, "dmarc": { "type": "boolean", "example": false } } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad request - no emails sent" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/accounts/move": { "post": { "operationId": "moveAccounts", "summary": "Move accounts between workspaces", "tags": [ "Account" ], "description": "Move accounts between workspaces. IMPORTANT: this endpoint should be called ONLY with an ADMIN workspace API key (check the workspace group docs: https://developer.instantly.ai/workspace-group), and both the source and destination workspaces must have the same admin workspace.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "description": "Array of email addresses of the accounts to move", "items": { "type": "string", "description": "Email address of the account to move", "example": "user@example.com" }, "minItems": 1 }, "source_workspace_id": { "type": "string", "description": "ID of the source workspace (the workspace that the accounts are currently in)", "example": "019e0e40-6121-77b8-a051-cf10cf3bc137" }, "destination_workspace_id": { "type": "string", "description": "ID of the destination workspace (the workspace that the accounts will be moved to)", "example": "019e0e40-6121-77b8-a051-cf11e094d893" } }, "required": [ "emails", "source_workspace_id", "destination_workspace_id" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ], "x-enumDescriptions": { "success": "The accounts were moved successfully " }, "example": "success" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/api-keys": { "post": { "operationId": "createAPIKey", "summary": "Create api key", "tags": [ "APIKey" ], "description": "Requires one of the following scopes: `api_keys:create`, `api_keys:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateAPI Key", "description": "The API Key to create", "type": "object", "properties": { "name": { "type": "string", "example": "My API Key" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "all:all", "all:create", "all:read", "all:update", "all:delete", "ai_agents:all", "ai_agents:create", "ai_agents:read", "ai_agents:update", "ai_agents:delete", "api_keys:all", "api_keys:create", "api_keys:read", "api_keys:update", "api_keys:delete", "audit_logs:all", "audit_logs:create", "audit_logs:read", "audit_logs:update", "audit_logs:delete", "custom_prompt_templates:all", "custom_prompt_templates:create", "custom_prompt_templates:read", "custom_prompt_templates:update", "custom_prompt_templates:delete", "account_campaign_mappings:all", "account_campaign_mappings:create", "account_campaign_mappings:read", "account_campaign_mappings:update", "account_campaign_mappings:delete", "campaigns:all", "campaigns:create", "campaigns:read", "campaigns:update", "campaigns:delete", "inbox_placement_tests:all", "inbox_placement_tests:create", "inbox_placement_tests:read", "inbox_placement_tests:update", "inbox_placement_tests:delete", "inbox_placement_analytics:all", "inbox_placement_analytics:create", "inbox_placement_analytics:read", "inbox_placement_analytics:update", "inbox_placement_analytics:delete", "inbox_placement_reports:all", "inbox_placement_reports:create", "inbox_placement_reports:read", "inbox_placement_reports:update", "inbox_placement_reports:delete", "lead_lists:all", "lead_lists:create", "lead_lists:read", "lead_lists:update", "lead_lists:delete", "leads:all", "leads:create", "leads:read", "leads:update", "leads:delete", "background-jobs:all", "background-jobs:create", "background-jobs:read", "background-jobs:update", "background-jobs:delete", "custom_tags:all", "custom_tags:create", "custom_tags:read", "custom_tags:update", "custom_tags:delete", "custom_tag_mappings:all", "custom_tag_mappings:create", "custom_tag_mappings:read", "custom_tag_mappings:update", "custom_tag_mappings:delete", "crm_actions:all", "crm_actions:create", "crm_actions:read", "crm_actions:update", "crm_actions:delete", "accounts:all", "accounts:create", "accounts:read", "accounts:update", "accounts:delete", "block_list_entries:all", "block_list_entries:create", "block_list_entries:read", "block_list_entries:update", "block_list_entries:delete", "lead-labels:all", "lead-labels:create", "lead-labels:read", "lead-labels:update", "lead-labels:delete", "email_verifications:all", "email_verifications:create", "email_verifications:read", "emails:all", "emails:create", "emails:read", "emails:update", "emails:delete", "email_templates:all", "email_templates:create", "email_templates:read", "email_templates:update", "email_templates:delete", "workspaces:all", "workspaces:create", "workspaces:read", "workspaces:update", "workspaces:delete", "workspace_billing:all", "workspace_billing:create", "workspace_billing:read", "workspace_billing:update", "workspace_billing:delete", "workspace_group_members:all", "workspace_group_members:create", "workspace_group_members:read", "workspace_group_members:update", "workspace_group_members:delete", "workspace_members:all", "workspace_members:create", "workspace_members:read", "workspace_members:update", "workspace_members:delete", "subsequences:all", "subsequences:create", "subsequences:read", "subsequences:update", "subsequences:delete", "ai_sdr:all", "ai_sdr:create", "ai_sdr:read", "ai_sdr:update", "ai_sdr:delete", "ai_sdr_replies:all", "ai_sdr_replies:create", "ai_sdr_replies:read", "ai_sdr_replies:update", "ai_sdr_replies:delete", "ai_inbox_manager_analytics:all", "ai_inbox_manager_analytics:create", "ai_inbox_manager_analytics:read", "ai_inbox_manager_analytics:update", "ai_inbox_manager_analytics:delete", "sales_flows:all", "sales_flows:create", "sales_flows:read", "sales_flows:update", "sales_flows:delete", "webhooks:all", "webhooks:create", "webhooks:read", "webhooks:update", "webhooks:delete", "webhook_events:all", "webhook_events:create", "webhook_events:read", "webhook_events:update", "webhook_events:delete", "security_tokens:all", "security_tokens:create", "security_tokens:read", "security_tokens:update", "security_tokens:delete", "dfy_email_account_orders:all", "dfy_email_account_orders:create", "dfy_email_account_orders:read", "dfy_email_account_orders:update", "dfy_email_account_orders:delete", "auth:all", "auth:create", "auth:read", "auth:update", "auth:delete" ], "example": "campaigns:create" } } }, "required": [ "name", "scopes" ], "additionalProperties": false } } }, "required": true, "description": "The API Key to create" }, "responses": { "200": { "description": "The API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-9" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listAPIKey", "summary": "List api key", "tags": [ "APIKey" ], "description": "Requires one of the following scopes: `api_keys:read`, `api_keys:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." } ], "responses": { "200": { "description": "The list of API Key", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of API Key", "items": { "$ref": "#/components/schemas/def-9" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-617b-772a-b713-bfc982d8a40e" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/api-keys/{id}": { "delete": { "operationId": "deleteAPIKey", "summary": "Delete api key", "tags": [ "APIKey" ], "description": "Requires one of the following scopes: `api_keys:delete`, `api_keys:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-617c-7f11-bec1-93257c8d2cf0" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted API Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-9" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/audit-logs": { "get": { "operationId": "listAuditLog", "summary": "List audit log", "tags": [ "AuditLog" ], "description": "Requires one of the following scopes: `audit_logs:read`, `audit_logs:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "number", "example": 1 }, "in": "query", "name": "activity_type", "required": false, "description": "Filter by activity type" }, { "schema": { "type": "string", "example": "login" }, "in": "query", "name": "search", "required": false, "description": "Search term to filter logs" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date to filter logs" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "end_date", "required": false, "description": "End date to filter logs" } ], "responses": { "200": { "description": "The list of Audit Log", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Audit Log", "items": { "$ref": "#/components/schemas/def-32" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6184-7580-a2f4-c0dfb46b192d" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/background-jobs": { "get": { "operationId": "listBackgroundJob", "summary": "List background job", "tags": [ "BackgroundJob" ], "description": "Requires one of the following scopes: `background-jobs:read`, `background-jobs:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "in": "query", "name": "starting_after", "required": false }, { "schema": { "type": "string", "example": "676f3caadedbfe9abea3bab4" }, "in": "query", "name": "ids", "required": false, "description": "The ID of the job. Multiple IDs can be provided as a comma-separated list" }, { "schema": { "type": "string", "example": "676f3caadedbfe9abea3bab4" }, "in": "query", "name": "included_ids", "required": false, "description": "The ID of the job to be included in the response. Multiple IDs can be provided as a comma-separated list" }, { "schema": { "type": "string", "example": "676f3caadedbfe9abea3bab4" }, "in": "query", "name": "excluded_ids", "required": false, "description": "The ID of the job to be excluded from the response. Multiple IDs can be provided as a comma-separated list" }, { "schema": { "type": "string", "enum": [ "move-leads", "import-leads", "export-leads", "update-warmup-accounts", "rename-variable" ], "example": "move-leads" }, "in": "query", "name": "type", "required": false, "description": "The type of the job" }, { "schema": { "type": "string", "enum": [ "list", "campaign", "workspace" ], "example": "list" }, "in": "query", "name": "entity_type", "required": false, "description": "The type of the entity" }, { "schema": { "type": "string", "example": "676f3caadedbfe9abea3bab4" }, "in": "query", "name": "entity_id", "required": false, "description": "The ID of the entity. Multiple IDs can be provided as a comma-separated list" }, { "schema": { "type": "string", "example": "pending,in-progress" }, "in": "query", "name": "status", "required": false, "description": "The status of the job. Multiple statuses can be provided as a comma-separated list. Valid statuses are: pending, in-progress, success, failed" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "x-enumDescriptions": { "created_at": "Created at", "updated_at": "Updated at" }, "example": "created_at" }, "in": "query", "name": "sort_column", "required": false, "description": "The column to sort the results by" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "x-enumDescriptions": { "asc": "Ascending", "desc": "Descending" }, "example": "desc" }, "in": "query", "name": "sort_order", "required": false, "description": "The order to sort the results by" } ], "responses": { "200": { "description": "The list of Background Job", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Background Job", "items": { "$ref": "#/components/schemas/def-12" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-618c-778b-b554-01fb5c52047b" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/background-jobs/{id}": { "get": { "operationId": "getBackgroundJob", "summary": "Get background job", "tags": [ "BackgroundJob" ], "description": "Requires one of the following scopes: `background-jobs:read`, `background-jobs:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "success_count,failed_count,total_to_process" }, "in": "query", "name": "data_fields", "required": false, "description": "Comma-separated list of fields to include from the `data` object (e.g., \"success_count,failed_count\")." }, { "schema": { "type": "string", "example": "69ff8d688ee71f4b5da21b14" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Background Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-12" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/block-lists-entries": { "post": { "operationId": "createBlockListEntry", "summary": "Create block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:create`, `block_list_entries:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateBlock List Entry", "description": "The Block List Entry to create", "type": "object", "properties": { "bl_value": { "type": "string", "description": "The email or domain to block", "example": "example.com" } }, "required": [ "bl_value" ], "additionalProperties": false } } }, "required": true, "description": "The Block List Entry to create" }, "responses": { "200": { "description": "The Block List Entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-15" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listBlockListEntry", "summary": "List block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "domains_only", "required": false, "description": "Filter by domain" }, { "schema": { "type": "string", "example": "example.com" }, "in": "query", "name": "search", "required": false, "description": "Search by value" } ], "responses": { "200": { "description": "The list of Block List Entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Block List Entry", "items": { "$ref": "#/components/schemas/def-15" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6199-7123-9db8-3e10a1a91a6d" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteallBlockListEntry", "summary": "Delete all block list entries", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "domains_only", "required": false, "description": "Filter by domain" }, { "schema": { "type": "string", "example": "example.com" }, "in": "query", "name": "search", "required": false, "description": "Search by value" } ], "responses": { "200": { "description": "List of deleted Block List Entry", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/def-15" } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/block-lists-entries/{id}": { "get": { "operationId": "getBlockListEntry", "summary": "Get block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6198-7ec2-9a71-9e93ebf10058" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Block List Entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-15" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchBlockListEntry", "summary": "Patch block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:update`, `block_list_entries:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "bl_value": { "type": "string", "description": "The email or domain to block", "example": "example.com" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-619a-7b2f-b325-695ee3111cc2" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Block List Entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-15" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteBlockListEntry", "summary": "Delete block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-619b-7253-91b9-9ac36ebc64b6" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Block List Entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-15" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/block-lists-entries/bulk-create": { "post": { "operationId": "createblukBlockListEntry", "summary": "Bulk create block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:create`, `block_list_entries:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "BulkCreate Block List Entry", "description": "Domains or emails to block", "type": "object", "required": [ "bl_values" ], "properties": { "bl_values": { "type": "array", "description": "List of domains or emails to block", "example": [ "example.com", "user@example.com" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 } } } } }, "required": true, "description": "Domains or emails to block" }, "responses": { "200": { "description": "List of created Block List Entry", "content": { "application/json": { "schema": { "title": "Bulk Created Block List Entries", "type": "object", "required": [ "items", "valid_count", "invalid_count" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/def-15" } }, "valid_count": { "type": "number", "description": "Number of valid entries", "example": 1 }, "invalid_count": { "type": "number", "description": "Number of invalid entries", "example": 0 } } } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/block-lists-entries/bulk-delete": { "post": { "operationId": "deletebulkBlockListEntry", "summary": "Bulk delete block list entry", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "Bulk Delete Block List Entry", "description": "Block list entry ids to delete", "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "List block list entry ids to delete", "example": [ "019c0e38-b39d-7504-93ef-1e032de54779", "019c0e38-b39d-7504-93ef-1e022fed2086" ], "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 } } } } }, "required": true, "description": "Block list entry ids to delete" }, "responses": { "200": { "description": "List of deleted Block List Entry", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/def-15" } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/block-lists-entries/download": { "get": { "operationId": "downloadBlockListEntry", "summary": "Download all block list entries as CSV", "tags": [ "BlockListEntry" ], "description": "Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "domains_only", "required": false, "description": "Filter by domain" }, { "schema": { "type": "string", "example": "example.com" }, "in": "query", "name": "search", "required": false, "description": "Search by value" } ], "responses": { "200": { "description": "The list of Block List Entry", "content": { "text/csv": { "schema": { "type": "string", "example": "Blocked Email,Date\r\nexample.com,2023-09-15T12:00:00Z\r\nuser@example.org,2023-09-15T12:00:00Z" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns": { "post": { "operationId": "createCampaign", "summary": "Create campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateCampaign", "description": "The Campaign to create", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the campaign", "example": "My First Campaign" }, "pl_value": { "type": [ "number", "null" ], "description": "Value of every positive lead", "example": 100 }, "is_evergreen": { "type": [ "boolean", "null" ], "description": "Whether the campaign is evergreen", "example": false }, "campaign_schedule": { "type": "object", "description": "Campaign schedule", "properties": { "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "End date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "My Schedule" }, "timing": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "09:00" }, "to": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "17:00" } }, "required": [ "from", "to" ] }, "days": { "type": "object", "minProperties": 1, "properties": { "0": { "type": "boolean", "example": true }, "1": { "type": "boolean", "example": true }, "2": { "type": "boolean", "example": true }, "3": { "type": "boolean", "example": true }, "4": { "type": "boolean", "example": true }, "5": { "type": "boolean", "example": false }, "6": { "type": "boolean", "example": false } } }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "example": "Etc/GMT+12" } }, "required": [ "name", "timing", "days", "timezone" ] }, "minItems": 1 } }, "required": [ "schedules" ] }, "sequences": { "type": "array", "description": "List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array", "items": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ], "x-enumDescriptions": { "email": "This steps represents an email" }, "description": "Type of step. This has to be 'email' always - it's the only supported type for now", "example": "email" }, "delay": { "type": "number", "description": "The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).", "example": 2 }, "delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.", "example": "days" }, "pre_delay": { "type": "number", "description": "The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).", "example": 2 }, "pre_delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.", "example": "days" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "example": "Hello {{firstName}}" }, "body": { "type": "string", "example": "Hey {{firstName}},\n\nI hope you are doing well." }, "v_disabled": { "type": "boolean", "description": "Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant", "example": true } }, "required": [ "subject", "body" ] } } }, "required": [ "type", "delay", "variants" ] } } }, "required": [ "steps" ] } }, "email_gap": { "type": [ "number", "null" ], "description": "The gap between emails in minutes", "example": 10 }, "random_wait_max": { "type": [ "number", "null" ], "description": "The maximum random wait time in minutes", "example": 10 }, "text_only": { "type": [ "boolean", "null" ], "description": "Whether the campaign is text only", "example": false }, "first_email_text_only": { "type": [ "boolean", "null" ], "description": "Whether the campaign is send the first email as a text only", "example": false }, "email_list": { "type": "array", "description": "List of accounts to use for sending emails", "items": { "type": "string", "example": "john@doe.com" } }, "daily_limit": { "type": [ "number", "null" ], "description": "The daily limit for sending emails", "example": 100 }, "stop_on_reply": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign on reply", "example": false }, "email_tag_list": { "type": "array", "description": "List of tags to use for sending emails", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91e96ef650a9" } }, "link_tracking": { "type": [ "boolean", "null" ], "description": "Whether to track links in emails", "example": true }, "open_tracking": { "type": "boolean", "description": "Whether to track opens in emails", "example": true }, "stop_on_auto_reply": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign on auto reply", "example": false }, "daily_max_leads": { "type": [ "integer", "null" ], "description": "The daily maximum new leads to contact", "minimum": 0, "example": 100 }, "prioritize_new_leads": { "type": [ "boolean", "null" ], "description": "Whether to prioritize new leads", "example": false }, "auto_variant_select": { "type": [ "object", "null" ], "description": "Auto variant select settings", "properties": { "trigger": { "type": "string", "enum": [ "reply_rate", "click_rate", "open_rate" ], "example": "click_rate" } }, "required": [ "trigger" ] }, "match_lead_esp": { "type": [ "boolean", "null" ], "description": "Whether to match leads by ESP", "example": false }, "stop_for_company": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign for the entire company(domain) when a lead replies", "example": false }, "insert_unsubscribe_header": { "type": [ "boolean", "null" ], "description": "Whether to insert an unsubscribe header in emails", "example": false }, "allow_risky_contacts": { "type": [ "boolean", "null" ], "description": "Whether to allow risky contacts", "example": false }, "disable_bounce_protect": { "type": [ "boolean", "null" ], "description": "Whether to disable bounce protection", "example": false }, "limit_emails_per_company_override": { "type": [ "object", "null" ], "description": "Overrides the workspace-wide limit emails per company setting for this campaign.", "properties": { "mode": { "type": "string", "enum": [ "custom", "disabled" ], "example": "custom" }, "daily_limit": { "type": "number", "minimum": 1, "example": 3 }, "scope": { "type": "string", "enum": [ "per_campaign", "across_workspace" ], "example": "per_campaign" } }, "required": [ "mode" ] }, "cc_list": { "type": "array", "description": "List of accounts to CC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "bcc_list": { "type": "array", "description": "List of accounts to BCC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "owned_by": { "type": [ "string", "null" ], "description": "Owner ID", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91ebee0ac63c" }, "ai_sdr_id": { "type": [ "string", "null" ], "description": "AI Sales Agent ID that created this campaign", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91ec400e40a2" }, "provider_routing_rules": { "type": "array", "description": "Auto variant select settings", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "send", "do_not_send" ], "example": "send" }, "recipient_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } }, "sender_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } } } }, "required": [ "action", "recipient_esp", "sender_esp" ] } }, "required": [ "name", "campaign_schedule" ], "additionalProperties": false } } }, "required": true, "description": "The Campaign to create" }, "responses": { "200": { "description": "The Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listCampaign", "summary": "List campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "example": "Summer Sale Campaign" }, "in": "query", "name": "search", "required": false, "description": "Search by campaign name" }, { "schema": { "type": "string", "example": "019e0e40-61ae-7b47-a24f-20d401585f4b,019e0e40-61ae-7b47-a24f-20d5a817f8cb" }, "in": "query", "name": "tag_ids", "required": false, "description": "Filter campaigns by tag ids. Returns campaigns that have any of the specified tags assigned. You can specify multiple tag ids by separating them with a comma." }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ae-7b47-a24f-20d632ff9988" }, "in": "query", "name": "ai_sales_agent_id", "required": false, "description": "Filter campaigns by AI Sales Agent ID. Returns campaigns that were created by the specified AI Sales Agent." }, { "schema": { "type": "number", "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 }, "in": "query", "name": "status", "required": false, "description": "Filter campaigns by status using the campaign status enum value (e.g., ACTIVE, PAUSED)." } ], "responses": { "200": { "description": "The list of Campaign", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Campaign", "items": { "$ref": "#/components/schemas/def-1" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-61ae-7b47-a24f-20d76f648255" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/activate": { "post": { "operationId": "activateCampaign", "summary": "Activate(start), or resume a campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ac-7c43-8924-e78e048f59e7" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "400": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/pause": { "post": { "operationId": "pauseCampaign", "summary": "Stop(or pause) a campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ad-73ea-be8c-ffa815f2d4c4" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "400": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}": { "get": { "operationId": "getCampaign", "summary": "Get campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ad-73ea-be8c-ffa9c70e5cac" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchCampaign", "summary": "Patch campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the campaign", "example": "My First Campaign" }, "pl_value": { "type": [ "number", "null" ], "description": "Value of every positive lead", "example": 100 }, "is_evergreen": { "type": [ "boolean", "null" ], "description": "Whether the campaign is evergreen", "example": false }, "campaign_schedule": { "type": "object", "description": "Campaign schedule", "properties": { "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "End date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "My Schedule" }, "timing": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "09:00" }, "to": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "17:00" } }, "required": [ "from", "to" ] }, "days": { "type": "object", "minProperties": 1, "properties": { "0": { "type": "boolean", "example": true }, "1": { "type": "boolean", "example": true }, "2": { "type": "boolean", "example": true }, "3": { "type": "boolean", "example": true }, "4": { "type": "boolean", "example": true }, "5": { "type": "boolean", "example": false }, "6": { "type": "boolean", "example": false } } }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "example": "Etc/GMT+12" } }, "required": [ "name", "timing", "days", "timezone" ] }, "minItems": 1 } }, "required": [ "schedules" ] }, "sequences": { "type": "array", "description": "List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array", "items": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ], "x-enumDescriptions": { "email": "This steps represents an email" }, "description": "Type of step. This has to be 'email' always - it's the only supported type for now", "example": "email" }, "delay": { "type": "number", "description": "The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).", "example": 2 }, "delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.", "example": "days" }, "pre_delay": { "type": "number", "description": "The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).", "example": 2 }, "pre_delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.", "example": "days" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "example": "Hello {{firstName}}" }, "body": { "type": "string", "example": "Hey {{firstName}},\n\nI hope you are doing well." }, "v_disabled": { "type": "boolean", "description": "Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant", "example": true } }, "required": [ "subject", "body" ] } } }, "required": [ "type", "delay", "variants" ] } } }, "required": [ "steps" ] } }, "email_gap": { "type": [ "number", "null" ], "description": "The gap between emails in minutes", "example": 10 }, "random_wait_max": { "type": [ "number", "null" ], "description": "The maximum random wait time in minutes", "example": 10 }, "text_only": { "type": [ "boolean", "null" ], "description": "Whether the campaign is text only", "example": false }, "first_email_text_only": { "type": [ "boolean", "null" ], "description": "Whether the campaign is send the first email as a text only", "example": false }, "email_list": { "type": "array", "description": "List of accounts to use for sending emails", "items": { "type": "string", "example": "john@doe.com" } }, "daily_limit": { "type": [ "number", "null" ], "description": "The daily limit for sending emails", "example": 100 }, "stop_on_reply": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign on reply", "example": false }, "email_tag_list": { "type": "array", "description": "List of tags to use for sending emails", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91e96ef650a9" } }, "link_tracking": { "type": [ "boolean", "null" ], "description": "Whether to track links in emails", "example": true }, "open_tracking": { "type": "boolean", "description": "Whether to track opens in emails", "example": true }, "stop_on_auto_reply": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign on auto reply", "example": false }, "daily_max_leads": { "type": [ "integer", "null" ], "description": "The daily maximum new leads to contact", "minimum": 0, "example": 100 }, "prioritize_new_leads": { "type": [ "boolean", "null" ], "description": "Whether to prioritize new leads", "example": false }, "auto_variant_select": { "type": [ "object", "null" ], "description": "Auto variant select settings", "properties": { "trigger": { "type": "string", "enum": [ "reply_rate", "click_rate", "open_rate" ], "example": "click_rate" } }, "required": [ "trigger" ] }, "match_lead_esp": { "type": [ "boolean", "null" ], "description": "Whether to match leads by ESP", "example": false }, "stop_for_company": { "type": [ "boolean", "null" ], "description": "Whether to stop the campaign for the entire company(domain) when a lead replies", "example": false }, "insert_unsubscribe_header": { "type": [ "boolean", "null" ], "description": "Whether to insert an unsubscribe header in emails", "example": false }, "allow_risky_contacts": { "type": [ "boolean", "null" ], "description": "Whether to allow risky contacts", "example": false }, "disable_bounce_protect": { "type": [ "boolean", "null" ], "description": "Whether to disable bounce protection", "example": false }, "limit_emails_per_company_override": { "type": [ "object", "null" ], "description": "Overrides the workspace-wide limit emails per company setting for this campaign.", "properties": { "mode": { "type": "string", "enum": [ "custom", "disabled" ], "example": "custom" }, "daily_limit": { "type": "number", "minimum": 1, "example": 3 }, "scope": { "type": "string", "enum": [ "per_campaign", "across_workspace" ], "example": "per_campaign" } }, "required": [ "mode" ] }, "cc_list": { "type": "array", "description": "List of accounts to CC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "bcc_list": { "type": "array", "description": "List of accounts to BCC on emails", "items": { "type": "string", "format": "email", "example": "john@doe.com" } }, "owned_by": { "type": [ "string", "null" ], "description": "Owner ID", "format": "uuid", "example": "019e0e40-2a05-7a09-9340-91ebee0ac63c" }, "provider_routing_rules": { "type": "array", "description": "Auto variant select settings", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "send", "do_not_send" ], "example": "send" }, "recipient_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } }, "sender_esp": { "type": "array", "items": { "type": "string", "enum": [ "all", "google", "outlook", "other" ], "example": "all" } } } }, "required": [ "action", "recipient_esp", "sender_esp" ] } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b7-76ab-9d86-cc99462082f0" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteCampaign", "summary": "Delete campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:delete`, `campaigns:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b8-7f5b-9597-279a63260470" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/search-by-contact": { "get": { "operationId": "searchByContact", "summary": "Search campaigns by lead email", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "lead-email@example.com" }, "in": "query", "name": "search", "required": false, "description": "Search by lead email" }, { "schema": { "type": "string", "default": "timestamp_created", "example": "timestamp_created" }, "in": "query", "name": "sort_column", "required": false, "description": "Sort campaigns by column name" }, { "schema": { "type": "string", "default": "asc", "example": "asc" }, "in": "query", "name": "sort_order", "required": false, "description": "Sort direction" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/def-1" } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/analytics": { "get": { "operationId": "getCampaignAnalytics", "summary": "Get campaign(s) analytics", "tags": [ "Campaign", "Analytics" ], "description": "Get analytics for one or multiple campaigns. Specify the `id` field to get the analytics for a single campaign, or leave it empty to get the analytics for all campaigns", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b0-7595-abc7-a7e1bd0022a4" }, "in": "query", "name": "id", "required": false, "description": "A campaign ID to get the analytics for. Leave this field empty to get the analytics for all campaigns" }, { "schema": { "type": "array", "items": { "type": "string", "description": "A list of campaign IDs to get the analytics for. Leave this field empty to get the analytics for all campaigns. You can specify multiple IDs by adding the same parameter multiple times, for instance: `/campaigns/analytics?ids=123&ids=456`", "format": "uuid", "example": "019e0e40-61b0-7595-abc7-a7e28058b652" } }, "in": "query", "name": "ids", "required": false }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "end_date", "required": false, "description": "End date" }, { "schema": { "type": "boolean", "default": false, "example": true }, "in": "query", "name": "exclude_total_leads_count", "required": false, "description": "Exclude the total leads from the result. Setting this to true will considerably decrease the response time" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "campaign_name": { "type": "string", "description": "The name of the campaign", "example": "My Test Campaign" }, "campaign_id": { "type": "string", "description": "The ID of the campaign", "format": "uuid", "example": "019e0e40-61b0-7595-abc7-a7e3db3bac75" }, "campaign_status": { "type": "number", "description": "The campaign status", "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 }, "campaign_is_evergreen": { "type": "boolean", "description": "Whether the campaign is evergreen", "example": true }, "leads_count": { "type": "integer", "description": "The total number of leads", "example": 1500 }, "contacted_count": { "type": "integer", "description": "Number of leads for whom the sequence has started", "example": 1200 }, "emails_sent_count": { "type": "integer", "description": "The total number of sent emails", "example": 5000 }, "new_leads_contacted_count": { "type": "integer", "description": "The total number of new leads contacted", "example": 200 }, "open_count": { "type": "integer", "description": "The number of leads that opened at least one email", "example": 800 }, "open_count_unique": { "type": "integer", "description": "The number of unique email opens (first open per lead)", "example": 750 }, "open_count_unique_by_step": { "type": "integer", "description": "The number of unique email opens per step (first open per lead per step)", "example": 900 }, "reply_count": { "type": "integer", "description": "The total number of replies received (if a lead replies multiple times, each reply is counted)", "example": 300 }, "reply_count_unique": { "type": "integer", "description": "The number of unique replies (first reply per lead). Excludes automatic replies.", "example": 280 }, "reply_count_unique_by_step": { "type": "integer", "description": "The number of unique replies per step (first reply per lead per step). Excludes automatic replies.", "example": 350 }, "reply_count_automatic": { "type": "integer", "description": "The total number of automatic replies detected", "example": 15 }, "reply_count_automatic_unique": { "type": "integer", "description": "The number of unique automatic replies (first automatic reply per lead)", "example": 12 }, "reply_count_automatic_unique_by_step": { "type": "integer", "description": "The number of unique automatic replies per step", "example": 18 }, "link_click_count": { "type": "integer", "description": "The number of links that got clicked", "example": 800 }, "link_click_count_unique": { "type": "integer", "description": "The number of unique link clicks (first click per lead)", "example": 600 }, "link_click_count_unique_by_step": { "type": "integer", "description": "The number of unique link clicks per step (first click per lead per step)", "example": 720 }, "bounced_count": { "type": "integer", "description": "The number of bounced leads", "example": 50 }, "unsubscribed_count": { "type": "integer", "description": "The number of unsubscribed leads", "example": 20 }, "completed_count": { "type": "integer", "description": "The number of leads that the campaign was completed for", "example": 1100 }, "total_opportunities": { "type": "integer", "description": "The total number of unique opportunities created", "example": 10 }, "total_opportunity_value": { "type": "number", "description": "The total value of opportunities created", "example": 1000 } }, "required": [ "campaign_name", "campaign_id", "campaign_status", "campaign_is_evergreen", "leads_count", "contacted_count", "open_count", "reply_count", "link_click_count", "bounced_count", "unsubscribed_count", "completed_count", "emails_sent_count", "new_leads_contacted_count", "total_opportunities", "total_opportunity_value" ] } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Start Date must be earlier than End Date" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/analytics/overview": { "get": { "operationId": "getCampaignAnalyticsOverview", "summary": "Get campaign(s) analytics overview", "tags": [ "Campaign", "Analytics" ], "description": "Get analytics overview for one or multiple campaigns. Specify the `id` field to get the analytics overview for a single campaign, or leave it empty to get the analytics overview for all campaigns.\n\nNote regarding the interest status totals (interested, meeting booked, meeting completed, closed): these are calculated based on the first occurrence of each event per contact by default. To change this behavior and calculate the totals based on all occurrences of the events, set the `expand_crm_events` parameter to `true`. Additionally, there is a 10 minute time window after you change a lead status in which the subsequent updates will NOT insert new analytics events to avoid duplicates from rapid status changes and avoid false inflation of the analytics numbers.", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b1-7c3e-894a-a9a9d66a02fe" }, "in": "query", "name": "id", "required": false, "description": "A campaign ID to get the analytics overview for. Leave this field empty to get the analytics overview for all campaigns" }, { "schema": { "type": "array", "items": { "type": "string", "description": "A list of campaign IDs to get the analytics overview for. Leave this field empty to get the analytics overview for all campaigns. You can specify multiple IDs by adding the same parameter multiple times, for instance: `/campaigns/analytics/overview?ids=123&ids=456`", "format": "uuid", "example": "019e0e40-61b1-7c3e-894a-a9aaf7d4e78b" } }, "in": "query", "name": "ids", "required": false }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "end_date", "required": false, "description": "End date" }, { "schema": { "type": "number", "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 }, "in": "query", "name": "campaign_status", "required": false, "description": "Filter by campaign status (only the analytics for the campaigns with the specified status will be returned)" }, { "schema": { "type": "boolean", "default": false, "example": true }, "in": "query", "name": "expand_crm_events", "required": false, "description": "When `true`, calculates the total of all the lead interest status update events instead of only the first occurrence for each contact. This will affect the following fields: `total_opportunities`, `total_interested`, `total_meeting_booked`, `total_meeting_completed`, and `total_closed`. Example: if a lead goes from interested to meeting booked to closed, it will count as 3 events (total_interested: 1, total_meeting_booked_1, and total_closed: 1) when this parameter is set to true, and as 1 event (total_interested) when it is set to false (default)." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "open_count": { "type": "integer", "description": "The total number of times the emails were opened, including duplicates", "example": 800 }, "open_count_unique": { "type": "integer", "description": "The number of emails that got opened (for the first time only)", "example": 800 }, "open_count_unique_by_step": { "type": "integer", "description": "The unique number of times the emails were opened (counted once per lead, step, and campaign)", "example": 800 }, "link_click_count": { "type": "integer", "description": "The number of links that got clicked", "example": 800 }, "link_click_count_unique": { "type": "integer", "description": "The number of links that got clicked (for the first time)", "example": 800 }, "link_click_count_unique_by_step": { "type": "integer", "description": "The unique number of links that got clicked, per step (counted once per lead, step, and campaign)", "example": 800 }, "reply_count": { "type": "integer", "description": "The total number of replies received (if a lead replies multiple times, each reply is counted)", "example": 300 }, "reply_count_unique": { "type": "integer", "description": "The number of unique replies (first reply per lead). Excludes automatic replies.", "example": 300 }, "reply_count_unique_by_step": { "type": "integer", "description": "The number of unique replies per step (first reply per lead per step). Excludes automatic replies.", "example": 300 }, "reply_count_automatic": { "type": "integer", "description": "The total number of automatic replies received (e.g., out-of-office)", "example": 50 }, "reply_count_automatic_unique": { "type": "integer", "description": "The number of unique leads that sent automatic replies", "example": 45 }, "reply_count_automatic_unique_by_step": { "type": "integer", "description": "The unique number of automatic replies per step (counted once per lead, step, and campaign)", "example": 45 }, "bounced_count": { "type": "integer", "description": "The number of bounced leads", "example": 50 }, "unsubscribed_count": { "type": "integer", "description": "The number of unsubscribed leads", "example": 20 }, "completed_count": { "type": "integer", "description": "The number of leads that the campaign was completed for", "example": 1100 }, "emails_sent_count": { "type": "integer", "description": "The total number of sent emails", "example": 5000 }, "contacted_count": { "type": "integer", "description": "The total number of unique leads contacted", "example": 4500 }, "new_leads_contacted_count": { "type": "integer", "description": "The total number of new leads contacted", "example": 200 }, "total_opportunities": { "type": "integer", "description": "The total number of unique opportunities created", "example": 10 }, "total_opportunity_value": { "type": "number", "description": "The total value of opportunities created", "example": 1000 }, "total_interested": { "type": "integer", "description": "The total number of interested opportunities created", "example": 103 }, "total_meeting_booked": { "type": "integer", "description": "The total number of meeting booked opportunities created", "example": 45 }, "total_meeting_completed": { "type": "integer", "description": "The total number of meeting completed opportunities created", "example": 12 }, "total_closed": { "type": "integer", "description": "The total number of closed opportunities created", "example": 10 } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Start Date must be earlier than End Date" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/analytics/daily": { "get": { "operationId": "getDailyCampaignAnalytics", "summary": "Get daily campaign analytics", "tags": [ "Campaign", "Analytics" ], "description": "Get campaign daily analytics", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b3-7532-a99c-a07da8b4c700" }, "in": "query", "name": "campaign_id", "required": false, "description": "Campaign ID (optional). Leave this field empty to get the analytics for all campaigns" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "end_date", "required": false, "description": "End date" }, { "schema": { "type": "number", "enum": [ -99, -1, -2, 0, 1, 2, 3, 4 ], "x-enumDescriptions": { "0": "Draft", "1": "Active", "2": "Paused", "3": "Completed", "4": "Running Subsequences", "-99": "Account Suspended", "-1": "Accounts Unhealthy", "-2": "Bounce Protect" }, "example": 1 }, "in": "query", "name": "campaign_status", "required": false, "description": "Filter by campaign status (only the analytics for the campaigns with the specified status will be returned)" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date of the analytics entry, in YYYY-MM-DD format", "example": "2025-03-01" }, "sent": { "type": "integer", "description": "The total number of sent emails", "example": 5421 }, "contacted": { "type": "integer", "description": "The total number of unique contacts who received an email that day", "example": 5000 }, "new_leads_contacted": { "type": "integer", "description": "The total number of new leads contacted that day", "example": 200 }, "opened": { "type": "integer", "description": "The total number of opened emails", "example": 99 }, "unique_opened": { "type": "integer", "description": "The total number of unique opened emails", "example": 60 }, "replies": { "type": "integer", "description": "The total number of replies", "example": 60 }, "unique_replies": { "type": "integer", "description": "The total number of unique replies", "example": 60 }, "replies_automatic": { "type": "integer", "description": "The total number of automatic replies detected", "example": 5 }, "unique_replies_automatic": { "type": "integer", "description": "The total number of unique automatic replies detected", "example": 4 }, "clicks": { "type": "integer", "description": "The total number of links clicked", "example": 60 }, "unique_clicks": { "type": "integer", "description": "The total number of unique links clicked. Unique meaning from unique leads, not unique links. For instance, if a lead clicked a link 3 times, it will be counted as 1 unique click. If a lead clicked 3 different links, it will still be counted as 1 unique click", "example": 60 }, "opportunities": { "type": "integer", "description": "The total number of unique opportunities created from the campaign on that day", "example": 5 }, "unique_opportunities": { "type": "integer", "description": "The total number of unique opportunities created from unique leads from the campaign on that day", "example": 3 } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Start Date must be earlier than End Date" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/analytics/steps": { "get": { "operationId": "getCampaignStepsAnalytics", "summary": "Get campaign steps analytics", "tags": [ "Campaign", "Analytics" ], "description": "Get campaign steps analytics", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b4-7985-a978-9f046f626ff1" }, "in": "query", "name": "campaign_id", "required": false, "description": "Campaign ID (optional). Leave this field empty to get the analytics for all campaigns" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "start_date", "required": false, "description": "Start date" }, { "schema": { "type": "string", "example": "2024-01-01" }, "in": "query", "name": "end_date", "required": false, "description": "End date" }, { "schema": { "type": "boolean", "default": false, "example": true }, "in": "query", "name": "include_opportunities_count", "required": false, "description": "Whether to include the opportunities count per step. If this field is true then `opportunities` and `unique_opportunities` fields will be included in the response" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": [ "null", "string" ], "description": "The step number. When null it means we couldn't determine the step number for the event, for instance for list leads, which are not part of a campaign.", "example": "1" }, "variant": { "type": [ "null", "string" ], "description": "The variant number, starting from 0. 0 = A, 1 = B, 2 = C, etc. When null it means we couldn't determine the variant for the event.", "example": "0" }, "sent": { "type": "integer", "description": "The total number of sent emails", "example": 5421 }, "opened": { "type": "integer", "description": "The total number of opened emails", "example": 99 }, "unique_opened": { "type": "integer", "description": "The total number of opened emails", "example": 60 }, "replies": { "type": "integer", "description": "The total number of replies", "example": 60 }, "unique_replies": { "type": "integer", "description": "The total number of replies", "example": 60 }, "replies_automatic": { "type": "integer", "description": "The total number of automatic replies detected", "example": 5 }, "unique_replies_automatic": { "type": "integer", "description": "The total number of unique automatic replies detected", "example": 4 }, "clicks": { "type": "integer", "description": "The total number of links clicked", "example": 60 }, "unique_clicks": { "type": "integer", "description": "The total number of unique links clicked. Unique meaning from unique leads, not unique links. For instance, if a lead clicked a link 3 times, it will be counted as 1 unique click. If a lead clicked 3 different links, it will still be counted as 1 unique click", "example": 60 }, "opportunities": { "type": "integer", "description": "The total number of opportunities created from this step. Included only if `include_opportunities_count` is `true`", "example": 10 }, "unique_opportunities": { "type": "integer", "description": "The total number of unique opportunities created from this step. Unique meaning unique per lead. If a lead has multiple opportunities, it will be counted as 1 unique opportunity. Included only if `include_opportunities_count` is `true`", "example": 8 } }, "required": [ "step", "variant", "sent", "opened", "unique_opened", "replies", "unique_replies", "replies_automatic", "unique_replies_automatic", "clicks", "unique_clicks" ] } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message", "example": "Start Date must be earlier than End Date" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/share": { "post": { "operationId": "shareCampaign", "summary": "Share a campaign", "tags": [ "Campaign" ], "description": "Share a campaign. This allows other users to create new campaigns based on this campaign. The campaign is being shared for 7 days, after which you'll have to call this endpoint again if you want to enable sharing on the campaign", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b9-7766-94bf-cf246327f3ad" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "204": { "description": "Default Response", "content": { "application/json": { "schema": {} } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/from-export": { "post": { "operationId": "createFromExport", "summary": "Create campaign from shared one", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61b9-7766-94bf-cf259abb0c09" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "403": { "description": "The requested campaign not shared", "content": { "application/json": { "schema": { "type": "object", "description": "The requested campaign not shared", "properties": { "message": { "type": "string", "example": "The requested campaign not shared" } } } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/export": { "post": { "operationId": "exportCampaign", "summary": "Export campaign to JSON format", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ba-7bc7-954d-06991d4d5963" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/duplicate": { "post": { "operationId": "duplicate", "summary": "Duplicate campaign", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Campaign new name (optional). If not provided, it will default to CAMPAIGN NAME (copy).", "default": "Campaign Name (copy)", "example": "Campaign new name" } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61ba-7bc7-954d-069a138b535f" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "The requested Campaign", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "400": { "description": "Duplication failed", "content": { "application/json": { "schema": { "type": "object", "description": "Duplication failed", "properties": { "message": { "type": "string", "description": "The error message", "example": "New campaign name is required" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/count-launched": { "get": { "operationId": "countLaunched", "summary": "Get launched campaigns count", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number", "example": 2 } }, "required": [ "count" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/variables": { "post": { "operationId": "addVariables", "summary": "Add campaign variables", "tags": [ "Campaign" ], "description": "Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "string", "description": "Custom or core variable names", "example": "firstName" } } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61bc-762e-81ac-73d742cbdddf" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "A campaign that can be sent to a list of recipients", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-1" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/campaigns/{id}/sending-status": { "get": { "operationId": "getCampaignSendingStatus", "summary": "Get campaign sending status", "tags": [ "Campaign" ], "description": "Returns sending status data explaining why a campaign may not be sending emails or is sending slower than expected. Note: Some fields may be missing when the campaign is out of schedule. Always-present fields: campaign_id, last_updated, status, issue_tracking.\n\n\nRequires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "boolean", "default": false, "example": false }, "in": "query", "name": "with_ai_summary", "required": false, "description": "Include AI-generated summary" }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-61bd-7efd-a3bc-e6339b1fc457" }, "in": "path", "name": "id", "required": true, "description": "Campaign ID" } ], "responses": { "200": { "description": "Sending status data with human-readable summary. Returns null for both fields if no data is available.", "content": { "application/json": { "schema": { "type": "object", "description": "Sending status data with human-readable summary. Returns null for both fields if no data is available.", "properties": { "diagnostics": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Raw sending status data. Some fields may be missing when campaign is out of schedule.", "properties": { "campaign_id": { "type": "string", "description": "The campaign ID", "example": "019e0e40-4f29-7185-97ae-bed99021ab1f" }, "subsequence_id": { "type": "string", "description": "The subsequence ID (only present for subsequence endpoints)", "example": "019e0e40-4f29-7185-97ae-bedaaa07b3ea" }, "last_updated": { "type": "string", "description": "ISO timestamp of when this data was last updated", "example": "2026-05-09T19:39:16.137Z" }, "status": { "type": [ "null", "string" ], "description": "Status code explaining why the campaign is not sending or sending slower", "enum": [ "campaign_paused", "campaign_draft", "campaign_completed", "campaign_running_subsequences", "campaign_bounce_protect", "campaign_accounts_unhealthy", "campaign_account_suspended", "out_of_schedule", "waiting_for_leads", "daily_limit_met", "account_daily_limit_met", "new_lead_limit_met", "all_accounts_unhealthy", "waiting_for_esp_match", "domain_limit_reached", "follow_up_delay_not_met", "no_accounts_available", "healthy" ], "example": "healthy" }, "issue_tracking": { "type": "object", "description": "Tracks persistence of the current issue", "properties": { "current_status_code": { "type": [ "null", "string" ], "description": "Current status code", "example": "healthy" }, "issue_first_seen_at": { "type": [ "null", "string" ], "description": "ISO timestamp when the issue was first detected", "example": "2026-05-09T19:39:16.137Z" }, "consecutive_loops_with_issue": { "type": "number", "description": "Number of consecutive processing loops with this issue", "example": 0 }, "last_healthy_send_at": { "type": [ "null", "string" ], "description": "ISO timestamp of last successful send", "example": "2026-05-09T19:39:16.137Z" } } }, "accounts_summary": { "type": "object", "description": "Summary of sending account availability. May be missing when campaign is out of schedule.", "properties": { "total_connected": { "type": "number", "description": "Total number of connected sending accounts", "example": 5 }, "available": { "type": "number", "description": "Number of accounts available to send", "example": 3 }, "unavailable": { "type": "object", "description": "Breakdown of unavailable accounts by reason", "properties": { "daily_limit_hit": { "type": "number", "description": "Accounts that hit their configured daily sending limit", "example": 1 }, "slow_ramp_limit_hit": { "type": "number", "description": "Accounts that hit the dynamic slow ramp limit (warmup feature)", "example": 0 }, "disconnected": { "type": "number", "description": "Accounts that are disconnected", "example": 1 }, "global_gap_not_met": { "type": "number", "description": "Accounts waiting for global sending gap", "example": 0 } } } } }, "campaign_daily_limit": { "type": "object", "description": "Campaign daily sending limit status. May be missing when campaign is out of schedule.", "properties": { "limit": { "type": "number", "description": "Configured daily sending limit", "example": 100 }, "sent": { "type": "number", "description": "Number of emails sent today", "example": 50 }, "limit_hit": { "type": "boolean", "description": "Whether the daily limit has been reached", "example": false } } }, "new_lead_limit": { "type": "object", "description": "New lead daily limit status. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether new lead limiting is enabled", "example": true }, "limit": { "type": [ "null", "number" ], "description": "Configured new lead limit per day", "example": 50 }, "contacted": { "type": "number", "description": "Number of new leads contacted today", "example": 25 }, "limit_hit": { "type": "boolean", "description": "Whether the new lead limit has been reached", "example": false } } }, "schedule_status": { "type": "object", "description": "Campaign schedule status", "properties": { "in_schedule": { "type": "boolean", "description": "Whether the campaign is currently within scheduled sending hours", "example": true } } }, "send_one_by_one": { "type": "object", "description": "Send one-by-one settings. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether send one-by-one mode is enabled", "example": false }, "single_account_per_wait_gap": { "type": "boolean", "description": "Whether to use single account per wait gap", "example": false } } }, "follow_ups_waiting": { "type": "object", "description": "Follow-up emails waiting status. May be missing when campaign is out of schedule.", "properties": { "count": { "type": "number", "description": "Number of follow-ups waiting to be sent", "example": 10 }, "earliest_wait_time_seconds": { "type": [ "null", "number" ], "description": "Seconds until the earliest follow-up can be sent", "example": 3600 } } }, "esp_routing_status": { "type": "object", "description": "ESP routing status. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether ESP routing is enabled", "example": false }, "waiting_for_match": { "type": "boolean", "description": "Whether waiting for an ESP-matched account", "example": false }, "connected_esps": { "type": "array", "items": { "type": "number", "example": 1 }, "description": "List of connected ESP IDs" } } }, "domain_limiter": { "type": "object", "description": "Per-domain sending limit status. May be missing when campaign is out of schedule.", "properties": { "active": { "type": "boolean", "description": "Whether domain limiting is active", "example": false }, "domains_at_limit": { "type": "number", "description": "Number of domains that have reached their limit", "example": 0 } } }, "leads_status": { "type": "object", "description": "Lead availability status. May be missing when campaign is out of schedule.", "properties": { "no_leads_ready": { "type": "boolean", "description": "Whether there are no leads ready to receive emails", "example": false }, "account_unavailable_skips": { "type": "number", "description": "Number of leads skipped due to account unavailability", "example": 0 }, "delay_not_met_skips": { "type": "number", "description": "Number of leads skipped due to delay requirements not met", "example": 0 } } } } }, "summary": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Human-readable summary of the sending status", "properties": { "status": { "type": [ "null", "string" ], "description": "The status code", "example": "healthy" }, "status_message": { "type": [ "null", "string" ], "description": "Human-readable message explaining the status", "example": "Campaign is sending normally" }, "issue_started_at": { "type": [ "null", "string" ], "description": "ISO timestamp when the issue was first detected", "example": "2026-05-09T19:39:16.137Z" }, "last_healthy_send_at": { "type": [ "null", "string" ], "description": "ISO timestamp of last successful send", "example": "2026-05-09T19:39:16.137Z" }, "ai_summary": { "type": [ "null", "string" ], "description": "AI-generated plain-English summary (only when with_ai_summary=true)", "example": "Your campaign is sending emails normally." } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/crm-actions/phone-numbers": { "get": { "operationId": "listPhoneNumbers", "summary": "List phone numbers", "tags": [ "CRMActions" ], "description": "Retrieve all phone numbers associated with the current organization.\n\n\nRequires one of the following scopes: `crm_actions:read`, `crm_actions:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the phone number record.", "example": "019e0e40-61ec-73e6-a56d-977990d239a9" }, "timestamp_created": { "type": "string", "format": "date-time", "description": "Timestamp when the phone number record was created.", "example": "2026-05-09T19:39:20.940Z" }, "organization_id": { "type": "string", "description": "Identifier of the organization that owns this phone number.", "example": "019e0e40-61ec-73e6-a56d-977aabb191be" }, "phone_number": { "type": "string", "description": "The phone number in international E.164 format.", "example": "+15551234567" }, "country": { "type": "string", "description": "Country code where the phone number is registered.", "example": "US" }, "locality": { "type": "string", "description": "City or region associated with the phone number.", "example": "San Francisco" }, "subscription_id": { "type": "string", "description": "Billing subscription ID linked to this phone number.", "example": "sub_1PuaE1B3VEKBA0ygDAKk7QVc" }, "twilio_sid": { "type": "string", "description": "Twilio resource SID for the phone number.", "example": "PN998dda028e07a49c8038b2206341d463" }, "renewal_date": { "type": "string", "format": "date", "description": "Next renewal date for the phone number subscription.", "example": "2026-05-09T19:39:20.940Z" }, "price": { "type": "number", "description": "Monthly price for this phone number (USD).", "example": 1 } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/crm-actions/phone-numbers/{id}": { "delete": { "operationId": "deletePhoneNumber", "summary": "Delete phone number", "tags": [ "CRMActions" ], "description": "Delete a specific phone number from the organization.\n\n\nRequires one of the following scopes: `crm_actions:delete`, `crm_actions:all`, `all:delete`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "019e0e40-61ed-7cd1-ac36-4e8664e65c79" }, "in": "path", "name": "id", "required": true, "description": "The phone number record id to delete" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted phone number record.", "example": "019e0e40-61ed-7cd1-ac36-4e8738ea3fa9" }, "timestamp_created": { "type": "string", "format": "date-time", "description": "Timestamp when the deleted record was originally created.", "example": "2026-05-09T19:39:20.941Z" }, "organization_id": { "type": "string", "description": "Identifier of the organization that owned the phone number.", "example": "019e0e40-61ed-7cd1-ac36-4e8883c7369a" }, "phone_number": { "type": "string", "description": "The deleted phone number.", "example": "+15551234567" }, "country": { "type": "string", "description": "Country code of the deleted phone number.", "example": "US" }, "locality": { "type": "string", "description": "Region or city associated with the deleted phone number.", "example": "San Francisco" }, "subscription_id": { "type": "string", "description": "Billing subscription ID associated with this number (if any).", "example": "sub_1PuaE1B3VEKBA0ygDAKk7QVc" }, "twilio_sid": { "type": "string", "description": "Twilio SID of the deleted number.", "example": "PN998dda028e07a49c8038b2206341d463" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/custom-tag-mappings": { "get": { "operationId": "listCustomTagMapping", "summary": "List custom tag mapping", "tags": [ "CustomTagMapping" ], "description": "Requires one of the following scopes: `custom_tag_mappings:read`, `custom_tag_mappings:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "example": "id1,id2,id3" }, "in": "query", "name": "resource_ids", "required": false, "description": "The list of resource ids to filter custom tag mappings by. A resource id is the id of an account or a campaign." } ], "responses": { "200": { "description": "The list of Custom Tag Mapping", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Custom Tag Mapping", "items": { "$ref": "#/components/schemas/def-14" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6205-78ec-a5d5-9e0139affa74" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/custom-tags": { "post": { "operationId": "createCustomTag", "summary": "Create custom tag", "tags": [ "CustomTag" ], "description": "Requires one of the following scopes: `custom_tags:create`, `custom_tags:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateCustom Tag", "description": "The Custom Tag to create", "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the custom tag", "example": "Important" }, "description": { "type": [ "string", "null" ], "description": "Detailed description of the custom tag purpose", "example": "Used for marking important items" } }, "required": [ "label" ], "additionalProperties": false } } }, "required": true, "description": "The Custom Tag to create" }, "responses": { "200": { "description": "The Custom Tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-13" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listCustomTag", "summary": "List custom tag", "tags": [ "CustomTag" ], "description": "Requires one of the following scopes: `custom_tags:read`, `custom_tags:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "example": "Important" }, "in": "query", "name": "search", "required": false, "description": "The search query to filter custom tags." }, { "schema": { "type": "string", "example": "id1,id2,id3" }, "in": "query", "name": "resource_ids", "required": false, "description": "The list of resource ids to filter custom tags by. A resource id is the id of an account or a campaign." }, { "schema": { "type": "string", "example": "id1,id2,id3" }, "in": "query", "name": "tag_ids", "required": false, "description": "The list of tag ids to filter custom tags by." } ], "responses": { "200": { "description": "The list of Custom Tag", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Custom Tag", "items": { "$ref": "#/components/schemas/def-13" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6210-716c-8c4e-953712de2bb1" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/custom-tags/{id}": { "get": { "operationId": "getCustomTag", "summary": "Get custom tag", "tags": [ "CustomTag" ], "description": "Requires one of the following scopes: `custom_tags:read`, `custom_tags:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6211-7db9-9aee-be275c2319b9" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Custom Tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-13" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchCustomTag", "summary": "Patch custom tag", "tags": [ "CustomTag" ], "description": "Requires one of the following scopes: `custom_tags:update`, `custom_tags:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the custom tag", "example": "Important" }, "description": { "type": [ "string", "null" ], "description": "Detailed description of the custom tag purpose", "example": "Used for marking important items" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6212-7214-990a-2d11ec396cc5" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Custom Tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-13" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteCustomTag", "summary": "Delete custom tag", "tags": [ "CustomTag" ], "description": "Requires one of the following scopes: `custom_tags:delete`, `custom_tags:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6213-7274-8fc9-a559c06623e7" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Custom Tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-13" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/custom-tags/toggle-resource": { "post": { "operationId": "toggleTagResource", "summary": "Assign or unassign tags to resources", "tags": [ "CustomTag" ], "description": "This can be used for both accounts and campaigns. Please check the `resource_type` field for more information.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-6212-7214-990a-2d12de76ec56" }, "description": "The list of tag ids to assign or unassign" }, "resource_type": { "type": "number", "enum": [ 1, 2 ], "description": "The resource type to assign or unassign the tags to", "x-enumDescriptions": { "1": "Account", "2": "Campaign" }, "example": 1 }, "resource_ids": { "type": "array", "items": { "type": "string", "example": "resource-1" }, "description": "The list of resource ids to assign or unassign. A resource id is the id of an account or a campaign." }, "assign": { "type": "boolean", "description": "Whether to assign the tags to the resources.", "example": true }, "selected_all": { "type": "boolean", "description": "Whether to select all resources.", "example": false }, "filter": { "type": "object", "description": "The filter to apply to the resources. These are only used when `selected_all` is true.", "oneOf": [ { "type": "string", "enum": [ "ACC_FILTER_PAUSED", "ACC_FILTER_ERROR", "ACC_FILTER_NO_CTD", "ACC_FILTER_PW_ACCOUNTS", "ACC_FILTER_DFY", "ACC_FILTER_DFY_SETUP_PENDING", "ACC_FILTER_W_ACTIVE", "ACC_FILTER_W_PAUSED", "ACC_FILTER_W_ERROR" ], "x-enumDescriptions": { "ACC_FILTER_PAUSED": "Paused", "ACC_FILTER_ERROR": "Error", "ACC_FILTER_NO_CTD": "No CTD", "ACC_FILTER_PW_ACCOUNTS": "PW Accounts", "ACC_FILTER_DFY": "DFY", "ACC_FILTER_DFY_SETUP_PENDING": "DFY Setup Pending", "ACC_FILTER_W_ACTIVE": "W Active", "ACC_FILTER_W_PAUSED": "W Paused", "ACC_FILTER_W_ERROR": "W Error" }, "example": "ACC_FILTER_PAUSED" }, { "type": "object", "properties": { "tag_id": { "type": "string", "format": "uuid", "example": "019e0e40-6212-7214-990a-2d136e085eb4" }, "search": { "type": "string", "example": "jon@doe.com" } } } ] } }, "required": [ "tag_ids", "resource_type", "resource_ids", "assign" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders": { "post": { "operationId": "createDFYEmailAccountOrder", "summary": "Place a DFY email account order", "tags": [ "DFYEmailAccountOrder" ], "description": "Place a Done-For-You (DFY) email account order for your workspace.\n\n**Order types**\n- `dfy`: Buy new DFY accounts on new custom domains.\n- `pre_warmed_up`: Buy available pre-warmed domains returned by `/dfy-email-account-orders/domains/pre-warmed-up-list`.\n- `extra_accounts`: Add mailboxes to domains you already ordered. All active accounts on a domain must use the same `email_provider`.\n\n**Provider limits and pricing**\n- `1` Google: up to 5 mailboxes per domain; per-mailbox monthly pricing.\n- `2` AirMail: up to 5 mailboxes per domain; per-mailbox monthly pricing.\n- `3` Microsoft/Outlook: exactly 50 mailboxes per new DFY domain; per-domain monthly pricing; extra-account orders are not supported.\n\n**Before ordering**\n- Regular DFY domains must use supported TLDs: .com, .org.\n- Check new-domain availability with `/dfy-email-account-orders/domains/check`.\n- For pre-warmed orders, choose a domain from `/dfy-email-account-orders/domains/pre-warmed-up-list`; if none are available, use a regular `dfy` order instead.\n- The workspace must have an Outreach plan and a default payment method.\n\n\nRequires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "List of domains and accounts to order", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain to use for the email accounts.For regular DFY accounts the only allowed domain extensions (tlds) are .com and .org.For regular DFY accounts - you can check the domain availability using the /dfy-email-account-orders/domains/check endpoint before placing an order.For pre-warmed up domains - use the /dfy-email-account-orders/domains endpoint to get a list of available domains.", "example": "example.com" }, "email_provider": { "type": "number", "description": "The mailbox product to order. Defaults to Google when omitted.\n\nOptions:\n- 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "default": 1, "example": 1 }, "forwarding_domain": { "type": "string", "description": "An optional domain to forward emails to. This domain must be different from the main domain.", "example": "forward-to-this-domain.com" }, "accounts": { "type": "array", "description": "List of email accounts to create (only if `pre_warmed_up` field is false). For pre-warmed up domains this field will be ignored because the accounts are already created and can't be changed. Please provide minimum 1 and maximum 5 accounts per domain for Google or AirMail, or exactly 50 for Microsoft/Outlook.", "items": { "type": "object", "properties": { "email_address_prefix": { "type": "string", "description": "The prefix for the email address (the part before the @). For instance, if the email address is \"john.doe@example.com\", then the email_address_prefix is \"john.doe\".", "example": "john.doe" }, "first_name": { "type": "string", "description": "The first name of the account owner", "example": "John" }, "last_name": { "type": "string", "description": "The last name of the account owner", "example": "Doe" } }, "required": [ "email_address_prefix", "first_name", "last_name" ] }, "default": [], "maxItems": 50 } }, "required": [ "domain" ] } }, "order_type": { "type": "string", "description": "The type of order to place. Please check the docs because this endpoint performs different actions based on the order type.", "enum": [ "dfy", "pre_warmed_up", "extra_accounts" ], "x-enumDescriptions": { "dfy": "Regular DFY accounts - it will place an order to buy new DFY accounts", "pre_warmed_up": "Pre-warmed up accounts - it will place an order to buy new pre-warmed up accounts", "extra_accounts": "Extra accounts - it will place an order to add extra accounts to already ordered domains" }, "example": "dfy" }, "simulation": { "type": "boolean", "description": "Whether to run a simulation of the order ot not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).", "default": false, "example": false } }, "required": [ "items", "order_type" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_placed": { "type": "boolean", "description": "Whether the order was placed or not. If true, then the order was placed successfully. If false, then the order was not placed due to an error or simulation mode was enabled.", "example": true }, "order_is_valid": { "type": "boolean", "description": "Whether the order is valid or not. If true, then the order is valid and can be placed. If false, then the order is not valid and cannot be placed. Use this field when you run a simulation to understand whether a real order would be valid.", "example": true }, "order_error": { "type": "string", "description": "The error that occurred if the order was not placed. If the order was placed successfully, then this field will be omitted.", "enum": [ "unavailable_domains", "blacklist_domains", "invalid_domains", "invalid_forwarding_domains", "invalid_accounts", "payment_failed", "missing_domain_orders", "domains_without_accounts", "provider_mismatch", "unsupported_provider", "provider_unavailable" ], "x-enumDescriptions": { "unavailable_domains": "Some domains are not available for order - check the `unavailable_domains` field", "blacklist_domains": "Some domains are blacklisted - check the `blacklist_domains` field", "invalid_domains": "Some domains are invalid - check the `invalid_domains` field", "invalid_forwarding_domains": "Some forwarding domains are invalid - check the `invalid_forwarding_domains` field", "invalid_accounts": "Some accounts are invalid - check the `invalid_accounts` field the list of invalid accounts", "payment_failed": "The payment failed - please make sure you have enough funds in your payment method", "missing_domain_orders": "Some domains are missing orders (when you set the `order_type` to `extra_accounts`, all the domains you want to add extra accounts to must be already ordered) - check the `missing_domain_orders` field", "domains_without_accounts": "Some domains are missing accounts - check the `domains_without_accounts` field", "provider_mismatch": "Some domains received an `email_provider` that does not match the existing accounts on that domain, or the domain is in a mixed provider state — check the `provider_mismatch_domains` field. All accounts for a domain must use the same provider.", "unsupported_provider": "Some domains use an existing provider that does not support extra-account orders through this endpoint - check the `unsupported_provider_domains` field.", "provider_unavailable": "One or more requested email providers are not available for ordering right now - check the `unavailable_email_providers` field." }, "example": "unavailable_domains" }, "unavailable_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of unavailable domains (if any)" }, "blacklist_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of blacklisted domains (if any)", "example": [ "example.com", "acme.com" ] }, "invalid_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of invalid domains (if any)", "example": [ "example.com", "acme.com" ] }, "invalid_forwarding_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of invalid forwarding domains (if any)", "example": [ "example.com", "acme.com" ] }, "missing_domain_orders": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of domains that are missing order (if any). Can happen when you order extra accounts for domains that you didn't order before." }, "provider_mismatch_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of domains whose requested `email_provider` does not match the existing active provider for that domain, or that are already in a mixed provider state in our records. All accounts for a domain must use the same provider." }, "unsupported_provider_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of domains that cannot receive extra accounts through this endpoint because their existing provider is not supported for public API extra-account orders." }, "unavailable_email_providers": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "example": 2 }, "description": "The requested email providers that are not available for ordering right now.", "example": [ 2 ] }, "domains_without_accounts": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of domains without accounts (if any). The `accounts` field for items in the `items` array for these domains was empty.", "example": [ "example.com", "acme.com" ] }, "invalid_accounts": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain", "example": "example.com" }, "first_name": { "type": "string", "description": "The account first name", "example": "John" }, "last_name": { "type": "string", "description": "The account last name", "example": "Doe" }, "email": { "type": "string", "description": "The account email", "example": "john.doe@example.com" }, "reason": { "type": "string", "description": "The reason why the account is invalid", "example": "First name is required" } }, "required": [ "domain", "first_name", "last_name", "email", "reason" ] }, "description": "The list of invalid accounts (if any)" }, "free_domains": { "type": "array", "items": { "type": "string", "example": "example.com" }, "description": "The list of domains that are free (domains can be free during promotions)", "example": [ "example.com", "acme.com" ] }, "number_of_domains_ordered": { "type": "number", "description": "The number of domains ordered", "example": 1 }, "number_of_accounts_ordered": { "type": "number", "description": "The number of accounts ordered", "example": 1 }, "price_per_account_per_month": { "type": "number", "description": "The monthly price charged per mailbox. Applies to per-account providers (Google, AirMail). For Microsoft/Outlook orders mailboxes are NOT charged individually — see `price_per_domain_per_month` instead.", "example": 4 }, "price_per_domain_per_month": { "type": [ "null", "number" ], "description": "The monthly price charged per domain. Populated only when the order contains Microsoft/Outlook items (domain-level billing: $20/month/domain for a fixed 50-mailbox bundle). Null for Google / AirMail-only orders.", "example": 20 }, "price_per_domain_per_year": { "type": "number", "description": "The price per domain per year", "example": 100 }, "total_domains_price_per_year": { "type": "number", "description": "The total price per domain per year", "example": 100 }, "total_accounts_price_per_month": { "type": "number", "description": "The total monthly price charged for accounts in the order. For Google / AirMail this is `per-account price × mailbox count`. For Microsoft/Outlook it is `$20 × domain count` (domain-level billing, fixed 50-mailbox bundle).", "example": 10 }, "total_price_per_month": { "type": "number", "description": "The total price per month you will have to pay for the order", "example": 100 }, "total_price_per_year": { "type": "number", "description": "The total price per year you will have to pay for the order", "example": 100 }, "total_price": { "type": "number", "description": "The total price you will have to pay for the order at the moment. This is the sum of the `total_accounts_price_per_month` and the `total_domains_price_per_year` fields.", "example": 100 }, "total_discount": { "type": "number", "description": "The total discount you will get for the order at the moment. Discounts are applied automatically when we're running promotions.", "example": 100 }, "payment_method_last_4_digits": { "type": "string", "description": "The last 4 digits of the payment method used for the order", "example": "1234" }, "payment_method_brand": { "type": "string", "description": "The brand of the payment method used for the order", "example": "Visa" }, "payment_method_name_on_card": { "type": "string", "description": "The name on the card used for the order", "example": "John Doe" }, "simulation": { "type": "boolean", "description": "Whether to run the request in simulation mode or not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).", "example": true }, "order_items": { "type": "array", "description": "The list of items that were ordered, with the pricing information for each item.", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain to use for the email accounts.", "example": "example.com" }, "accounts": { "type": "array", "description": "The list of accounts that were ordered for the domain.", "items": { "type": "object", "properties": { "email_address_prefix": { "type": "string", "description": "The email address prefix of the account.", "example": "john.doe" }, "first_name": { "type": "string", "description": "The account first name.", "example": "John" }, "last_name": { "type": "string", "description": "The account last name.", "example": "Doe" } }, "required": [ "email_address_prefix", "first_name", "last_name" ] } }, "email_provider": { "type": "number", "description": "The mailbox product to order. Defaults to Google when omitted.\n\nOptions:\n- 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "example": 1 }, "forwarding_domain": { "type": "string", "description": "The forwarding domain to use for the domain.", "example": "example.com" }, "domain_price": { "type": "number", "description": "The price for the domain.", "example": 100 }, "accounts_price": { "type": "number", "description": "The total price for the accounts in the item. For Google / AirMail this is `per-account price × mailbox count`. For Microsoft/Outlook it is the flat `$20` per-domain bundle.", "example": 20 }, "domain_monthly_price": { "type": [ "null", "number" ], "description": "The monthly price for the domain bundle. Populated only for providers whose billing is domain-level (Microsoft/Outlook — $20/month/domain, 50 mailboxes). Null for per-account providers.", "example": 20 }, "total_price": { "type": "number", "description": "The total price for the item.", "example": 100 }, "total_discount": { "type": "number", "description": "The total discount for the item.", "example": 100 } }, "required": [ "domain", "accounts", "email_provider", "domain_price", "accounts_price", "total_price", "total_discount" ] } } }, "required": [ "order_placed", "order_is_valid", "unavailable_domains", "blacklist_domains", "invalid_domains", "invalid_forwarding_domains", "invalid_accounts", "missing_domain_orders", "provider_mismatch_domains", "unsupported_provider_domains", "unavailable_email_providers", "domains_without_accounts", "free_domains", "number_of_domains_ordered", "number_of_accounts_ordered", "price_per_account_per_month", "price_per_domain_per_year", "total_domains_price_per_year", "total_accounts_price_per_month", "total_price_per_month", "total_price_per_year", "total_price", "total_discount", "simulation", "order_items", "payment_method_last_4_digits", "payment_method_brand", "payment_method_name_on_card" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listDFYEmailAccountOrder", "summary": "List dfy email account order", "tags": [ "DFYEmailAccountOrder" ], "description": "Requires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." } ], "responses": { "200": { "description": "The list of DFY Email Account Order", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of DFY Email Account Order", "items": { "$ref": "#/components/schemas/def-42" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6220-708f-ba0c-64f5b50adae3" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders/domains/similar": { "post": { "operationId": "generateSimilarDomains", "summary": "Generate similar available domains", "tags": [ "DFYEmailAccountOrder" ], "description": "This endpoint will generate a list of similar AND available domains based on the provided domain.. It will return a maximum number of 66 suggestions per extension (tld) requested.. All the returned domains will be available for order.\n\n\nRequires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain to base the suggestions on", "example": "example.com" }, "tlds": { "type": "array", "description": "The extensions (tlds) to use for generating similar domains. By default, we will use com and org.", "items": { "type": "string", "enum": [ "com", "org" ], "maximum": 2, "x-enumDescriptions": { "com": ".com domain", "org": ".org domain" }, "example": "com" }, "default": [ "com", "org" ] } }, "required": [ "domain" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string", "example": "acme.com" }, "description": "List of similar and available domains" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders/domains/check": { "post": { "operationId": "checkDomainsAvailability", "summary": "Check domains availability", "tags": [ "DFYEmailAccountOrder" ], "description": "This endpoint will check the availability of the provided domains.. It will return a list of domains with their availability status.\n\n. The only supported extensions (tlds) are: .com, .org.\n\n. Please do not abuse this endpoint and do not use it for anything other than checking availability before ordering a domain.. This request has a rate limit of 30 request per minute, or 900 requests per hour.\n\n\nRequires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "description": "List of domains to check", "items": { "type": "string", "example": "example.com" }, "maxItems": 50 } }, "required": [ "domains" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "available": { "type": "boolean", "description": "Whether the domain is available or not", "example": true } } }, "description": "List of domains with their availability status" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders/domains/pre-warmed-up-list": { "post": { "operationId": "preWarmedUpDomainsList", "summary": "Get pre-warmed up domains", "tags": [ "DFYEmailAccountOrder" ], "description": "This endpoint will return a list of pre-warmed up domains available for order.
These domains are set up and configured in advance, allowing for quick deployment of email services.
Use this endpoint to retrieve available pre-warmed up domains before placing an order.

IMPORTANT: if the endpoint returns a list of empty domains - it's not a bug, please don't retry right away or report this as a bug - it simply means that there are no available pre-warmed up domains at the moment.\n\n\nRequires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "extensions": { "type": "array", "description": "A list of domain extensions to filter the results by. If not provided, all available extensions will be returned.", "items": { "type": "string", "enum": [ "com", "org", "co" ], "x-enumDescriptions": { "com": ".com domain", "org": ".org domain", "co": ".co domain" }, "example": "com" }, "default": [ "com", "org", "co" ] }, "search": { "type": "string", "description": "A search string to filter the domains by. This can be a partial or full domain name.", "example": "acme.com" } }, "description": "This endpoint does not require any parameters in the request body." } } }, "description": "This endpoint does not require any parameters in the request body." }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string", "example": "acme.com" }, "description": "List of pre-warmed up domains available for order" }, "domains_with_type": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "example": "acme.com" }, "account_type": { "type": "number", "description": "The mailbox product to order. Defaults to Google when omitted.\n\nOptions:\n- 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "example": 2 } }, "required": [ "domain", "account_type" ] }, "description": "Pre-warmed up domains annotated with their underlying email provider" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders/accounts": { "get": { "operationId": "listDFYEmailAccountOrdersAccounts", "summary": "List DFY ordered email accounts", "tags": [ "DFYEmailAccountOrder" ], "description": "This endpoint will return a list of DFY email accounts ordered\n\n\nRequires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "with_passwords", "required": false, "description": "Whether to include passwords in the response" } ], "responses": { "200": { "description": "The list of accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of accounts", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the email account order", "example": "123e4567-e89b-12d3-a456-426614174000" }, "domain": { "type": "string", "description": "The domain associated with the email account", "example": "example.com" }, "email": { "type": "string", "description": "The email address of the account", "example": "user@example.com" }, "email_provider": { "type": "number", "description": "The mailbox product to order. Defaults to Google when omitted.\n\nOptions:\n- 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "example": 1 }, "first_name": { "type": "string", "description": "The first name of the account", "example": "John" }, "last_name": { "type": "string", "description": "The last name of the account", "example": "Doe" }, "is_pre_warmed_up": { "type": "boolean", "description": "Whether the account is pre-warmed up", "example": true }, "timestamp_cancelled": { "type": "string", "description": "The timestamp when the account was cancelled", "example": "2025-01-01T00:00:00.000Z" }, "timestamp_created": { "type": "string", "description": "The timestamp when the account was created", "example": "2025-01-01T00:00:00.000Z" }, "password": { "type": "string", "description": "The password of the account (returned only if `with_passwords` is true). This field can be empty if the accounts are not ready yet.", "example": "password" } }, "required": [ "id", "domain", "email", "email_provider", "first_name", "last_name", "is_pre_warmed_up", "timestamp_cancelled", "timestamp_created" ] } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "123e4567-e89b-12d3-a456-426614174000:2025-01-01T00:00:00.000Z" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/dfy-email-account-orders/accounts/cancel": { "post": { "operationId": "cancelDFYEmailAccounts", "summary": "Cancel dfy email accounts", "tags": [ "DFYEmailAccountOrder" ], "description": "This endpoint will cancel the DFY email accounts based on the provided email addresses.\n\n\nRequires one of the following scopes: `dfy_email_account_orders:delete`, `dfy_email_account_orders:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "string", "example": "test@test.com" }, "minItems": 1, "description": "List of emails to cancel the DFY email accounts for." } }, "required": [ "accounts" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of cancelled email accounts.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the email account order", "example": "123e4567-e89b-12d3-a456-426614174000" }, "domain": { "type": "string", "description": "The domain associated with the email account", "example": "example.com" }, "email": { "type": "string", "description": "The email address of the account", "example": "user@example.com" }, "email_provider": { "type": "number", "description": "The mailbox product to order. Defaults to Google when omitted.\n\nOptions:\n- 1: Google. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 2: AirMail. Up to 5 mailboxes per domain; priced per mailbox monthly.\n- 3: Microsoft/Outlook. Exactly 50 mailboxes per new DFY domain; priced per domain monthly.", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Google", "2": "AirMail", "3": "Microsoft/Outlook" }, "example": 1 }, "first_name": { "type": "string", "description": "The first name of the account", "example": "John" }, "last_name": { "type": "string", "description": "The last name of the account", "example": "Doe" }, "is_pre_warmed_up": { "type": "boolean", "description": "Whether the account is pre-warmed up", "example": true }, "timestamp_cancelled": { "type": "string", "description": "The timestamp when the account was cancelled", "example": "2025-01-01T00:00:00.000Z" }, "timestamp_created": { "type": "string", "description": "The timestamp when the account was created", "example": "2025-01-01T00:00:00.000Z" } }, "required": [ "id", "domain", "email", "email_provider", "first_name", "last_name", "is_pre_warmed_up", "timestamp_cancelled", "timestamp_created" ] } } }, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/test": { "post": { "operationId": "sendTestEmail", "summary": "Send a test email", "tags": [ "Email" ], "description": "Send a preview/test email without creating an email entity in Unibox. Rate limit: 10 requests per minute per workspace.\n\n\nRequires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eaccount": { "type": "string", "description": "The email account that will be used to send this email. It has to be an email account connected to your workspace.", "example": "jondoe@example.com" }, "to_address_email_list": { "type": "string", "description": "Comma-separated list of recipients that will receive the test email.", "example": "recipient@example.com,recipient2@example.com" }, "subject": { "type": "string", "description": "Subject line of the test email.", "example": "Test email subject" }, "body": { "type": "object", "description": "HTML body of the test email.", "properties": { "html": { "type": "string", "description": "HTML body of the test email.", "example": "

This is a test email

" } }, "required": [ "html" ] } }, "required": [ "eaccount", "to_address_email_list", "subject", "body" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ], "example": "success" } }, "required": [ "status" ] }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "ACC_AUTH_ERROR", "ACC_NOT_FOUND", "ACC_UNKNOWN_ERROR" ], "example": "ACC_AUTH_ERROR" } }, "required": [ "error" ] } ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/reply": { "post": { "operationId": "replyToEmail", "summary": "Reply to an email", "tags": [ "Email" ], "description": "Send a reply to an email. This endpoint can be used to send an email only as a reply to an existing email. In order to reply to an email, please specify the `reyply_to_uuid` field, and your email will be sent as a reply to that email. The `reyply_to_uuid` field represents the `id` field of an existing email, which is being returned to you in all the `/email` endpoints\n\n\nRequires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eaccount": { "type": "string", "description": "The email account that will be used to send this email. It has to be an email account connected to your workspace", "example": "jondoe@example.com" }, "reply_to_uuid": { "type": "string", "description": "The id of the email to reply to", "example": "123e4567-e89b-12d3-a456-426614174000" }, "subject": { "type": "string", "description": "Subject line of the email message", "example": "Re: Your inquiry" }, "body": { "description": "The email body. You can specify either the `html` or the `text` field, or both", "type": "object", "properties": { "html": { "type": "string", "description": "HTML body of the email message", "example": "

Hello, how are you?

" }, "text": { "type": "string", "description": "Text body of the email message", "example": "Hello, how are you?" } } }, "cc_address_email_list": { "type": "string", "description": "Comma-separated list of CC email addresses", "example": "cc@example.com" }, "bcc_address_email_list": { "type": "string", "description": "Comma-separated list of BCC email addresses", "example": "bcc@example.com" }, "reminder_ts": { "type": "string", "format": "date-time", "description": "If provided then a reminder will be attached to this email, you will see this reminder in the Unibox in the web app", "example": "2026-05-09T19:39:21.011Z" }, "assigned_to": { "type": "string", "format": "uuid", "description": "The user id assigned to the lead", "example": "019e0e40-6233-7315-bbb0-ec426b4c733f" } }, "required": [ "reply_to_uuid", "eaccount", "subject", "body" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-2" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/forward": { "post": { "operationId": "forwardEmail", "summary": "Forward an email", "tags": [ "Email" ], "description": "Forward an existing email to another recipient. You must specify the `reply_to_uuid` field, which represents the `id` of an existing email returned by the `/emails` endpoints.\n\n\nRequires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "eaccount": { "type": "string", "description": "The email account that will be used to send this email. It has to be an email account connected to your workspace", "example": "jondoe@example.com" }, "reply_to_uuid": { "type": "string", "description": "The id of the email you want to forward", "example": "123e4567-e89b-12d3-a456-426614174000" }, "to_address_email_list": { "type": "string", "description": "Comma-separated list of recipients that will receive the forwarded email", "example": "recipient@example.com" }, "subject": { "type": "string", "description": "Subject line of the forwarded email message", "example": "Fwd: Interesting update" }, "body": { "description": "The email body. You can specify either the `html` or the `text` field, or both", "type": "object", "properties": { "html": { "type": "string", "description": "HTML body of the email message", "example": "

Sharing this with you.

" }, "text": { "type": "string", "description": "Text body of the email message", "example": "Sharing this with you." } } }, "cc_address_email_list": { "type": "string", "description": "Comma-separated list of CC email addresses", "example": "cc@example.com" }, "bcc_address_email_list": { "type": "string", "description": "Comma-separated list of BCC email addresses", "example": "bcc@example.com" }, "reply_to": { "type": "string", "format": "email", "description": "Reply-to email address that recipients should use when replying", "example": "reply@example.com" }, "forwarded_attachments": { "type": "string", "description": "JSON-encoded forwarded attachment metadata from the original email", "example": "[{\"filename\":\"attachment.pdf\",\"url\":\"https://cdn.instantly.ai/example-attachment/file.pdf\"}]" }, "assigned_to": { "type": "string", "format": "uuid", "description": "The user id assigned to the lead", "example": "019e0e40-6234-75bd-a274-f71e8e2c8ea1" } }, "required": [ "reply_to_uuid", "to_address_email_list", "eaccount", "subject", "body" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-2" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails": { "get": { "operationId": "listEmail", "summary": "List email", "tags": [ "Email" ], "description": "**Rate Limit:** This endpoint has a rate limit of 20 requests per minute, unlike other API endpoints.\n\n\nRequires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "example": "search term" }, "in": "query", "name": "search", "required": false, "description": "The search query to filter emails. It can be an email address (the lead email address), or a special string that starts with \"thread:\" to search for emails in a specific thread. If you want to search for emails in a specific thread, use the \"thread:\" prefix followed by the thread ID (e.g., \"thread:123e4567-e89b-12d3-a456-426614174000\")." }, { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "query", "name": "campaign_id", "required": false, "description": "The ID of the campaign to filter emails by." }, { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "query", "name": "list_id", "required": false, "description": "The ID of the lead list to filter emails by." }, { "schema": { "type": "number", "example": 1 }, "in": "query", "name": "i_status", "required": false, "description": "The status of the emails to filter by." }, { "schema": { "type": "string", "example": "jon@example.com" }, "in": "query", "name": "eaccount", "required": false, "description": "The email account that was used to send this email. You can filter by multiple email accounts by providing a comma-separated list of email addresses." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "is_unread", "required": false, "description": "Whether the email is unread." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "has_reminder", "required": false }, { "schema": { "type": "string", "enum": [ "emode_focused", "emode_others", "emode_all" ], "example": "emode_focused" }, "in": "query", "name": "mode", "required": false, "description": "The mode to filter emails by." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "preview_only", "required": false, "description": "Whether to only return the preview of the emails." }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc" }, "in": "query", "name": "sort_order", "required": false, "description": "The order to sort the emails by (based on the email creation date). Default is \"desc\"." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "scheduled_only", "required": false, "description": "Whether to only return the scheduled emails." }, { "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "query", "name": "assigned_to", "required": false, "description": "The ID of the user to filter emails by." }, { "schema": { "type": "string", "example": "jondoe@example.com" }, "in": "query", "name": "lead", "required": false, "description": "The email of the lead to filter emails by." }, { "schema": { "type": "string", "example": "example.com" }, "in": "query", "name": "company_domain", "required": false, "description": "The domain of the company to filter emails by." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "marked_as_done", "required": false, "description": "Whether the email is marked as done." }, { "schema": { "type": "string", "enum": [ "received", "sent", "manual" ], "example": "received" }, "in": "query", "name": "email_type", "required": false, "description": "The type of the email to filter by." }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.012Z" }, "in": "query", "name": "min_timestamp_created", "required": false, "description": "Filter emails created after this timestamp (ISO format)" }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.012Z" }, "in": "query", "name": "max_timestamp_created", "required": false, "description": "Filter emails created before this timestamp (ISO format)" }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "latest_of_thread", "required": false, "description": "Whether to only return the latest email in each thread." } ], "responses": { "200": { "description": "The list of Email", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Email", "items": { "$ref": "#/components/schemas/def-2" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6234-75bd-a274-f71f3330a47f" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/{id}": { "get": { "operationId": "getEmail", "summary": "Get email", "tags": [ "Email" ], "description": "Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6235-79f7-9efb-03eefa4b6f11" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-2" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchEmail", "summary": "Patch email", "tags": [ "Email" ], "description": "Requires one of the following scopes: `emails:update`, `emails:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_unread": { "type": [ "number", "null" ], "description": "Indicates if the email is unread", "example": 1 }, "reminder_ts": { "type": [ "string", "null" ], "description": "Timestamp for the reminder.", "format": "date-time", "example": "2026-05-09T19:39:06.742Z" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6236-7e01-b540-95f869ac62e5" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-2" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteEmail", "summary": "Delete email", "tags": [ "Email" ], "description": "Requires one of the following scopes: `emails:delete`, `emails:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6237-7a5b-976d-485ce24679c0" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-2" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/unread/count": { "get": { "operationId": "countUnreadEmails", "summary": "Count unread emails", "tags": [ "Email" ], "description": "Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number", "example": 100 } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/emails/threads/{thread_id}/mark-as-read": { "post": { "operationId": "markThreadAsRead", "summary": "Mark all emails in a thread as read", "tags": [ "Email" ], "description": "Requires one of the following scopes: `emails:update`, `emails:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "thread_id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-analytics": { "get": { "operationId": "listInboxPlacementAnalytics", "summary": "List inbox placement analytics", "tags": [ "InboxPlacementAnalytics" ], "description": "Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6262-78db-b407-5f96ee123c8b" }, "in": "query", "name": "test_id", "required": true }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.058Z" }, "in": "query", "name": "date_from", "required": false }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.058Z" }, "in": "query", "name": "date_to", "required": false }, { "schema": { "type": "string", "example": "1,2" }, "in": "query", "name": "recipient_geo", "required": false, "description": "A comma-separated list of recipient geo values." }, { "schema": { "type": "string", "example": "1,2" }, "in": "query", "name": "recipient_type", "required": false, "description": "A comma-separated list of recipient type values." }, { "schema": { "type": "string", "example": "1,2" }, "in": "query", "name": "recipient_esp", "required": false, "description": "A comma-separated list of recipient ESP values." }, { "schema": { "type": "string", "example": "john@doe.com" }, "in": "query", "name": "sender_email", "required": false } ], "responses": { "200": { "description": "The list of Inbox Placement Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Inbox Placement Analytics", "items": { "$ref": "#/components/schemas/def-6" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6262-78db-b407-5f97cb0c6f64" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-analytics/{id}": { "get": { "operationId": "getInboxPlacementAnalytics", "summary": "Get inbox placement analytics", "tags": [ "InboxPlacementAnalytics" ], "description": "Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6264-7036-b295-89aa7187f742" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Inbox Placement Analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-6" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-analytics/stats-by-test-id": { "post": { "operationId": "getInboxPlacementAnalyticsStatsByTestId", "summary": "Retrieve inbox placement analytics stats by test id", "tags": [ "InboxPlacementAnalytics" ], "description": "Provides aggregated inbox, spam and category counts for specified test IDs\n\n\nRequires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "test_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-6265-731e-9803-ee8917a501a5" }, "minItems": 1 }, "date_from": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "date_to": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "recipient_geo": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "United States", "2": "Italy", "3": "Germany", "4": "France" }, "example": 1 }, "example": [ 1 ] }, "recipient_type": { "type": "array", "items": { "type": "number", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Professional", "2": "Personal" }, "example": 1 }, "example": [ 1 ] }, "recipient_esp": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "example": [ 1, 2 ] }, "sender_email": { "type": "string", "example": "john@doe.com" } }, "required": [ "test_ids" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "test_id": { "type": "string", "format": "uuid", "example": "019e0e40-6265-731e-9803-ee8a9af756f4" }, "count": { "type": "number", "example": 1 }, "spam_count": { "type": "number", "example": 1 }, "spam_percent": { "type": "number", "example": 1 }, "inbox_count": { "type": "number", "example": 1 }, "inbox_percent": { "type": "number", "example": 1 }, "category_count": { "type": "number", "example": 1 }, "category_percent": { "type": "number", "example": 1 } }, "required": [ "test_id", "count", "spam_count", "spam_percent", "inbox_count", "inbox_percent", "category_count", "category_percent" ] } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-analytics/deliverability-insights": { "post": { "operationId": "getInboxPlacementAnalyticsDeliverabilityInsights", "summary": "Retrieve inbox placement analytics deliverability insights", "tags": [ "InboxPlacementAnalytics" ], "description": "Provides deliverability insights for a specific inbox placement test\n\n\nRequires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "test_id": { "type": "string", "format": "uuid", "example": "019e0e40-6265-731e-9803-ee8bdac525c2" }, "date_from": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "date_to": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "previous_date_from": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "previous_date_to": { "type": "string", "example": "2026-05-09T19:39:21.061Z" }, "show_previous": { "type": "boolean", "example": true }, "recipient_geo": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "United States", "2": "Italy", "3": "Germany", "4": "France" }, "example": 1 }, "example": [ 1 ] }, "recipient_type": { "type": "array", "items": { "type": "number", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Professional", "2": "Personal" }, "example": 1 }, "example": [ 1 ] }, "recipient_esp": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "example": [ 1, 2 ] } }, "required": [ "test_id" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "test_id": { "type": "string", "format": "uuid", "example": "019e0e40-6265-731e-9803-ee8c07a25068" }, "from": { "type": [ "null", "string" ], "example": "2024-01-01" }, "to": { "type": [ "null", "string" ], "example": "2024-01-01" }, "previous_from": { "type": [ "null", "string" ], "example": "2023-01-01" }, "previous_to": { "type": [ "null", "string" ], "example": "2023-01-01" }, "sender_esp": { "type": "number", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "recipient_esp": { "type": "number", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "spam_percentage": { "type": [ "null", "number" ], "example": 10 }, "inbox_percentage": { "type": [ "null", "number" ], "example": 20 }, "category_percentage": { "type": [ "null", "number" ], "example": 70 }, "prev_spam_percentage": { "type": [ "null", "number" ], "example": 10 }, "prev_inbox_percentage": { "type": [ "null", "number" ], "example": 56.67 }, "prev_category_percentage": { "type": [ "null", "number" ], "example": 33.33 } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-analytics/stats-by-date": { "post": { "operationId": "getInboxPlacementAnalyticsStatsByDate", "summary": "Get inbox placement analytics stats by date", "tags": [ "InboxPlacementAnalytics" ], "description": "Provides a time series representing the distribution of emails sent to inbox, spam, or category folders for scheduled inbox placement tests.\n\n\nRequires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "test_id": { "type": "string", "format": "uuid", "example": "019e0e40-6266-7638-b77d-35e9c12a873a" }, "date_from": { "type": "string", "example": "2026-05-09T19:39:21.062Z" }, "date_to": { "type": "string", "example": "2026-05-09T19:39:21.062Z" }, "recipient_geo": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "United States", "2": "Italy", "3": "Germany", "4": "France" }, "example": 1 }, "example": [ 1 ] }, "recipient_type": { "type": "array", "items": { "type": "number", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Professional", "2": "Personal" }, "example": 1 }, "example": [ 1 ] }, "recipient_esp": { "type": "array", "items": { "type": "number", "enum": [ 1, 2, 12, 13 ], "x-enumDescriptions": { "1": "Google", "2": "Microsoft", "12": "Web.de", "13": "Libero.it" }, "example": 1 }, "example": [ 1, 2 ] }, "sender_email": { "type": "string", "example": "john@doe.com" } }, "required": [ "test_id" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "timestamp_created_date": { "type": "string", "example": "2026-05-09T19:39:21.062Z" }, "sent_count": { "type": "number", "example": 1 }, "received_count": { "type": "number", "example": 1 }, "spam_count": { "type": "number", "example": 1 }, "inbox_count": { "type": "number", "example": 1 }, "category_count": { "type": "number", "example": 1 } }, "required": [ "timestamp_created_date", "sent_count", "received_count", "spam_count", "inbox_count", "category_count" ] } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-reports": { "get": { "operationId": "listInboxPlacementBlacklist&SpamAssassinReport", "summary": "List inbox placement blacklist & spamassassin report", "tags": [ "InboxPlacementBlacklist&SpamAssassinReport" ], "description": "Requires one of the following scopes: `inbox_placement_reports:read`, `inbox_placement_reports:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "format": "uuid", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" }, "in": "query", "name": "test_id", "required": true }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.073Z" }, "in": "query", "name": "date_from", "required": false }, { "schema": { "type": "string", "example": "2026-05-09T19:39:21.073Z" }, "in": "query", "name": "date_to", "required": false }, { "schema": { "type": "boolean", "example": false }, "in": "query", "name": "skip_spam_assassin_report", "required": false, "description": "Flag to skip including spam_assassin_report JSON" }, { "schema": { "type": "boolean", "example": false }, "in": "query", "name": "skip_blacklist_report", "required": false, "description": "Flag to skip including blacklist_report JSON" } ], "responses": { "200": { "description": "The list of Inbox Placement Blacklist & SpamAssassin Report", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Inbox Placement Blacklist & SpamAssassin Report", "items": { "$ref": "#/components/schemas/def-7" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6271-743c-bef8-0e287dae1dc3" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-reports/{id}": { "get": { "operationId": "getInboxPlacementBlacklist&SpamAssassinReport", "summary": "Get inbox placement blacklist & spamassassin report", "tags": [ "InboxPlacementBlacklist&SpamAssassinReport" ], "description": "Requires one of the following scopes: `inbox_placement_reports:read`, `inbox_placement_reports:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6273-7895-b2f9-d13ddbadfa15" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Inbox Placement Blacklist & SpamAssassin Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-7" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-tests": { "post": { "operationId": "createInboxPlacementTest", "summary": "Create inbox placement test", "tags": [ "InboxPlacementTest" ], "description": "Requires one of the following scopes: `inbox_placement_tests:create`, `inbox_placement_tests:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateInbox Placement Test", "description": "The Inbox Placement Test to create", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the inbox placement test", "example": "My Inbox Placement Test" }, "delivery_mode": { "type": [ "null", "number" ], "description": "Whether to send emails one by one or all together", "enum": [ 1, 2, null ], "x-enumDescriptions": { "1": "One by one", "2": "All together" }, "example": 1 }, "description": { "type": [ "string", "null" ], "description": "Description of the inbox placement test", "example": "This is a test description" }, "schedule": { "type": "object", "description": "Specifies the date and time when the automated inbox placement tests will be sent.", "properties": { "days": { "type": "object", "description": "Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days.", "additionalProperties": { "type": "boolean", "example": false }, "example": { "0": false, "1": false, "2": true, "3": true, "4": false, "5": false, "6": false } }, "timing": { "type": "object", "properties": { "from": { "type": "string", "description": "The time of day when the test will start (24-hour format).", "example": "02:30" } }, "description": "Timing configuration for the scheduled test." }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "description": "Timezone in which the schedule is set, in IANA timezone format.", "example": "Etc/GMT+12" } } }, "type": { "type": "number", "description": "Whether the inbox placement test is a one-time test or an automated test", "enum": [ 1, 2 ], "example": 1 }, "sending_method": { "type": "number", "description": "Whether the inbox placement test will be sent from Instantly or from outside Instantly", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "From Instantly", "2": "From Outside Instantly" }, "example": 1 }, "campaign_id": { "type": [ "null", "string" ], "description": "Campaign ID", "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e516e732f9" }, "email_subject": { "type": "string", "description": "Email subject of the inbox placement test", "example": "My Email Subject" }, "email_body": { "type": "string", "description": "Email body of the inbox placement test", "example": "Hi, this is my email body" }, "emails": { "type": "array", "description": "Emails to send the inbox placement test to", "items": { "type": "string", "example": "john@doe.com" } }, "test_code": { "type": [ "string", "null" ], "description": "Code for identifying the inbox placement tests in the email body from outside Instantly", "example": "ptid_9YWg_TkNb-pz-paVrQr07" }, "tags": { "type": [ "array", "null" ], "description": "List of tag IDs to use for sending emails", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e6e488a607" } }, "text_only": { "type": [ "boolean", "null" ], "description": "Disables open tracking", "example": true }, "recipients_labels": { "type": "array", "description": "A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the `GET: /inbox-placement-tests/email-service-provider-options` endpoint", "items": { "type": "object", "properties": { "region": { "type": "string", "description": "The region to send emails to", "example": "North America" }, "sub_region": { "type": "string", "description": "The sub-region to send emails to", "example": "US" }, "type": { "type": "string", "description": "The type of email to send", "example": "Professional" }, "esp": { "type": "string", "description": "The Email Service Provider (ESP) to send emails to", "example": "Google" } }, "required": [ "region", "sub_region", "type", "esp" ] } }, "timestamp_next_run": { "type": [ "string", "null" ], "description": "Timestamp when the inbox placement test will run next", "example": "2026-05-09T19:39:06.665Z" }, "automations": { "type": [ "null", "array" ], "description": "Optional automations to trigger based on conditions", "minItems": 0, "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "condition": { "type": "string", "description": "Condition for automation trigger", "enum": [ "placement_goes_below", "placement_goes_above", "added_to_blacklists", "removed_from_blacklists" ], "example": "placement_goes_below" }, "condition_value": { "type": [ "null", "number" ], "description": "Value for condition, if applicable", "example": 80 } }, "required": [ "condition" ] }, "then": { "type": "object", "properties": { "webhook_url": { "type": "string", "example": "https://example.com/webhook" }, "pause_sending_campaigns_for": { "type": "number", "description": "Number of days to pause sending campaigns for", "example": 14 }, "pause": { "type": "boolean", "example": true }, "enable_slow_ramp": { "type": "boolean", "example": true }, "disable_slow_ramp": { "type": "boolean", "example": true }, "add_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bb1404084c" }, "example": [ "019e0e40-2a2a-7b5f-baa1-75bcf5869f13" ] }, "remove_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bd0cec1c31" } } }, "minProperties": 1, "description": "Actions to take when condition is met" } }, "required": [ "when", "then" ] } }, "status": { "type": [ "number", "null" ], "description": "Status of the inbox placement test", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed" }, "example": 1 }, "not_sending_status": { "type": [ "string", "null" ], "description": "Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.", "enum": [ "daily_limits_hit", "other" ], "x-enumDescriptions": { "daily_limits_hit": "Daily limits hit", "other": "Other reason" }, "example": "daily_limits_hit" }, "run_immediately": { "type": "boolean", "description": "Run the test immediately after creation, as well as on the schedule", "example": true } }, "required": [ "name", "type", "sending_method", "email_subject", "email_body", "emails" ], "additionalProperties": false } } }, "required": true, "description": "The Inbox Placement Test to create" }, "responses": { "200": { "description": "The Inbox Placement Test", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-5" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listInboxPlacementTest", "summary": "List inbox placement test", "tags": [ "InboxPlacementTest" ], "description": "Requires one of the following scopes: `inbox_placement_tests:read`, `inbox_placement_tests:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "example": "test" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "number", "enum": [ 1, 2, 3 ], "example": 1 }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "example": "desc" }, "in": "query", "name": "sort_order", "required": false, "description": "Sort order for the results. Results are always sorted by id (which is timestamp-sorted due to UUIDv7)." } ], "responses": { "200": { "description": "The list of Inbox Placement Test", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Inbox Placement Test", "items": { "$ref": "#/components/schemas/def-5" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6280-7415-b9cf-fa408f89fc01" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-tests/{id}": { "get": { "operationId": "getInboxPlacementTest", "summary": "Get inbox placement test", "tags": [ "InboxPlacementTest" ], "description": "Requires one of the following scopes: `inbox_placement_tests:read`, `inbox_placement_tests:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "with_metadata", "required": false, "description": "Whether to include additional metadata about the inbox placement test" }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6281-7905-aadf-6166132e52dd" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Inbox Placement Test", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "description": "Unique identifier for the inbox placement test", "readOnly": true, "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e3baff63a4" }, "organization_id": { "type": "string", "description": "Organization ID", "readOnly": true, "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e4f68637aa" }, "name": { "type": "string", "description": "Name of the inbox placement test", "example": "My Inbox Placement Test" }, "delivery_mode": { "type": [ "null", "number" ], "description": "Whether to send emails one by one or all together", "enum": [ 1, 2, null ], "x-enumDescriptions": { "1": "One by one", "2": "All together" }, "example": 1 }, "description": { "type": [ "null", "string" ], "description": "Description of the inbox placement test", "example": "This is a test description" }, "schedule": { "type": "object", "description": "Specifies the date and time when the automated inbox placement tests will be sent.", "properties": { "days": { "type": "object", "description": "Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days.", "additionalProperties": { "type": "boolean", "example": false }, "example": { "0": false, "1": false, "2": true, "3": true, "4": false, "5": false, "6": false } }, "timing": { "type": "object", "properties": { "from": { "type": "string", "description": "The time of day when the test will start (24-hour format).", "example": "02:30" } }, "description": "Timing configuration for the scheduled test." }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "description": "Timezone in which the schedule is set, in IANA timezone format.", "example": "Etc/GMT+12" } } }, "type": { "type": "number", "description": "Whether the inbox placement test is a one-time test or an automated test", "enum": [ 1, 2 ], "example": 1 }, "sending_method": { "type": "number", "description": "Whether the inbox placement test will be sent from Instantly or from outside Instantly", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "From Instantly", "2": "From Outside Instantly" }, "example": 1 }, "campaign_id": { "type": [ "null", "string" ], "description": "Campaign ID", "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e516e732f9" }, "email_subject": { "type": "string", "description": "Email subject of the inbox placement test", "example": "My Email Subject" }, "email_body": { "type": "string", "description": "Email body of the inbox placement test", "example": "Hi, this is my email body" }, "emails": { "type": "array", "description": "Emails to send the inbox placement test to", "items": { "type": "string", "example": "john@doe.com" } }, "test_code": { "type": [ "null", "string" ], "description": "Code for identifying the inbox placement tests in the email body from outside Instantly", "example": "ptid_9YWg_TkNb-pz-paVrQr07" }, "tags": { "type": [ "null", "array" ], "description": "List of tag IDs to use for sending emails", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a29-76cc-8980-b9e6e488a607" } }, "text_only": { "type": [ "null", "boolean" ], "description": "Disables open tracking", "example": true }, "recipients": { "type": "array", "readOnly": true, "items": { "type": "string", "example": "johndoe@instantly.ai" } }, "recipients_labels": { "type": "array", "description": "A list of email providers and their corresponding types to which emails will be sent. To retrieve the available options, use the `GET: /inbox-placement-tests/email-service-provider-options` endpoint", "items": { "type": "object", "properties": { "region": { "type": "string", "description": "The region to send emails to", "example": "North America" }, "sub_region": { "type": "string", "description": "The sub-region to send emails to", "example": "US" }, "type": { "type": "string", "description": "The type of email to send", "example": "Professional" }, "esp": { "type": "string", "description": "The Email Service Provider (ESP) to send emails to", "example": "Google" } }, "required": [ "region", "sub_region", "type", "esp" ] } }, "timestamp_created": { "type": "string", "description": "Timestamp when the inbox placement test was created", "readOnly": true, "example": "2026-05-09T19:39:06.665Z" }, "timestamp_next_run": { "type": [ "null", "string" ], "description": "Timestamp when the inbox placement test will run next", "example": "2026-05-09T19:39:06.665Z" }, "automations": { "type": [ "null", "array" ], "description": "Optional automations to trigger based on conditions", "minItems": 0, "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "condition": { "type": "string", "description": "Condition for automation trigger", "enum": [ "placement_goes_below", "placement_goes_above", "added_to_blacklists", "removed_from_blacklists" ], "example": "placement_goes_below" }, "condition_value": { "type": [ "null", "number" ], "description": "Value for condition, if applicable", "example": 80 } }, "required": [ "condition" ] }, "then": { "type": "object", "properties": { "webhook_url": { "type": "string", "example": "https://example.com/webhook" }, "pause_sending_campaigns_for": { "type": "number", "description": "Number of days to pause sending campaigns for", "example": 14 }, "pause": { "type": "boolean", "example": true }, "enable_slow_ramp": { "type": "boolean", "example": true }, "disable_slow_ramp": { "type": "boolean", "example": true }, "add_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bb1404084c" }, "example": [ "019e0e40-2a2a-7b5f-baa1-75bcf5869f13" ] }, "remove_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bd0cec1c31" } } }, "minProperties": 1, "description": "Actions to take when condition is met" } }, "required": [ "when", "then" ] } }, "status": { "type": [ "null", "number" ], "description": "Status of the inbox placement test", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed" }, "example": 1 }, "not_sending_status": { "type": [ "null", "string" ], "description": "Why the inbox placement test is currently not sending. It will be an empty string if there are no issues.", "enum": [ "daily_limits_hit", "other" ], "x-enumDescriptions": { "daily_limits_hit": "Daily limits hit", "other": "Other reason" }, "example": "daily_limits_hit" }, "metadata": { "type": "object", "description": "Included only when the `with_metadata` parameter is `true`. Contains additional information about the inbox placement test as associated campaign details and tags.", "properties": { "campaign": { "description": "The campaign associated with the inbox placement test", "type": "object", "properties": { "id": { "type": "string", "example": "campaign-id" }, "name": { "type": "string", "example": "Campaign Name" } } }, "tags": { "type": "object", "description": "The tags associated with the inbox placement test", "additionalProperties": { "type": "object", "properties": { "id": { "type": "string", "example": "tag-id" }, "label": { "type": "string", "example": "Tag Label" } }, "required": [ "id", "label" ] } } }, "example": { "campaign": { "id": "campaign-id", "name": "Campaign Name" }, "tags": { "tag-id": { "id": "tag-id", "label": "Tag Label" } } } } }, "type": "object" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteInboxPlacementTest", "summary": "Delete inbox placement test", "tags": [ "InboxPlacementTest" ], "description": "Requires one of the following scopes: `inbox_placement_tests:delete`, `inbox_placement_tests:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6283-701e-8eb1-9cf3310d2ef7" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Inbox Placement Test", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-5" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchInboxPlacementTest", "summary": "Patch inbox placement test", "tags": [ "InboxPlacementTest" ], "description": "Requires one of the following scopes: `inbox_placement_tests:update`, `inbox_placement_tests:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the inbox placement test", "example": "My Inbox Placement Test" }, "schedule": { "type": "object", "description": "Specifies the date and time when the automated inbox placement tests will be sent.", "properties": { "days": { "type": "object", "description": "Days of the week when the test will run, where keys are integers (0-6, 0 = Sunday) and values are booleans indicating active days.", "additionalProperties": { "type": "boolean", "example": false }, "example": { "0": false, "1": false, "2": true, "3": true, "4": false, "5": false, "6": false } }, "timing": { "type": "object", "properties": { "from": { "type": "string", "description": "The time of day when the test will start (24-hour format).", "example": "02:30" } }, "description": "Timing configuration for the scheduled test." }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "description": "Timezone in which the schedule is set, in IANA timezone format.", "example": "Etc/GMT+12" } } }, "automations": { "type": [ "null", "array" ], "description": "Optional automations to trigger based on conditions", "minItems": 0, "items": { "type": "object", "properties": { "when": { "type": "object", "properties": { "condition": { "type": "string", "description": "Condition for automation trigger", "enum": [ "placement_goes_below", "placement_goes_above", "added_to_blacklists", "removed_from_blacklists" ], "example": "placement_goes_below" }, "condition_value": { "type": [ "null", "number" ], "description": "Value for condition, if applicable", "example": 80 } }, "required": [ "condition" ] }, "then": { "type": "object", "properties": { "webhook_url": { "type": "string", "example": "https://example.com/webhook" }, "pause_sending_campaigns_for": { "type": "number", "description": "Number of days to pause sending campaigns for", "example": 14 }, "pause": { "type": "boolean", "example": true }, "enable_slow_ramp": { "type": "boolean", "example": true }, "disable_slow_ramp": { "type": "boolean", "example": true }, "add_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bb1404084c" }, "example": [ "019e0e40-2a2a-7b5f-baa1-75bcf5869f13" ] }, "remove_tags": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-2a2a-7b5f-baa1-75bd0cec1c31" } } }, "minProperties": 1, "description": "Actions to take when condition is met" } }, "required": [ "when", "then" ] } }, "status": { "type": [ "number", "null" ], "description": "Status of the inbox placement test", "enum": [ 1, 2, 3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed" }, "example": 1 } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6284-7f0d-a3d6-b8e9b9d769a0" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Inbox Placement Test", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-5" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/inbox-placement-tests/email-service-provider-options": { "get": { "operationId": "getInboxPlacementTestESPOptions", "summary": "Get ESP options", "tags": [ "InboxPlacementTest" ], "description": "Provides a list of available email service providers for inbox placement tests.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "region": { "type": "string", "example": "North America" }, "sub_region": { "type": "string", "example": "US" }, "type": { "type": "string", "example": "Professional" }, "esp": { "type": "string", "example": "Google" } }, "required": [ "region", "sub_region", "type", "esp" ] } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/lead-labels": { "post": { "operationId": "createLeadLabel", "summary": "Create lead label", "tags": [ "LeadLabel" ], "description": "Requires one of the following scopes: `lead-labels:create`, `lead-labels:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateLead Label", "description": "The Lead Label to create", "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the custom lead label", "example": "Hot Lead" }, "interest_status_label": { "type": "string", "description": "Interest status label associated with this label", "enum": [ "positive", "negative", "neutral" ], "x-enumDescriptions": { "positive": "Positive", "negative": "Negative", "neutral": "Neutral" }, "example": "positive" }, "description": { "type": [ "string", "null" ], "description": "Detailed description of the custom lead label purpose", "example": "Used for marking high-priority leads" }, "use_with_ai": { "type": [ "boolean", "null" ], "description": "Whether this label should be used with AI features", "example": false } }, "required": [ "label", "interest_status_label" ], "additionalProperties": false } } }, "required": true, "description": "The Lead Label to create" }, "responses": { "200": { "description": "The Lead Label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-16" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listLeadLabel", "summary": "List lead label", "tags": [ "LeadLabel" ], "description": "Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "2025-03-07T00:00:00.000Z" }, "in": "query", "name": "starting_after", "required": false, "description": "The starting after timestamp to filter lead labels by." }, { "schema": { "type": "string", "example": "Hot Lead" }, "in": "query", "name": "search", "required": false, "description": "The search query to filter lead labels." }, { "schema": { "type": "string", "enum": [ "positive", "neutral", "negative" ], "example": "positive" }, "in": "query", "name": "interest_status", "required": false, "description": "The interest status to filter lead labels by." } ], "responses": { "200": { "description": "The list of Lead Label", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Lead Label", "items": { "$ref": "#/components/schemas/def-16" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6290-7f69-8e76-85288fe961fe" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/lead-labels/{id}": { "get": { "operationId": "getLeadLabel", "summary": "Get lead label", "tags": [ "LeadLabel" ], "description": "Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6291-7118-af1d-bf97714ef90c" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Lead Label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-16" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchLeadLabel", "summary": "Patch lead label", "tags": [ "LeadLabel" ], "description": "Requires one of the following scopes: `lead-labels:update`, `lead-labels:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label for the custom lead label", "example": "Hot Lead" }, "interest_status_label": { "type": "string", "description": "Interest status label associated with this label", "enum": [ "positive", "negative", "neutral" ], "x-enumDescriptions": { "positive": "Positive", "negative": "Negative", "neutral": "Neutral" }, "example": "positive" }, "description": { "type": [ "string", "null" ], "description": "Detailed description of the custom lead label purpose", "example": "Used for marking high-priority leads" }, "use_with_ai": { "type": [ "boolean", "null" ], "description": "Whether this label should be used with AI features", "example": false } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6291-7118-af1d-bf98b45cfeb7" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Lead Label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-16" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteLeadLabel", "summary": "Delete lead label", "tags": [ "LeadLabel" ], "description": "Requires one of the following scopes: `lead-labels:delete`, `lead-labels:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "properties": { "reassigned_status": { "type": "number", "description": "The interest status to reassign leads and emails to.", "example": 1 } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6292-798c-ae85-e582f60873e4" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Lead Label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-16" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/lead-labels/ai-reply-label": { "post": { "operationId": "testAiReplyLabelLeadLabels", "summary": "Test AI reply label prediction", "tags": [ "LeadLabel" ], "description": "Returns the AI-predicted lead label for a reply text. This simulates how AI auto-tagging would label an incoming reply for testing custom labels and descriptions. Rate limit: 500 requests per 30 days per workspace. This rate limit applies only to this testing endpoint; live reply processing does not use this limiter.\n\n\nRequires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reply_text": { "type": "string", "description": "The reply text to classify.", "example": "Thanks for reaching out. I am interested in learning more." } }, "required": [ "reply_text" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "description": "The predicted lead label.", "example": "Hot Lead" }, "custom_labels_considered": { "type": "array", "items": { "type": "string", "example": "Hot Lead" }, "description": "AI-enabled custom labels considered during classification.", "example": [ "Hot Lead", "Needs Follow-up" ] } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded" } } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Classification failed" } } } } } } } } }, "/api/v2/lead-lists": { "post": { "operationId": "createLeadList", "summary": "Create lead list", "tags": [ "LeadList" ], "description": "Requires one of the following scopes: `lead_lists:create`, `lead_lists:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateLead List", "description": "The Lead List to create", "type": "object", "properties": { "has_enrichment_task": { "type": [ "boolean", "null" ], "description": "Whether this list runs the enrichment process on every added lead or not", "example": false }, "owned_by": { "type": [ "string", "null" ], "description": "User ID of the owner of this lead list. Defaults to the user that created the list", "format": "uuid", "example": "019e0e40-2a37-7997-8b57-0782a116aef9" }, "name": { "type": "string", "description": "Name of the lead list", "example": "My Lead List" } }, "required": [ "name" ], "additionalProperties": false } } }, "required": true, "description": "The Lead List to create" }, "responses": { "200": { "description": "The Lead List", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listLeadList", "summary": "List lead list", "tags": [ "LeadList" ], "description": "Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "2025-03-07T00:00:00.000Z" }, "in": "query", "name": "starting_after", "required": false, "description": "The starting after timestamp to filter lead lists by." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "has_enrichment_task", "required": false, "description": "Whether the list has an enrichment task." }, { "schema": { "type": "string", "example": "Summer 2025 List" }, "in": "query", "name": "search", "required": false, "description": "The search query to filter lead lists by." } ], "responses": { "200": { "description": "The list of Lead List", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Lead List", "items": { "$ref": "#/components/schemas/def-4" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-629e-7eae-aa5a-a5f5d719833d" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/lead-lists/{id}": { "get": { "operationId": "getLeadList", "summary": "Get lead list", "tags": [ "LeadList" ], "description": "Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-629f-77bc-9639-e802e7d58b67" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Lead List", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchLeadList", "summary": "Patch lead list", "tags": [ "LeadList" ], "description": "Requires one of the following scopes: `lead_lists:update`, `lead_lists:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "has_enrichment_task": { "type": [ "boolean", "null" ], "description": "Whether this list runs the enrichment process on every added lead or not", "example": false }, "owned_by": { "type": [ "string", "null" ], "description": "User ID of the owner of this lead list. Defaults to the user that created the list", "format": "uuid", "example": "019e0e40-2a37-7997-8b57-0782a116aef9" }, "name": { "type": "string", "description": "Name of the lead list", "example": "My Lead List" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62a0-78db-8d32-8a0fd7ae5de0" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Lead List", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteLeadList", "summary": "Delete lead list", "tags": [ "LeadList" ], "description": "Requires one of the following scopes: `lead_lists:delete`, `lead_lists:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62a1-7430-bd34-e75036dcf168" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Lead List", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/lead-lists/{id}/verification-stats": { "get": { "operationId": "getVerificationStats", "summary": "Get verification statistics for a lead list", "tags": [ "LeadList" ], "description": "Get verification statistics for a lead list", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62a2-73e7-a749-d9944079a038" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "verified": { "type": "number", "description": "Count of verified leads", "example": 150 }, "invalid": { "type": "number", "description": "Count of invalid leads", "example": 25 }, "risky": { "type": "number", "description": "Count of risky leads", "example": 10 }, "catch_all": { "type": "number", "description": "Count of catch all leads", "example": 5 }, "job_change": { "type": "number", "description": "Count of job change leads", "example": 2 }, "verification_job_pending_leadfinder": { "type": "number", "description": "Count of verification job pending leads for leadfinder", "example": 11 }, "verification_job_pending_user": { "type": "number", "description": "Count of verification job pending leads for user", "example": 12 } }, "description": "Sums up the leads by their verification status", "example": { "verified": 150, "invalid": 25, "risky": 10, "catch_all": 5, "job_change": 2, "verification_job_pending_leadfinder": 11, "verification_job_pending_user": 12 } }, "total_leads": { "type": "number", "description": "Total number of leads in the list", "example": 203 } }, "required": [ "stats", "total_leads" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads": { "post": { "operationId": "createLead", "summary": "Create lead", "tags": [ "Lead" ], "description": "Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateLead", "description": "When using `campaign`: The `email` field is required. When using `list_id`: The `email` field is optional, but at least one of the following must be provided: `email`, `first_name`, or `last_name`.", "type": "object", "properties": { "campaign": { "type": [ "string", "null" ], "description": "Campaign ID associated with the lead", "format": "uuid", "example": "019e0e40-12e1-78c6-856f-979aa2c7fd88" }, "email": { "type": [ "string", "null" ], "description": "Email address of the lead", "example": "example@example.com" }, "personalization": { "type": [ "string", "null" ], "description": "Personalization of the lead", "example": "Hello, how are you?" }, "website": { "type": [ "string", "null" ], "description": "Website of the lead", "example": "https://example.com" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the lead", "example": "Doe" }, "first_name": { "type": [ "string", "null" ], "description": "First name of the lead", "example": "John" }, "company_name": { "type": [ "string", "null" ], "description": "Company name of the lead", "example": "Example Inc." }, "job_title": { "type": [ "string", "null" ], "description": "Job title of the lead", "example": "Head of Growth" }, "phone": { "type": [ "string", "null" ], "description": "Phone number of the lead", "example": "+1234567890" }, "lt_interest_status": { "type": "number", "description": "Lead interest status. It can be either a static value (check below), or a custom status interest value", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 }, "pl_value_lead": { "type": [ "string", "null" ], "description": "Potential value of the lead", "example": "High" }, "list_id": { "type": [ "string", "null" ], "description": "List ID associated with the lead", "format": "uuid", "example": "019e0e40-12e1-78c6-856f-979f36881d5f" }, "assigned_to": { "type": [ "string", "null" ], "description": "ID of the user assigned to the lead", "format": "uuid", "example": "019e0e40-12e2-7a51-bfcc-4d94276e4b3a" }, "skip_if_in_workspace": { "type": "boolean", "description": "Whether to skip if the lead is already in the workspace.", "example": true }, "skip_if_in_campaign": { "type": "boolean", "description": "Whether to skip if the lead is already in the campaign.", "example": true }, "skip_if_in_list": { "type": "boolean", "description": "Whether to skip if the lead is already in the list.", "example": true }, "blocklist_id": { "type": "string", "format": "uuid", "description": "The ID of the blocklist to check for the lead.", "example": "019e0e40-62bb-7fdf-9cf9-32c41f79469b" }, "verify_leads_for_lead_finder": { "type": "boolean", "description": "Whether to verify the leads for the lead finder.", "example": true }, "verify_leads_on_import": { "type": "boolean", "description": "Whether to verify the leads on import.", "example": true }, "custom_variables": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field", "example": { "past_customer": true, "has_tried_competitors": false } } }, "required": [], "additionalProperties": false } } }, "description": "When using `campaign`: The `email` field is required. When using `list_id`: The `email` field is optional, but at least one of the following must be provided: `email`, `first_name`, or `last_name`." }, "responses": { "200": { "description": "The Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "bulkDeleteLeads", "summary": "Delete leads in bulk", "tags": [ "Lead" ], "description": "Delete multiple leads from a campaign or list based on filters. You must provide either `campaign_id` or `list_id`. Optionally filter by status or specific IDs.\n\n\nRequires one of the following scopes: `leads:delete`, `leads:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "description": "The ID of the campaign to delete leads from. Required if `list_id` is not provided.", "example": "019e0e40-62c3-7101-bf3c-b1e2843ccb36" }, "list_id": { "type": "string", "format": "uuid", "description": "The ID of the list to delete leads from. Required if `campaign_id` is not provided.", "example": "019e0e40-62c3-7101-bf3c-b1e378271333" }, "status": { "type": "number", "enum": [ 1, 2, 3, -1, -2, -3 ], "x-enumDescriptions": { "1": "Active", "2": "Paused", "3": "Completed", "-1": "Bounced", "-2": "Unsubscribed", "-3": "Skipped" }, "description": "Optional status filter. Only delete leads with this status.", "example": 3 }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-62c3-7101-bf3c-b1e4aecba61e" }, "description": "Optional array of specific lead IDs to delete. When provided, only these leads will be deleted from the specified campaign or list." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of leads to delete. If not specified, all matching leads will be deleted.", "example": 100 } }, "anyOf": [ { "required": [ "campaign_id" ] }, { "required": [ "list_id" ] } ] } } } }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "Number of leads successfully deleted.", "example": 5 } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/list": { "post": { "operationId": "listLeads", "summary": "List leads", "tags": [ "Lead" ], "description": "This endpoint is a POST endpoint, instead of GET - a deviation from the REST APIs standards we’re following because of the complex arguments it accepts, which would be too hard to express through query parameters. Results are ordered by each lead's `id` field in ascending order (or by `contact` when distinct_contacts is true) so clients can paginate chronologically by reusing the cursor returned in `next_starting_after`. Leads created on or after October 15, 2025 respect this chronological ordering; older records may appear out of sequence when sorted by ID.\n\n\nRequires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "description": "A search string to search the leads against - can be First Name, Last Name, or Email", "example": "John Doe" }, "filter": { "type": "string", "x-enumDescriptions": { "FILTER_VAL_CONTACTED": "Filter for contacted leads", "FILTER_VAL_NOT_CONTACTED": "Filter for not contacted leads", "FILTER_VAL_COMPLETED": "Filter for completed leads", "FILTER_VAL_UNSUBSCRIBED": "Filter for unsubscribed leads", "FILTER_VAL_ACTIVE": "Filter for active leads", "FILTER_LEAD_INTERESTED": "Filter for interested leads", "FILTER_LEAD_NOT_INTERESTED": "Filter for not interested leads", "FILTER_LEAD_MEETING_BOOKED": "Filter for leads with meeting booked", "FILTER_LEAD_MEETING_COMPLETED": "Filter for leads with meeting completed", "FILTER_LEAD_CLOSED": "Filter for closed leads", "FILTER_LEAD_OUT_OF_OFFICE": "Filter for leads out of office", "FILTER_LEAD_WRONG_PERSON": "Filter for wrong person leads", "FILTER_LEAD_LOST": "Filter for lost leads", "FILTER_LEAD_NO_SHOW": "Filter for no show leads", "FILTER_LEAD_CUSTOM_LABEL_POSITIVE": "Filter for leads with positive custom label", "FILTER_LEAD_CUSTOM_LABEL_NEGATIVE": "Filter for leads with negative custom label", "FILTER_VAL_BOUNCED": "Filter for bounced leads", "FILTER_VAL_SKIPPED": "Filter for skipped leads", "FILTER_VAL_RISKY": "Filter for risky leads", "FILTER_VAL_INVALID": "Filter for invalid leads", "FILTER_VAL_VALID": "Filter for valid leads", "FILTER_VAL_IN_SUBSEQUENCE": "Filter for leads in subsequence", "FILTER_VAL_OPENED_NO_REPLY": "Filter for leads with opened emails but no reply", "FILTER_VAL_COMPLETED_NO_REPLY": "Filter for leads with completed sequence but no reply", "FILTER_VAL_NO_OPENS": "Filter for leads with no opened emails", "FILTER_VAL_REPLIED": "Filter for leads that replied", "FILTER_VAL_LINK_CLICKED": "Filter for leads that clicked a link" }, "description": "Filter criteria for leads. For custom lead labels, use the `interest_status` field.", "example": "FILTER_VAL_CONTACTED" }, "campaign": { "type": "string", "format": "uuid", "description": "Campaign ID to filter leads", "example": "019e0e40-56b4-7864-96e1-67df0dfc61aa" }, "list_id": { "type": "string", "format": "uuid", "description": "List ID to filter leads", "example": "019e0e40-56b4-7864-96e1-67e0550f0893" }, "in_campaign": { "type": "boolean", "description": "Whether the lead is in a campaign", "example": true }, "in_list": { "type": "boolean", "description": "Whether the lead is in a list", "example": true }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-56b4-7864-96e1-67e10edced6d" }, "description": "Array of lead IDs to include" }, "queries": { "type": "array", "items": { "type": "object", "required": [ "actionType", "values" ], "description": "Smart view query to filter leads", "properties": { "actionType": { "type": "string", "enum": [ "reply", "email-open", "last-contacted", "link-click", "lead-status", "lead-status-change" ], "example": "email-open" }, "values": { "type": "object", "properties": { "occurrence-days": { "type": "number", "example": 1 }, "occurrence-count": { "type": "object", "properties": { "condition": { "type": "string", "enum": [ "more", "less", "equal" ], "example": "more" }, "count": { "type": "number", "example": 1 } } }, "lead-status": { "type": "object", "properties": { "status": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "is", "is-not" ], "example": "is" } } } } } }, "example": { "actionType": "email-open", "values": { "occurrence-days": 1 } } } }, "excluded_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-56b4-7864-96e1-67e2128a802c" }, "description": "Array of lead IDs to exclude" }, "contacts": { "type": "array", "items": { "type": "string", "format": "email", "example": "test@test.com" }, "description": "Array of emails the leads needs to have" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "The number of items to return", "example": 10 }, "starting_after": { "type": "string", "description": "Forward pagination cursor. When distinct_contacts is false, provide the `id` value from the last lead of the previous page; when true, provide the lead's email.", "example": "019e0e40-62bc-7523-af11-957e3ab75ea0" }, "organization_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-62bc-7523-af11-957fa77ad495" }, "description": "Array of organization user IDs to filter leads" }, "smart_view_id": { "type": "string", "format": "uuid", "description": "Smart view ID to filter leads", "example": "019e0e40-62bc-7523-af11-958053e0771f" }, "is_website_visitor": { "type": "boolean", "description": "Whether the lead is a website visitor", "example": true }, "distinct_contacts": { "type": "boolean", "description": "Whether to return distinct contacts", "example": true }, "enrichment_status": { "type": "number", "enum": [ 1, -1, 11, -2 ], "x-enumDescriptions": { "1": "The lead has been successfully enriched", "11": "The lead is pending enrichment", "-1": "Enrichment data is not available for the lead", "-2": "An error occurred during the enrichment process" }, "description": "Enrichment status to filter leads", "example": 1 }, "esg_code": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "all", "none" ], "x-enumDescriptions": { "0": "In Queue", "1": "Barracuda", "2": "Mimecast", "3": "Proofpoint", "4": "Cisco", "all": "All", "none": "None" }, "description": "ESG code to filter leads", "example": "1" } } } } } }, "responses": { "200": { "description": "The list of Lead", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Lead", "items": { "$ref": "#/components/schemas/def-11" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-62bc-7523-af11-958193366e9a" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/{id}": { "get": { "operationId": "getLead", "summary": "Get lead", "tags": [ "Lead" ], "description": "Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62bd-7a0b-bfff-d2e7fe22866e" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchLead", "summary": "Patch lead", "tags": [ "Lead" ], "description": "Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "personalization": { "type": [ "string", "null" ], "description": "Personalization of the lead", "example": "Hello, how are you?" }, "website": { "type": [ "string", "null" ], "description": "Website of the lead", "example": "https://example.com" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the lead", "example": "Doe" }, "first_name": { "type": [ "string", "null" ], "description": "First name of the lead", "example": "John" }, "company_name": { "type": [ "string", "null" ], "description": "Company name of the lead", "example": "Example Inc." }, "job_title": { "type": [ "string", "null" ], "description": "Job title of the lead", "example": "Head of Growth" }, "phone": { "type": [ "string", "null" ], "description": "Phone number of the lead", "example": "+1234567890" }, "lt_interest_status": { "type": "number", "description": "Lead interest status. It can be either a static value (check below), or a custom status interest value", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 }, "pl_value_lead": { "type": [ "string", "null" ], "description": "Potential value of the lead", "example": "High" }, "assigned_to": { "type": [ "string", "null" ], "description": "ID of the user assigned to the lead", "format": "uuid", "example": "019e0e40-12e2-7a51-bfcc-4d94276e4b3a" }, "custom_variables": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field", "example": { "past_customer": true, "has_tried_competitors": false } } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62c0-7ee8-8429-e9b505bcc58f" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteLead", "summary": "Delete lead", "tags": [ "Lead" ], "description": "Requires one of the following scopes: `leads:delete`, `leads:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-62c2-7789-ab7c-fac282b36ad1" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/merge": { "post": { "operationId": "mergeLeads", "summary": "Merge two leads", "tags": [ "Lead" ], "description": "Merge two leads\n\n\nRequires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_id": { "type": "string", "format": "uuid", "description": "The ID of the lead to merge.", "example": "019e0e40-62bf-719e-8099-2cbd76295b4c" }, "destination_lead_id": { "type": "string", "format": "uuid", "description": "The ID of the destination lead to merge into.", "example": "019e0e40-62bf-719e-8099-2cbeb9c9e0ab" } }, "required": [ "lead_id", "destination_lead_id" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/update-interest-status": { "post": { "operationId": "updateLeadInterestStatus", "summary": "Update the interest status of a lead", "tags": [ "Lead" ], "description": "Update the interest status of a lead", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lead_email": { "type": "string", "description": "The email of the lead to update the interest status of.", "example": "test@test.com" }, "interest_value": { "type": [ "number", "null" ], "description": "Set this field to \"null\" to reset the lead value to \"Lead\". This is the same as moving the lead to the \"Lead\" status in the web app. Please check the `lt_interest_status` field for the list of possible values.", "example": 1 }, "campaign_id": { "type": "string", "description": "The ID of the campaign to update the interest status of.", "example": "019e0e40-62bf-719e-8099-2cbf68707b40" }, "ai_interest_value": { "type": "number", "description": "The AI interest value to set for the lead.", "example": 1 }, "disable_auto_interest": { "type": "boolean", "description": "Whether to disable the auto interest.", "example": true }, "list_id": { "type": "string", "description": "The ID of the list to update the interest status of.", "example": "019e0e40-62bf-719e-8099-2cc0487e5e91" } }, "required": [ "lead_email", "interest_value" ] } } }, "required": true }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Lead interest status update background job submitted" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid lead email" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/subsequence/remove": { "post": { "operationId": "removeLeadFromSubsequence", "summary": "Remove a lead from a subsequence", "tags": [ "Lead" ], "description": "Remove a lead from a subsequence\n\n\nRequires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the lead to remove from the subsequence.", "example": "019e0e40-62c1-7638-b230-c89fb37bccd2" } }, "required": [ "id" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/bulk-assign": { "post": { "operationId": "bulkAssignLeads", "summary": "Bulk assign leads to organization users", "tags": [ "Lead" ], "description": "Bulk assign leads to organization users", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "description": "The search query to filter leads by.", "example": "test" }, "filter": { "type": "string", "enum": [ "FILTER_VAL_CONTACTED", "FILTER_VAL_NOT_CONTACTED", "FILTER_VAL_COMPLETED", "FILTER_VAL_UNSUBSCRIBED", "FILTER_VAL_ACTIVE", "FILTER_LEAD_INTERESTED", "FILTER_LEAD_NOT_INTERESTED", "FILTER_LEAD_MEETING_BOOKED", "FILTER_LEAD_MEETING_COMPLETED", "FILTER_LEAD_CLOSED", "FILTER_LEAD_OUT_OF_OFFICE", "FILTER_LEAD_WRONG_PERSON", "FILTER_LEAD_LOST", "FILTER_LEAD_NO_SHOW", "FILTER_LEAD_CUSTOM_LABEL_POSITIVE", "FILTER_LEAD_CUSTOM_LABEL_NEGATIVE", "FILTER_VAL_BOUNCED", "FILTER_VAL_SKIPPED", "FILTER_VAL_RISKY", "FILTER_VAL_INVALID", "FILTER_VAL_VALID", "FILTER_VAL_IN_SUBSEQUENCE", "FILTER_VAL_OPENED_NO_REPLY", "FILTER_VAL_COMPLETED_NO_REPLY", "FILTER_VAL_NO_OPENS", "FILTER_VAL_REPLIED", "FILTER_VAL_LINK_CLICKED" ], "description": "The filter to apply to the leads.", "example": "FILTER_LEAD_CLOSED" }, "campaign": { "type": "string", "format": "uuid", "description": "The ID of the campaign to filter leads by.", "example": "019e0e40-62c1-7638-b230-c8a09fd677ce" }, "list_id": { "type": "string", "format": "uuid", "description": "The ID of the list to filter leads by.", "example": "019e0e40-62c2-7789-ab7c-fabe39c3fe9a" }, "in_campaign": { "type": "boolean", "description": "Whether the leads are in the campaign.", "example": true }, "in_list": { "type": "boolean", "description": "Whether the leads are in the list.", "example": true }, "organization_user_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-62c2-7789-ab7c-fabfc71e6281" }, "minItems": 1 }, "smart_view_id": { "type": "string", "format": "uuid", "description": "The ID of the smart view to filter leads by.", "example": "019e0e40-62c2-7789-ab7c-fac00f557609" }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-62c2-7789-ab7c-fac1fae5925a" }, "description": "The IDs of the leads to filter by." }, "limit": { "type": "integer", "minimum": 0, "description": "The limit of the number of leads to return.", "example": 10 }, "queries": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "reply", "email-open", "last-contacted", "link-click", "lead-status", "lead-status-change" ], "x-enumDescriptions": { "reply": "Reply", "email-open": "Email Opened", "last-contacted": "Last Contacted", "link-click": "Link Click", "lead-status": "Lead Status", "lead-status-change": "Lead Status Change" }, "example": "email-open" }, "values": { "type": "object", "properties": { "occurrence-days": { "type": "number", "example": 5 }, "occurrence-count": { "type": "object", "properties": { "condition": { "type": "string", "enum": [ "more", "less", "equal" ], "x-enumDescriptions": { "more": "More than the count", "less": "Less than the count", "equal": "Equal to the count" }, "example": "more" }, "count": { "type": "number", "example": 5 } } }, "lead-status": { "type": "object", "properties": { "status": { "type": "number", "example": 5 }, "condition": { "type": "string", "enum": [ "is", "is-not" ], "x-enumDescriptions": { "is": "Is", "is-not": "Is Not" }, "example": "is" } } } } } }, "required": [ "actionType", "values" ] } } }, "required": [ "organization_user_ids" ] } } }, "required": true }, "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "accepted" }, "message": { "type": "string", "example": "Your request will be processed in a background job" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid ID on `organization_user_ids` field" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/move": { "post": { "operationId": "moveLeads", "summary": "Move leads to a campaign or list", "tags": [ "Lead" ], "description": "Move leads to a different campaign or list. This endpoint will return a background job that will process the move. The job will be processed in the background and the leads will be moved to the destination campaign or list. You can use the `/background-jobs/:id` endpoint to check the job status. Note: When using the `ids` parameter, you must also provide either `campaign` or `list_id` to specify which campaign or list to filter the leads from.\n\n\nRequires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "description": "A search string to search the leads against - can be First Name, Last Name, or Email", "example": "John Doe" }, "filter": { "type": "string", "x-enumDescriptions": { "FILTER_VAL_CONTACTED": "Filter for contacted leads", "FILTER_VAL_NOT_CONTACTED": "Filter for not contacted leads", "FILTER_VAL_COMPLETED": "Filter for completed leads", "FILTER_VAL_UNSUBSCRIBED": "Filter for unsubscribed leads", "FILTER_VAL_ACTIVE": "Filter for active leads", "FILTER_LEAD_INTERESTED": "Filter for interested leads", "FILTER_LEAD_NOT_INTERESTED": "Filter for not interested leads", "FILTER_LEAD_MEETING_BOOKED": "Filter for leads with meeting booked", "FILTER_LEAD_MEETING_COMPLETED": "Filter for leads with meeting completed", "FILTER_LEAD_CLOSED": "Filter for closed leads", "FILTER_LEAD_OUT_OF_OFFICE": "Filter for leads out of office", "FILTER_LEAD_WRONG_PERSON": "Filter for wrong person leads", "FILTER_LEAD_LOST": "Filter for lost leads", "FILTER_LEAD_NO_SHOW": "Filter for no show leads", "FILTER_LEAD_CUSTOM_LABEL_POSITIVE": "Filter for leads with positive custom label", "FILTER_LEAD_CUSTOM_LABEL_NEGATIVE": "Filter for leads with negative custom label", "FILTER_VAL_BOUNCED": "Filter for bounced leads", "FILTER_VAL_SKIPPED": "Filter for skipped leads", "FILTER_VAL_RISKY": "Filter for risky leads", "FILTER_VAL_INVALID": "Filter for invalid leads", "FILTER_VAL_VALID": "Filter for valid leads", "FILTER_VAL_IN_SUBSEQUENCE": "Filter for leads in subsequence", "FILTER_VAL_OPENED_NO_REPLY": "Filter for leads with opened emails but no reply", "FILTER_VAL_COMPLETED_NO_REPLY": "Filter for leads with completed sequence but no reply", "FILTER_VAL_NO_OPENS": "Filter for leads with no opened emails", "FILTER_VAL_REPLIED": "Filter for leads that replied", "FILTER_VAL_LINK_CLICKED": "Filter for leads that clicked a link" }, "description": "Filter criteria for leads. For custom lead labels, use the `interest_status` field.", "example": "FILTER_VAL_CONTACTED" }, "campaign": { "type": "string", "format": "uuid", "description": "Campaign ID to filter leads", "example": "019e0e40-56b4-7864-96e1-67df0dfc61aa" }, "list_id": { "type": "string", "format": "uuid", "description": "List ID to filter leads", "example": "019e0e40-56b4-7864-96e1-67e0550f0893" }, "in_campaign": { "type": "boolean", "description": "Whether the lead is in a campaign", "example": true }, "in_list": { "type": "boolean", "description": "Whether the lead is in a list", "example": true }, "ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-62c3-7101-bf3c-b1e58c4fca07" }, "description": "Array of lead IDs to include. When using this parameter, you must provide either `campaign` or `list_id` to specify which campaign or list to filter the leads from. This parameter acts as a filter within the specified campaign or list, not as a standalone way to select leads." }, "queries": { "type": "array", "items": { "type": "object", "required": [ "actionType", "values" ], "description": "Smart view query to filter leads", "properties": { "actionType": { "type": "string", "enum": [ "reply", "email-open", "last-contacted", "link-click", "lead-status", "lead-status-change" ], "example": "email-open" }, "values": { "type": "object", "properties": { "occurrence-days": { "type": "number", "example": 1 }, "occurrence-count": { "type": "object", "properties": { "condition": { "type": "string", "enum": [ "more", "less", "equal" ], "example": "more" }, "count": { "type": "number", "example": 1 } } }, "lead-status": { "type": "object", "properties": { "status": { "type": "number", "example": 1 }, "condition": { "type": "string", "enum": [ "is", "is-not" ], "example": "is" } } } } } }, "example": { "actionType": "email-open", "values": { "occurrence-days": 1 } } } }, "excluded_ids": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "019e0e40-56b4-7864-96e1-67e2128a802c" }, "description": "Array of lead IDs to exclude" }, "contacts": { "type": "array", "items": { "type": "string", "format": "email", "example": "test@test.com" }, "description": "Array of emails the leads needs to have" }, "to_campaign_id": { "type": "string", "format": "uuid", "description": "The ID of the campaign to move the leads to.", "example": "019e0e40-62c3-7101-bf3c-b1e6a8af6c8e" }, "to_list_id": { "type": "string", "format": "uuid", "description": "The ID of the list to move the leads to.", "example": "019e0e40-62c3-7101-bf3c-b1e7c10a3018" }, "ignore_resource_filter_clauses": { "type": "boolean", "description": "Whether to ignore saved lead-finder clauses for the source campaign/list when selecting leads to move.", "example": true }, "check_duplicates_in_campaigns": { "type": "boolean", "description": "Whether to check duplicates in campaigns.", "example": true }, "skip_leads_in_verification": { "type": "boolean", "description": "Whether to skip leads in verification.", "example": true }, "limit": { "type": "number", "description": "The limit of the number of leads to move.", "example": 10 }, "assigned_to": { "type": "string", "format": "uuid", "description": "The ID of the user to assign the leads to.", "example": "019e0e40-62c3-7101-bf3c-b1e837679922" }, "esp_code": { "type": "number", "enum": [ 0, 1, 2, 3, 8, 9, 10, 12, 13, 999, 1000 ], "x-enumDescriptions": { "0": "In Queue", "1": "Google", "2": "Microsoft", "3": "Zoho", "8": "AirMail", "9": "Yahoo", "10": "Yandex", "12": "Webde", "13": "Liberoit", "999": "Other", "1000": "Not Found" }, "description": "The ESP code to move the leads for.", "example": 1 }, "esg_code": { "type": "string", "enum": [ "0", "1", "2", "3", "4", "all", "none" ], "x-enumDescriptions": { "0": "In Queue", "1": "Barracuda", "2": "Mimecast", "3": "Proofpoint", "4": "Cisco", "all": "All", "none": "None" }, "description": "The ESG code to move the leads for.", "example": "1" }, "copy_leads": { "type": "boolean", "description": "Whether to copy the leads.", "example": true }, "check_duplicates": { "type": "boolean", "description": "Whether to check duplicates.", "example": true }, "reset_interest_status": { "type": "boolean", "description": "Whether to reset the interest status of leads when moving or copying them. When true, the interest status will be reset. When false, the existing interest status will be preserved; for non-copy campaign-to-campaign moves, opportunities will also be migrated to the target campaign.", "example": true } } } } } }, "responses": { "200": { "description": "The requested Background Job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-12" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/subsequence/move": { "post": { "operationId": "moveLeadToSubsequence", "summary": "Move a lead to a subsequence", "tags": [ "Lead" ], "description": "Move a lead to a subsequence\n\n\nRequires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subsequence_id": { "type": "string", "format": "uuid", "example": "019e0e40-62c5-7275-a0ec-d41ddd7dc8a4" }, "id": { "type": "string", "format": "uuid", "example": "019e0e40-62c5-7275-a0ec-d41eeba48cfd" } }, "required": [ "id", "subsequence_id" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-11" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/leads/add": { "post": { "operationId": "bulkAddLeads", "summary": "Add leads in bulk to a campaign or list", "tags": [ "Lead" ], "description": "Adds up to 1000 leads to either a campaign or a list. You must provide a `campaign_id` or a `list_id`, but not both. The endpoint validates emails, checks against blocklists and existing leads.\n\n\nRequires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid", "description": "The unique identifier for the campaign to add leads to. Use this field OR `list_id`, but not both.", "example": "019e0e40-62c5-7275-a0ec-d41f51792b55" }, "list_id": { "type": "string", "format": "uuid", "description": "The unique identifier for the list to add leads to. Use this field OR `campaign_id`, but not both.", "example": "019e0e40-62c5-7275-a0ec-d4208eb8377f" }, "leads": { "type": "array", "minItems": 1, "maxItems": 1000, "description": "An array of lead objects to create. When using `campaign_id`: Each lead object must contain an `email`. When using `list_id` Each lead object must contain at least one of the following: `email`, `first_name`, or `last_name`.", "items": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "description": "Email address of the lead", "example": "example@example.com" }, "personalization": { "type": [ "string", "null" ], "description": "Personalization of the lead", "example": "Hello, how are you?" }, "website": { "type": [ "string", "null" ], "description": "Website of the lead", "example": "https://example.com" }, "last_name": { "type": [ "string", "null" ], "description": "Last name of the lead", "example": "Doe" }, "first_name": { "type": [ "string", "null" ], "description": "First name of the lead", "example": "John" }, "company_name": { "type": [ "string", "null" ], "description": "Company name of the lead", "example": "Example Inc." }, "job_title": { "type": [ "string", "null" ], "description": "Job title of the lead", "example": "Head of Growth" }, "phone": { "type": [ "string", "null" ], "description": "Phone number of the lead", "example": "+1234567890" }, "lt_interest_status": { "type": "number", "description": "Lead interest status. It can be either a static value (check below), or a custom status interest value", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 }, "pl_value_lead": { "type": [ "string", "null" ], "description": "Potential value of the lead", "example": "High" }, "assigned_to": { "type": [ "string", "null" ], "description": "ID of the user assigned to the lead", "format": "uuid", "example": "019e0e40-12e2-7a51-bfcc-4d94276e4b3a" }, "custom_variables": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] }, "description": "Custom variables can include any metadata about the lead that is relevant to the campaign, the campaign will be updated to allow all the other leads in the campaign to have the same custom variables. The custom variables will be added to the lead payload field", "example": { "past_customer": true, "has_tried_competitors": false } } }, "required": [], "additionalProperties": false } }, "blocklist_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional blocklist ID to check leads against. If omitted, the workspace default blocklist is used.", "example": "019e0e40-62c5-7275-a0ec-d421facff572" }, "assigned_to": { "type": "string", "format": "uuid", "description": "Optional user ID to assign all imported leads to. If omitted, leads are assigned to the campaign owner when `campaign_id` is defined, or the user making the request.", "example": "019e0e40-62c5-7275-a0ec-d42265bc099e" }, "verify_leads_on_import": { "type": "boolean", "description": "If true, a background job will be created to verify the email addresses of the imported leads.", "example": false }, "skip_if_in_workspace": { "type": "boolean", "description": "If true, any lead that already exists anywhere in your workspace (in any campaign or list) will be skipped. This option overrides the other \"skip_if\" flags.", "example": true }, "skip_if_in_campaign": { "type": "boolean", "description": "If true, any lead that already exists in ANY campaign in your workspace will be skipped.", "example": false }, "skip_if_in_list": { "type": "boolean", "description": "If true, any lead that already exists in ANY list in your workspace will be skipped.", "example": false } }, "required": [ "leads" ] } } }, "required": true }, "responses": { "200": { "description": "A summary of the bulk import operation.", "content": { "application/json": { "schema": { "description": "A summary of the bulk import operation.", "type": "object", "properties": { "status": { "type": "string", "description": "Indicates the request was processed.", "example": "success" }, "total_sent": { "type": "integer", "description": "The total number of leads included in the request payload.", "example": 10 }, "leads_uploaded": { "type": "integer", "description": "The number of leads that were successfully created.", "example": 7 }, "in_blocklist": { "type": "integer", "description": "The number of leads that were skipped because their email was found on the blocklist.", "example": 1 }, "blocklist_used": { "type": [ "null", "string" ], "description": "The ID of the blocklist that was used for the check.", "example": "019e0e40-62c5-7275-a0ec-d423cc7436fb" }, "duplicated_leads": { "type": "integer", "description": "The number of leads that were already in this specific campaign or list and were not re-added.", "example": 0 }, "skipped_count": { "type": "integer", "description": "The number of leads skipped due to the `skip_if_in_...` flags being enabled.", "example": 1 }, "invalid_email_count": { "type": "integer", "description": "The number of leads skipped due to an invalid email format or a missing email address.", "example": 1 }, "incomplete_count": { "type": "integer", "description": "The number of leads skipped due to missing email and names. Only calculated for lists.", "example": 1 }, "duplicate_email_count": { "type": "integer", "description": "The number of leads skipped because their email was duplicated within the request payload itself.", "example": 0 }, "remaining_in_plan": { "type": [ "null", "integer" ], "description": "The remaining lead uploads in the current billing plan. This value is only present in the response when a `campaign_id` is provided.", "example": 9993 }, "created_leads": { "type": "array", "description": "A list of created leads with their summary information. You can use this to map your input to the created leads.", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The index of the lead in the input array. For leads that have no email address you can use this field as the key to your input leads.", "example": 0 }, "id": { "type": "string", "format": "uuid", "description": "The ID of the lead. Use it for GET, DELETE or PATCH operations.", "example": "019e0e40-62c6-7590-be18-d52f50519e50" }, "email": { "type": [ "null", "string" ], "example": "test@example.com" }, "first_name": { "type": [ "null", "string" ], "example": "John" }, "last_name": { "type": [ "null", "string" ], "example": "Doe" }, "phone": { "type": [ "null", "string" ], "example": "+1234567890" } }, "required": [ "id", "index" ], "example": { "id": "019e0e40-62c6-7590-be18-d53021f5d4dd", "email": "test@example.com", "index": 0 } }, "example": [ { "id": "019e0e40-62c6-7590-be18-d53105138c16", "email": "test@example.com", "index": 0 } ] } }, "required": [ "status", "total_sent", "leads_uploaded", "in_blocklist", "blocklist_used", "duplicated_leads", "skipped_count", "invalid_email_count", "incomplete_count", "duplicate_email_count", "remaining_in_plan", "created_leads" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/oauth/google/init": { "post": { "operationId": "initGoogleOAuth", "summary": "Initialize google oauth", "tags": [ "OAuth" ], "description": "Creates an OAuth session and returns the Google authorization URL. The user should be redirected to auth_url to complete the OAuth flow. Poll the status endpoint to check for completion.\n\n**Special rate limits (stricter than the standard API rate limit) to comply with upstream Google rate limits:**\n- 75 requests per minute per workspace\n- 150 requests per minute per IP\n\nIf Google's upstream OAuth service is temporarily unavailable, requests may return 503.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Session ID for polling status", "example": "abc123def456" }, "auth_url": { "type": "string", "description": "Google authorization URL to redirect user to", "example": "https://accounts.google.com/o/oauth2/auth?..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Session expiry time (10 minutes from creation)", "example": "2026-01-14T12:30:00.000Z" } } } } } }, "429": { "description": "Rate limit exceeded — 75 requests per minute per workspace or 150 requests per minute per IP", "content": { "application/json": { "schema": { "type": "object", "description": "Rate limit exceeded — 75 requests per minute per workspace or 150 requests per minute per IP", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded for OAuth session creation" } }, "required": [ "statusCode", "error", "message" ] } } } }, "503": { "description": "Upstream provider temporarily unavailable — the provider is rate-limiting Instantly. Retry after a short delay.", "content": { "application/json": { "schema": { "type": "object", "description": "Upstream provider temporarily unavailable — the provider is rate-limiting Instantly. Retry after a short delay.", "properties": { "statusCode": { "type": "number", "enum": [ 503 ], "example": 503 }, "error": { "type": "string", "enum": [ "Service Unavailable" ], "example": "Service Unavailable" }, "message": { "type": "string", "example": "OAuth is temporarily unavailable, please retry shortly" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/oauth/microsoft/init": { "post": { "operationId": "initMicrosoftOAuth", "summary": "Initialize microsoft oauth", "tags": [ "OAuth" ], "description": "Creates an OAuth session and returns the Microsoft authorization URL. The user should be redirected to auth_url to complete the OAuth flow. Poll the status endpoint to check for completion.\n\n**Special rate limits (stricter than the standard API rate limit) to comply with upstream Microsoft rate limits:**\n- 75 requests per minute per workspace\n- 150 requests per minute per IP\n\nIf Microsoft's upstream OAuth service is temporarily unavailable, requests may return 503.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Session ID for polling status", "example": "abc123def456" }, "auth_url": { "type": "string", "description": "Microsoft authorization URL to redirect user to", "example": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?..." }, "expires_at": { "type": "string", "format": "date-time", "description": "Session expiry time (10 minutes from creation)", "example": "2026-01-14T12:30:00.000Z" } } } } } }, "429": { "description": "Rate limit exceeded — 75 requests per minute per workspace or 150 requests per minute per IP", "content": { "application/json": { "schema": { "type": "object", "description": "Rate limit exceeded — 75 requests per minute per workspace or 150 requests per minute per IP", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded for OAuth session creation" } }, "required": [ "statusCode", "error", "message" ] } } } }, "503": { "description": "Upstream provider temporarily unavailable — the provider is rate-limiting Instantly. Retry after a short delay.", "content": { "application/json": { "schema": { "type": "object", "description": "Upstream provider temporarily unavailable — the provider is rate-limiting Instantly. Retry after a short delay.", "properties": { "statusCode": { "type": "number", "enum": [ 503 ], "example": 503 }, "error": { "type": "string", "enum": [ "Service Unavailable" ], "example": "Service Unavailable" }, "message": { "type": "string", "example": "OAuth is temporarily unavailable, please retry shortly" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/oauth/session/status/{sessionId}": { "get": { "operationId": "getOAuthSessionStatus", "summary": "Get oauth session status", "tags": [ "OAuth" ], "description": "Poll this endpoint to check the OAuth session result. Works for both Google and Microsoft OAuth sessions. Returns pending while waiting, success with account details when complete, or error if something went wrong. Sessions expire after 10 minutes.", "parameters": [ { "schema": { "type": "string", "example": "abc123def456" }, "in": "path", "name": "sessionId", "required": true, "description": "Session ID from init response" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "success", "error", "expired" ], "description": "Current status of the OAuth session", "example": "success" }, "email": { "type": "string", "description": "Email of the connected account (on success)", "example": "user@example.com" }, "name": { "type": "string", "description": "Name of the account owner (on success)", "example": "John Doe" }, "error": { "type": "string", "description": "Error code (on error)", "example": "access_denied" }, "error_description": { "type": "string", "description": "Human-readable error description (on error)", "example": "User denied access to the application" } } } } } } } } }, "/api/v2/supersearch-enrichment/signal-keywords-facet": { "post": { "operationId": "signalKeywordsFacet", "summary": "Facet keywords for a signal category", "tags": [ "SuperSearchEnrichment" ], "description": "Return the top matching keyword tokens for a given signal category and keyword field, aggregated from the last 90 days of signal data. Powers the Signals filter autocomplete in the Lead Finder. Unknown (category, field) pairs return 400.\n\n\nRequires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "field" ], "properties": { "category": { "type": "string", "description": "Signal category to facet against (e.g. `linkedin_post_contact`).", "example": "linkedin_post_contact" }, "field": { "type": "string", "description": "Indexed keyword field on `autobound_signals` to aggregate on.", "example": "tags" }, "prefix": { "type": "string", "description": "Optional case-insensitive prefix to narrow the tokens returned.", "example": "ai" }, "limit": { "type": "number", "description": "Max number of keyword buckets to return (1-100).", "minimum": 1, "maximum": 100, "example": 20 } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "keywords": { "type": "array", "description": "Keyword tokens ordered by descending frequency.", "items": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword token (lowercased).", "example": "artificial intelligence" }, "count": { "type": "number", "description": "Number of signal records with this token in the last 90 days.", "example": 22418 } } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences": { "post": { "operationId": "createCampaignSubsequence", "summary": "Create campaign subsequence", "tags": [ "CampaignSubsequence" ], "description": "Requires one of the following scopes: `subsequences:create`, `subsequences:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateCampaign Subsequence", "description": "The Campaign Subsequence to create", "type": "object", "properties": { "parent_campaign": { "type": "string", "description": "ID of the parent campaign", "format": "uuid", "example": "019e0e40-2ab6-7fd4-abd7-4e15c5c50074" }, "name": { "type": "string", "description": "Name of the subsequence", "example": "Follow-up sequence" }, "conditions": { "type": "object", "description": "Conditions that trigger the subsequence", "properties": { "crm_status": { "type": "array", "description": "Lead CRM statuses that trigger the subsequence.", "items": { "type": "number", "enum": [ 1, 2, 3, 4, 0, -1, -2, -3, -4 ], "x-enumDescriptions": { "0": "Out of Office", "1": "Interested", "2": "Meeting Booked", "3": "Meeting Completed", "4": "Won", "-1": "Not Interested", "-2": "Wrong Person", "-3": "Lost", "-4": "No Show" }, "example": 1 } }, "lead_activity": { "type": "array", "description": "Lead activities that trigger the subsequence.", "items": { "type": "number", "enum": [ 4, 91, 2 ], "x-enumDescriptions": { "2": "Email Opened - Triggered when a lead opens an email", "4": "Email Link Clicked - Triggered when a lead clicks a link in an email", "91": "Campaign Completed Without Reply - Triggered when a campaign completes for a lead without receiving a reply" }, "example": 4 } }, "reply_contains": { "type": "string", "example": "yes" } } }, "subsequence_schedule": { "type": "object", "description": "Schedule configuration for the subsequence", "properties": { "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "End date in YYYY-MM-DD format. Uses the campaign's timezone.", "example": "2025-09-25" }, "schedules": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "My Schedule" }, "timing": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "09:00" }, "to": { "type": "string", "pattern": "^([01][0-9]|2[0-3]):([0-5][0-9])$", "example": "17:00" } }, "required": [ "from", "to" ] }, "days": { "type": "object", "minProperties": 1, "properties": { "0": { "type": "boolean", "example": true }, "1": { "type": "boolean", "example": true }, "2": { "type": "boolean", "example": true }, "3": { "type": "boolean", "example": true }, "4": { "type": "boolean", "example": true }, "5": { "type": "boolean", "example": false }, "6": { "type": "boolean", "example": false } } }, "timezone": { "type": "string", "enum": [ "Etc/GMT+12", "Etc/GMT+11", "Etc/GMT+10", "America/Anchorage", "America/Dawson", "America/Creston", "America/Chihuahua", "America/Boise", "America/Belize", "America/Chicago", "America/Bahia_Banderas", "America/Regina", "America/Bogota", "America/Detroit", "America/Indiana/Marengo", "America/Caracas", "America/Asuncion", "America/Glace_Bay", "America/Campo_Grande", "America/Anguilla", "America/Santiago", "America/St_Johns", "America/Sao_Paulo", "America/Argentina/La_Rioja", "America/Araguaina", "America/Godthab", "America/Montevideo", "America/Bahia", "America/Noronha", "America/Scoresbysund", "Atlantic/Cape_Verde", "Africa/Casablanca", "America/Danmarkshavn", "Europe/Isle_of_Man", "Atlantic/Canary", "Africa/Abidjan", "Arctic/Longyearbyen", "Europe/Belgrade", "Africa/Ceuta", "Europe/Sarajevo", "Africa/Algiers", "Africa/Windhoek", "Asia/Nicosia", "Asia/Beirut", "Africa/Cairo", "Asia/Damascus", "Europe/Bucharest", "Africa/Blantyre", "Europe/Helsinki", "Europe/Istanbul", "Asia/Jerusalem", "Africa/Tripoli", "Asia/Amman", "Asia/Baghdad", "Europe/Kaliningrad", "Asia/Aden", "Africa/Addis_Ababa", "Europe/Kirov", "Europe/Astrakhan", "Asia/Tehran", "Asia/Dubai", "Asia/Baku", "Indian/Mahe", "Asia/Tbilisi", "Asia/Yerevan", "Asia/Kabul", "Antarctica/Mawson", "Asia/Yekaterinburg", "Asia/Karachi", "Asia/Kolkata", "Asia/Colombo", "Asia/Kathmandu", "Antarctica/Vostok", "Asia/Dhaka", "Asia/Rangoon", "Antarctica/Davis", "Asia/Novokuznetsk", "Asia/Hong_Kong", "Asia/Krasnoyarsk", "Asia/Brunei", "Australia/Perth", "Asia/Taipei", "Asia/Choibalsan", "Asia/Irkutsk", "Asia/Dili", "Asia/Pyongyang", "Australia/Adelaide", "Australia/Darwin", "Australia/Brisbane", "Australia/Melbourne", "Antarctica/DumontDUrville", "Australia/Currie", "Asia/Chita", "Antarctica/Macquarie", "Asia/Sakhalin", "Pacific/Auckland", "Etc/GMT-12", "Pacific/Fiji", "Asia/Anadyr", "Asia/Kamchatka", "Etc/GMT-13", "Pacific/Apia" ], "example": "Etc/GMT+12" } }, "required": [ "name", "timing", "days", "timezone" ] }, "minItems": 1 } }, "required": [ "schedules" ] }, "sequences": { "type": "array", "description": "List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array", "items": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ], "x-enumDescriptions": { "email": "This steps represents an email" }, "description": "Type of step. This has to be 'email' always - it's the only supported type for now", "example": "email" }, "delay": { "type": "number", "description": "The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).", "example": 2 }, "delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.", "example": "days" }, "pre_delay": { "type": "number", "description": "The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).", "example": 2 }, "pre_delay_unit": { "type": "string", "enum": [ "minutes", "hours", "days" ], "default": "days", "description": "The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.", "example": "days" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "example": "Hello {{firstName}}" }, "body": { "type": "string", "example": "Hey {{firstName}},\n\nI hope you are doing well." }, "v_disabled": { "type": "boolean", "description": "Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant", "example": true } }, "required": [ "subject", "body" ] } } }, "required": [ "type", "delay", "variants" ] } } }, "required": [ "steps" ] } }, "daily_limit_mode": { "type": "string", "description": "Daily limit mode for the subsequence. \"inherit\" uses the parent campaign limit, \"custom\" uses a subsequence-specific limit, \"unlimited\" bypasses the campaign-level daily limit.", "enum": [ "inherit", "custom", "unlimited" ], "example": "inherit" }, "daily_limit": { "type": [ "number", "null" ], "description": "Custom daily limit for the subsequence. Only used when `daily_limit_mode` is \"custom\".", "example": 50 }, "ignore_account_daily_limit": { "type": "boolean", "description": "When enabled, the subsequence will send even when sending accounts have reached their daily limit.", "example": false } }, "required": [ "parent_campaign", "name", "conditions", "subsequence_schedule", "sequences" ], "additionalProperties": false } } }, "required": true, "description": "The Campaign Subsequence to create" }, "responses": { "200": { "description": "The Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listCampaignSubsequence", "summary": "List campaign subsequence", "tags": [ "CampaignSubsequence" ], "description": "Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "query", "name": "parent_campaign", "required": true, "description": "The ID of the campaign to list the subsequences of." }, { "schema": { "type": "string", "example": "test" }, "in": "query", "name": "search", "required": false, "description": "The search query to filter the subsequences by." } ], "responses": { "200": { "description": "The list of Campaign Subsequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Campaign Subsequence", "items": { "$ref": "#/components/schemas/def-26" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6324-7619-859e-b53fe12d7dac" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences/{id}/duplicate": { "post": { "operationId": "duplicateSubsequence", "summary": "Duplicate a subsequence", "tags": [ "CampaignSubsequence" ], "description": "Duplicate a subsequence with the same trigger conditions\n\n\nRequires one of the following scopes: `subsequences:create`, `subsequences:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "parent_campaign": { "type": "string", "format": "uuid", "description": "The ID of the campaign to duplicate the subsequence to.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "name": { "type": "string", "description": "The name of the duplicate subsequence.", "example": "My Duplicate Subsequence" } }, "required": [ "parent_campaign", "name" ] } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "id", "required": true, "description": "The ID of the subsequence to duplicate." } ], "responses": { "200": { "description": "The requested Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences/{id}/pause": { "post": { "operationId": "pauseSubsequence", "summary": "Pause a subsequence", "tags": [ "CampaignSubsequence" ], "description": "Pause a subsequence\n\n\nRequires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "id", "required": true, "description": "Subsequence ID" } ], "responses": { "200": { "description": "The requested Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences/{id}/resume": { "post": { "operationId": "resumeSubsequence", "summary": "Resume a paused subsequence", "tags": [ "CampaignSubsequence" ], "description": "Resume a paused subsequence\n\n\nRequires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "id", "required": true, "description": "The ID of the subsequence to resume." } ], "responses": { "200": { "description": "The requested Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences/{id}": { "get": { "operationId": "getCampaignSubsequence", "summary": "Get campaign subsequence", "tags": [ "CampaignSubsequence" ], "description": "Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6325-7edb-b72d-24b2909539a9" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchCampaignSubsequence", "summary": "Patch campaign subsequence", "tags": [ "CampaignSubsequence" ], "description": "Requires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the subsequence", "example": "Follow-up sequence" }, "daily_limit_mode": { "type": "string", "description": "Daily limit mode for the subsequence. \"inherit\" uses the parent campaign limit, \"custom\" uses a subsequence-specific limit, \"unlimited\" bypasses the campaign-level daily limit.", "enum": [ "inherit", "custom", "unlimited" ], "example": "inherit" }, "daily_limit": { "type": [ "number", "null" ], "description": "Custom daily limit for the subsequence. Only used when `daily_limit_mode` is \"custom\".", "example": 50 }, "ignore_account_daily_limit": { "type": "boolean", "description": "When enabled, the subsequence will send even when sending accounts have reached their daily limit.", "example": false } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6326-71fc-937e-d382439883b5" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteCampaignSubsequence", "summary": "Delete campaign subsequence", "tags": [ "CampaignSubsequence" ], "description": "Requires one of the following scopes: `subsequences:delete`, `subsequences:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6326-71fc-937e-d383aa13ef61" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Campaign Subsequence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-26" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/subsequences/{id}/sending-status": { "get": { "operationId": "getSubsequenceSendingStatus", "summary": "Get subsequence sending status", "tags": [ "CampaignSubsequence" ], "description": "Returns sending status data explaining why a subsequence may not be sending emails or is sending slower than expected. Note: Some fields may be missing when the campaign is out of schedule. Always-present fields: campaign_id, subsequence_id, last_updated, status, issue_tracking.\n\n\nRequires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "boolean", "default": false, "example": false }, "in": "query", "name": "with_ai_summary", "required": false, "description": "Include AI-generated summary" }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6327-7aa5-925b-100a9cb1018f" }, "in": "path", "name": "id", "required": true, "description": "Subsequence ID" } ], "responses": { "200": { "description": "Sending status data with human-readable summary. Returns null for both fields if no data is available.", "content": { "application/json": { "schema": { "type": "object", "description": "Sending status data with human-readable summary. Returns null for both fields if no data is available.", "properties": { "diagnostics": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Raw sending status data. Some fields may be missing when campaign is out of schedule.", "properties": { "campaign_id": { "type": "string", "description": "The campaign ID", "example": "019e0e40-4f29-7185-97ae-bed99021ab1f" }, "subsequence_id": { "type": "string", "description": "The subsequence ID (only present for subsequence endpoints)", "example": "019e0e40-4f29-7185-97ae-bedaaa07b3ea" }, "last_updated": { "type": "string", "description": "ISO timestamp of when this data was last updated", "example": "2026-05-09T19:39:16.137Z" }, "status": { "type": [ "null", "string" ], "description": "Status code explaining why the campaign is not sending or sending slower", "enum": [ "campaign_paused", "campaign_draft", "campaign_completed", "campaign_running_subsequences", "campaign_bounce_protect", "campaign_accounts_unhealthy", "campaign_account_suspended", "out_of_schedule", "waiting_for_leads", "daily_limit_met", "account_daily_limit_met", "new_lead_limit_met", "all_accounts_unhealthy", "waiting_for_esp_match", "domain_limit_reached", "follow_up_delay_not_met", "no_accounts_available", "healthy" ], "example": "healthy" }, "issue_tracking": { "type": "object", "description": "Tracks persistence of the current issue", "properties": { "current_status_code": { "type": [ "null", "string" ], "description": "Current status code", "example": "healthy" }, "issue_first_seen_at": { "type": [ "null", "string" ], "description": "ISO timestamp when the issue was first detected", "example": "2026-05-09T19:39:16.137Z" }, "consecutive_loops_with_issue": { "type": "number", "description": "Number of consecutive processing loops with this issue", "example": 0 }, "last_healthy_send_at": { "type": [ "null", "string" ], "description": "ISO timestamp of last successful send", "example": "2026-05-09T19:39:16.137Z" } } }, "accounts_summary": { "type": "object", "description": "Summary of sending account availability. May be missing when campaign is out of schedule.", "properties": { "total_connected": { "type": "number", "description": "Total number of connected sending accounts", "example": 5 }, "available": { "type": "number", "description": "Number of accounts available to send", "example": 3 }, "unavailable": { "type": "object", "description": "Breakdown of unavailable accounts by reason", "properties": { "daily_limit_hit": { "type": "number", "description": "Accounts that hit their configured daily sending limit", "example": 1 }, "slow_ramp_limit_hit": { "type": "number", "description": "Accounts that hit the dynamic slow ramp limit (warmup feature)", "example": 0 }, "disconnected": { "type": "number", "description": "Accounts that are disconnected", "example": 1 }, "global_gap_not_met": { "type": "number", "description": "Accounts waiting for global sending gap", "example": 0 } } } } }, "campaign_daily_limit": { "type": "object", "description": "Campaign daily sending limit status. May be missing when campaign is out of schedule.", "properties": { "limit": { "type": "number", "description": "Configured daily sending limit", "example": 100 }, "sent": { "type": "number", "description": "Number of emails sent today", "example": 50 }, "limit_hit": { "type": "boolean", "description": "Whether the daily limit has been reached", "example": false } } }, "new_lead_limit": { "type": "object", "description": "New lead daily limit status. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether new lead limiting is enabled", "example": true }, "limit": { "type": [ "null", "number" ], "description": "Configured new lead limit per day", "example": 50 }, "contacted": { "type": "number", "description": "Number of new leads contacted today", "example": 25 }, "limit_hit": { "type": "boolean", "description": "Whether the new lead limit has been reached", "example": false } } }, "schedule_status": { "type": "object", "description": "Campaign schedule status", "properties": { "in_schedule": { "type": "boolean", "description": "Whether the campaign is currently within scheduled sending hours", "example": true } } }, "send_one_by_one": { "type": "object", "description": "Send one-by-one settings. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether send one-by-one mode is enabled", "example": false }, "single_account_per_wait_gap": { "type": "boolean", "description": "Whether to use single account per wait gap", "example": false } } }, "follow_ups_waiting": { "type": "object", "description": "Follow-up emails waiting status. May be missing when campaign is out of schedule.", "properties": { "count": { "type": "number", "description": "Number of follow-ups waiting to be sent", "example": 10 }, "earliest_wait_time_seconds": { "type": [ "null", "number" ], "description": "Seconds until the earliest follow-up can be sent", "example": 3600 } } }, "esp_routing_status": { "type": "object", "description": "ESP routing status. May be missing when campaign is out of schedule.", "properties": { "enabled": { "type": "boolean", "description": "Whether ESP routing is enabled", "example": false }, "waiting_for_match": { "type": "boolean", "description": "Whether waiting for an ESP-matched account", "example": false }, "connected_esps": { "type": "array", "items": { "type": "number", "example": 1 }, "description": "List of connected ESP IDs" } } }, "domain_limiter": { "type": "object", "description": "Per-domain sending limit status. May be missing when campaign is out of schedule.", "properties": { "active": { "type": "boolean", "description": "Whether domain limiting is active", "example": false }, "domains_at_limit": { "type": "number", "description": "Number of domains that have reached their limit", "example": 0 } } }, "leads_status": { "type": "object", "description": "Lead availability status. May be missing when campaign is out of schedule.", "properties": { "no_leads_ready": { "type": "boolean", "description": "Whether there are no leads ready to receive emails", "example": false }, "account_unavailable_skips": { "type": "number", "description": "Number of leads skipped due to account unavailability", "example": 0 }, "delay_not_met_skips": { "type": "number", "description": "Number of leads skipped due to delay requirements not met", "example": 0 } } } } }, "summary": { "type": [ "null", "object" ], "additionalProperties": true, "description": "Human-readable summary of the sending status", "properties": { "status": { "type": [ "null", "string" ], "description": "The status code", "example": "healthy" }, "status_message": { "type": [ "null", "string" ], "description": "Human-readable message explaining the status", "example": "Campaign is sending normally" }, "issue_started_at": { "type": [ "null", "string" ], "description": "ISO timestamp when the issue was first detected", "example": "2026-05-09T19:39:16.137Z" }, "last_healthy_send_at": { "type": [ "null", "string" ], "description": "ISO timestamp of last successful send", "example": "2026-05-09T19:39:16.137Z" }, "ai_summary": { "type": [ "null", "string" ], "description": "AI-generated plain-English summary (only when with_ai_summary=true)", "example": "Your campaign is sending emails normally." } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/enrich-leads-from-supersearch": { "post": { "operationId": "enrichLeadsFromSupersearch", "summary": "Enrich leads from supersearch", "tags": [ "SuperSearchEnrichment" ], "description": "Add leads from SuperSearch to a list and enrich them. A list is automatically created if no list is provided.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "search_filters", "limit" ], "properties": { "search_filters": { "type": "object", "description": "Search filters to find leads.", "properties": { "locations": { "oneOf": [ { "type": "array", "description": "Legacy format: Array of locations to include in the search. For new integrations, use the object format with include/exclude properties.", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] } }, { "type": "object", "description": "Locations to include or exclude in the search", "properties": { "include": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to include in the search" }, "exclude": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to exclude from the search" } } } ] }, "department": { "type": "array", "items": { "type": "string", "enum": [ "Engineering", "Finance & Administration", "Human Resources", "IT & IS", "Marketing", "Operations", "Sales", "Support", "Other" ], "x-enumDescriptions": { "Engineering": "Engineering", "Finance & Administration": "Finance & Administration", "Human Resources": "Human Resources", "IT & IS": "IT & IS", "Marketing": "Marketing", "Operations": "Operations", "Sales": "Sales", "Support": "Support", "Other": "Other" }, "description": "Department of the lead", "example": "Engineering" } }, "level": { "type": "array", "items": { "type": "string", "enum": [ "C-Level", "VP-Level", "Director-Level", "Manager-Level", "Staff", "Entry level", "Mid-Senior level", "Director", "Associate", "Owner", "Executive", "Manager", "Senior", "Chief X Officer (CxO)", "Internship", "Vice President (VP)", "Unpaid / Internship", "Partner" ], "x-enumDescriptions": { "C-Level": "C-Level", "VP-Level": "VP-Level", "Director-Level": "Director-Level", "Manager-Level": "Manager-Level", "Staff": "Staff", "Entry level": "Entry level", "Mid-Senior level": "Mid-Senior level", "Director": "Director", "Associate": "Associate", "Owner": "Owner", "Executive": "Executive", "Manager": "Manager", "Senior": "Senior", "Chief X Officer (CxO)": "Chief X Officer (CxO)", "Internship": "Internship", "Vice President (VP)": "Vice President (VP)", "Unpaid / Internship": "Unpaid / Internship", "Partner": "Partner" }, "description": "Level of the lead", "example": "Entry level" } }, "employeeCount": { "type": "array", "description": "Employee count filters.", "items": { "oneOf": [ { "type": "string", "enum": [ "0 - 25", "25 - 100", "100 - 250", "250 - 1000", "1K - 10K", "10K - 50K", "50K - 100K", "> 100K" ], "description": "Legacy format: Predefined employee count range", "x-enumDescriptions": { "0 - 25": "0 - 25", "25 - 100": "25 - 100", "100 - 250": "100 - 250", "250 - 1000": "250 - 1000", "1K - 10K": "1K - 10K", "10K - 50K": "10K - 50K", "50K - 100K": "50K - 100K", "> 100K": "> 100K" }, "example": "0 - 25" }, { "type": "object", "description": "Custom employee count range", "properties": { "op": { "type": "string", "description": "Operation type.", "example": "between" }, "min": { "type": "number", "description": "Minimum employee count (inclusive), used for \"between\" and \"gte\" operations", "example": 50 }, "max": { "type": "number", "description": "Maximum employee count (inclusive), used for \"between\" and \"lte\" operations", "example": 200 } }, "required": [ "op" ], "additionalProperties": false } ] } }, "revenue": { "type": "array", "items": { "type": "string", "enum": [ "$0 - 1M", "$1 - 10M", "$10 - 50M", "$50 - 100M", "$100 - 250M", "$250 - 500M", "$500M - 1B", "> $1B" ], "x-enumDescriptions": { "$0 - 1M": "$0 - 1M", "$1 - 10M": "$1M - 10M", "$10 - 50M": "$10M - 50M", "$50 - 100M": "$50M - 100M", "$100 - 250M": "$100M - 250M", "$250 - 500M": "$250M - 500M", "$500M - 1B": "$500M - 1B", "> $1B": "> $1B" }, "description": "Revenue of the lead company", "example": "$1 - 10M" } }, "news": { "type": "array", "items": { "type": "string", "enum": [ "launches", "expands_offices_to", "hires", "partners_with", "leaves", "receives_financing", "recognized_as", "closes_offices_in", "is_developing", "has_issues_with", "promotes", "opens_new_location", "receives_award", "acquires", "invests_into_assets", "signs_new_client", "increases_headcount_by", "retires_from", "invests_into", "integrates_with", "expands_facilities", "goes_public", "sells_assets_to", "identified_as_competitor_of", "decreases_headcount_by", "expands_offices_in", "files_suit_against", "merges_with" ], "x-enumDescriptions": { "launches": "Launches", "expands_offices_to": "Expands Offices To", "hires": "Hires", "partners_with": "Partners With", "leaves": "Leaves", "receives_financing": "Receives Financing", "recognized_as": "Recognized As", "closes_offices_in": "Closes Offices In", "is_developing": "Is Developing", "has_issues_with": "Has Issues With", "promotes": "Promotes", "opens_new_location": "Opens New Location", "receives_award": "Receives Award", "acquires": "Acquires", "invests_into_assets": "Invests Into Assets", "signs_new_client": "Signs New Client", "increases_headcount_by": "Increases Headcount By", "retires_from": "Retires From", "invests_into": "Invests Into", "integrates_with": "Integrates With", "expands_facilities": "Expands Facilities", "goes_public": "Goes Public", "sells_assets_to": "Sells Assets To", "identified_as_competitor_of": "Identified As Competitor Of", "decreases_headcount_by": "Decreases Headcount By", "expands_offices_in": "Expands Offices In", "files_suit_against": "Files Suit Against", "merges_with": "Merges With" }, "description": "News about the lead company", "example": "launches" } }, "title": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "CEO" }, "description": "Titles of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "VP" }, "description": "Titles of the lead to exclude in the search" } } }, "name": { "type": "array", "items": { "type": "string", "example": "John Doe" }, "description": "Names of the lead to include in the search" }, "company_name": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "Google" }, "description": "Companies of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "Amazon" }, "description": "Companies of the lead to exclude in the search" } } }, "look_alike": { "type": "string", "description": "If set, the lead finder will find companies that are similar to the look-alike domain", "example": "google.com" }, "keyword_filter": { "type": "object", "properties": { "exclude": { "type": "string", "example": "sales" }, "include": { "type": "string", "example": "marketing" } } }, "industry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "example": "Agriculture & Mining" }, "description": "Industries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "description": "Industries of the lead company to include in the search", "example": "Agriculture & Mining" } } } }, "subIndustry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to include in the search" } } }, "domains": { "type": "array", "items": { "type": "string", "description": "Domains of the lead company to include in the search", "example": "google.com" } }, "funding_type": { "type": "array", "items": { "type": "string", "enum": [ "angel", "seed", "pre_seed", "series_a", "pre_series_a", "series_b", "pre_series_b", "series_c", "pre_series_c", "series_d", "pre_series_d", "series_e", "pre_series_e", "series_f", "pre_series_f", "series_g", "pre_series_g", "series_h", "pre_series_h", "series_i", "pre_series_i", "series_j", "pre_series_j" ], "x-enumDescriptions": { "angel": "Angel", "seed": "Seed", "pre_seed": "Pre-Seed", "series_a": "Series A", "series_b": "Series B", "series_c": "Series C", "series_d": "Series D", "series_e": "Series E", "series_f": "Series F", "series_g": "Series G", "series_h": "Series H", "series_i": "Series I", "series_j": "Series J", "pre_series_a": "Pre-Series A", "pre_series_b": "Pre-Series B", "pre_series_c": "Pre-Series C", "pre_series_d": "Pre-Series D", "pre_series_e": "Pre-Series E", "pre_series_f": "Pre-Series F", "pre_series_g": "Pre-Series G", "pre_series_h": "Pre-Series H", "pre_series_i": "Pre-Series I", "pre_series_j": "Pre-Series J" }, "description": "Funding types of the lead company to include in the search", "example": "angel" } }, "signals": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Signal category name. Uses the default 30-day freshness window.", "example": "job_change" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Signal category to filter by.", "example": "job_change" }, "period_days": { "type": "number", "description": "Freshness window in days. Only leads whose most recent signal of this category is within this window are returned. Defaults to 30 if omitted.", "example": 7 }, "keywords": { "oneOf": [ { "type": "array", "items": { "type": "string", "example": "artificial intelligence" }, "description": "Legacy flat list of keyword tokens (OR-matched across every keyword index field for the category)." }, { "type": "object", "description": "Per-field map of keyword tokens. Each property name is a keyword index field; each value is the list of tokens to OR-match within that field. Records must have at least one matching token in EACH selected field — fields act as additional filters. Example: `{ \"objection_type\": [\"security\"], \"buying_stage\": [\"consideration\"] }`.", "additionalProperties": { "type": "array", "items": { "type": "string", "example": "security" } } } ] } }, "additionalProperties": false } ] }, "description": "Filter leads by Autobound signal categories (e.g. job changes, traffic surges, LinkedIn activity). Leads matching ANY of the specified signals within the per-signal freshness window will be returned." }, "skip_owned_leads": { "type": "boolean", "description": "If set, the lead finder will skip leads that are owned by the user", "example": true }, "show_one_lead_per_company": { "type": "boolean", "description": "If set, the lead finder will show only one lead per company", "example": true }, "location_mode": { "type": "string", "enum": [ "contact", "company" ], "description": "Whether to filter/display by contact location or company HQ location. Defaults to contact.", "example": "contact" } } }, "search_name": { "type": "string", "description": "Name of the search", "example": "Tech CEOs in San Francisco" }, "work_email_enrichment": { "type": "boolean", "description": "Enable work email enrichment", "example": true }, "fully_enriched_profile": { "type": "boolean", "description": "Enable LinkedIn profile enrichment", "example": true }, "custom_flow": { "type": "array", "description": "Ordered list of providers for waterfall enrichment (enabled platforms only)", "items": { "type": "string", "example": "instantly" }, "example": [ "instantly", "findymail", "leadmagic", "icypeas", "prospeo", "wiza", "contactout" ] }, "signal_enrichment": { "type": "array", "description": "Signal categories to enrich from Autobound data. Accepts the legacy plain-string form and the richer per-signal form with a freshness window and optional keyword filter. The worker fetches matching signal records for the lead and writes the raw data into the lead payload under the signal_category key.", "items": { "oneOf": [ { "type": "string", "description": "Signal category name. Uses the default 30-day freshness window and no keyword filter.", "example": "job_change" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Signal category to enrich.", "example": "linkedin_post_contact" }, "period_days": { "type": "number", "description": "Freshness window in days. Only signals whose most recent record is within this window are attached to the lead payload. Defaults to 30 if omitted.", "example": 7 }, "keywords": { "oneOf": [ { "type": "array", "items": { "type": "string", "example": "artificial intelligence" }, "description": "Legacy flat list (OR-matched across every keyword index field for the category)." }, { "type": "object", "description": "Per-field map: each property is a keyword index field; tokens within a field are OR-matched, and fields act as additional filters (records must hit at least one token per selected field). Example: `{ \"objection_type\": [\"security\"], \"buying_stage\": [\"consideration\"] }`.", "additionalProperties": { "type": "array", "items": { "type": "string", "example": "security" } } } ] } }, "additionalProperties": false } ] } }, "resource_id": { "type": "string", "format": "uuid", "description": "ID of the list to target. A list is automatically created if not provided.", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "auto_update": { "type": "boolean", "description": "Whether to auto-update new leads", "example": true }, "evergreen": { "type": "object", "properties": { "leads_to_add": { "type": "number", "description": "Number of leads to add", "example": 100 }, "frequency": { "type": "string", "description": "Frequency of the evergreen", "example": "Daily" } } }, "skip_rows_without_email": { "type": "boolean", "description": "Whether to skip leads without email", "example": true }, "list_name": { "type": "string", "description": "Name for new list if resource_id not provided", "example": "My List" }, "limit": { "type": "number", "minimum": 1, "maximum": 1000000, "description": "Maximum number of leads to import", "example": 100 }, "ai_enrichment": { "type": "object", "description": "AI enrichment configuration. Keys are output column names, values are enrichment details.", "additionalProperties": true } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID that created this enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_id": { "type": "string", "format": "uuid", "description": "ID of the list", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_type": { "type": "number", "description": "Resource type: 1=Campaign, 2=List (default)", "enum": [ 1, 2 ], "example": 2 }, "search_filters": { "type": "object", "description": "The search filters used for enrichment", "additionalProperties": true }, "limit": { "type": "number", "description": "Maximum number of leads to import", "example": 100 }, "list_name": { "type": "string", "description": "Name of the list created", "example": "Supersearch List (22 Sep 2025)" }, "custom_flow": { "type": "array", "description": "Custom flow to apply to the enrichment", "items": { "type": "string", "example": "instantly" } } }, "required": [ "id", "organization_id", "resource_id" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/{resource_id}": { "get": { "operationId": "getEnrichmentForResource", "summary": "Get enrichment for resource", "tags": [ "SuperSearchEnrichment" ], "description": "Get the enrichment for a specific resource", "parameters": [ { "schema": { "format": "uuid", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "resource_id", "required": true, "description": "The ID of the list or campaign to retrieve the enrichment." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid", "description": "ID of the resource being enriched", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "in_progress": { "type": "boolean", "description": "Whether the enrichment is in progress", "example": false }, "has_no_leads": { "type": "boolean", "description": "Whether the enrichment for this resource returned no leads for these search filters. This is only applicable for enrichments created from SuperSearch.", "example": false }, "exists": { "type": "boolean", "description": "Whether the enrichment exists", "example": true }, "enrichment_payload": { "type": "object", "description": "Enrichment types", "minProperties": 1, "properties": { "work_email_enrichment": { "type": "boolean", "example": true }, "fully_enriched_profile": { "type": "boolean", "example": true }, "email_verification": { "type": "boolean", "example": false }, "joblisting": { "type": "boolean", "example": true }, "technologies": { "type": "boolean", "example": true }, "news": { "type": "boolean", "example": true }, "funding": { "type": "boolean", "example": true }, "engagement_score": { "type": "boolean", "example": true }, "ai_enrichment": { "type": "object", "additionalProperties": true }, "custom_flow": { "type": "array", "items": { "type": "string", "example": "leadmagic" }, "example": [ "leadmagic", "prospeo", "hunter" ] }, "limit": { "type": "number", "description": "Maximum number of leads to enrich", "example": 10 }, "autofill": { "type": "boolean", "description": "Whether to automatically fill in missing lead information", "example": true } }, "additionalProperties": true }, "auto_update": { "type": "boolean", "description": "Whether leads added to the list will be automatically enriched", "example": false }, "is_evergreen": { "type": "boolean", "description": "Whether the enrichment is evergreen", "example": false }, "search_filters": { "type": "object", "description": "Search filters used to create this enrichment (only present for enrichments created from SuperSearch)", "additionalProperties": true } }, "required": [ "resource_id", "enrichment_payload" ], "additionalProperties": false } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment": { "post": { "operationId": "createSuperSearchEnrichment", "summary": "Create an enrichment", "tags": [ "SuperSearchEnrichment" ], "description": "Create an enrichment for a specific resource (list or campaign). This is the main endpoint for adding enrichments to resources. The enrichments are automatically run after creation.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "resource_id" ], "properties": { "resource_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the resource (list or campaign)", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "type": { "type": "string", "enum": [ "work_email_enrichment", "fully_enriched_profile", "email_verification", "joblisting", "technologies", "news", "funding", "engagement_score", "ai_enrichment", "custom_flow" ], "x-enumDescriptions": { "work_email_enrichment": "Work Email Enrichment", "fully_enriched_profile": "LinkedIn Enrichment", "email_verification": "Email Verification", "joblisting": "Job Listing Enrichment", "technologies": "Technologies Enrichment", "news": "News Enrichment", "funding": "Funding Enrichment", "ai_enrichment": "AI Enrichment", "custom_flow": "Custom Flow Enrichment" }, "description": "Enrichment type to add to the resource", "example": "email_verification" }, "limit": { "type": "number", "description": "Maximum number of leads to enrich.", "minimum": 1, "maximum": 50000, "example": 100 }, "filters": { "type": "array", "description": "Filters to apply to the enrichment", "items": { "type": "object" } }, "custom_flow": { "type": "array", "description": "Custom flow to apply to the enrichment", "items": { "type": "string", "example": "instantly" } }, "integration_actions": { "type": "object", "description": "Provider-keyed integration actions to run against the resource. Mutually exclusive with `type` — either run a built-in enrichment via `type` or supply `integration_actions` to run one or more provider actions. Outer keys are provider IDs (e.g. `findymail`, `apify`); inner keys are action IDs offered by that provider (e.g. `findymail_find_email`). Each action requires a `mapping` object whose keys are the action's declared input fields and whose values are the lead column names to read from.", "minProperties": 1, "additionalProperties": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "required": [ "mapping" ], "properties": { "mapping": { "type": "object", "description": "Maps action input field keys to lead column names", "additionalProperties": { "type": "string", "example": "firstName" } } } } }, "example": { "findymail": { "findymail_find_email": { "mapping": { "first_name": "firstName", "last_name": "lastName", "domain": "website" } } } } } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "limit": { "type": "number", "description": "The maximum number of leads to enrich", "example": 100 }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID that created this enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the entity to enrich leads into", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "enrichment_payload": { "type": "object", "description": "The enrichment configuration payload", "properties": { "joblisting": { "type": "boolean", "description": "Whether job listing enrichment is enabled", "example": true }, "email_verification": { "type": "boolean", "description": "Whether email verification is enabled", "example": true }, "work_email_enrichment": { "type": "boolean", "description": "Whether work email enrichment is enabled", "example": true }, "fully_enriched_profile": { "type": "boolean", "description": "Whether fully enriched profile is enabled", "example": true }, "custom_flow": { "type": "array", "items": { "type": "string", "example": "instantly" } } }, "additionalProperties": true } }, "required": [ "id", "organization_id", "resource_id" ], "additionalProperties": false } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/{resource_id}/settings": { "patch": { "operationId": "updateEnrichmentSettingsForResource", "summary": "Update enrichment settings for resource", "tags": [ "SuperSearchEnrichment" ], "description": "Update auto-update and skip settings for a SuperSearch enrichment tied to a specific resource\n\n\nRequires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_update": { "type": "boolean", "description": "Whether new leads added to the resource will be automatically enriched", "example": true }, "skip_rows_without_email": { "type": "boolean", "description": "Whether the fully enriched profile enrichment will run even if we don't find an email", "example": true }, "is_evergreen": { "type": "boolean", "description": "Whether the enrichment is evergreen", "example": true } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "in": "path", "name": "resource_id", "required": true, "description": "Unique identifier for the resource (list or campaign)" } ], "responses": { "200": { "description": "The requested SuperSearch Enrichment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-23" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/ai": { "post": { "operationId": "createAIEnrichment", "summary": "Create AI enrichment", "tags": [ "SuperSearchEnrichment" ], "description": "Create an AI enrichment for a resource (list or campaign)\n\n\nRequires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "resource_id", "output_column", "resource_type", "model_version" ], "properties": { "resource_id": { "type": "string", "format": "uuid", "description": "Id of the resource (list or campaign) to enrich", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "output_column": { "type": "string", "description": "Name of the column where the AI enrichment results will be stored", "example": "ai_generated_content" }, "resource_type": { "type": "number", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "Campaign", "2": "List" }, "description": "Type of the entity to enrich", "example": 2 }, "input_columns": { "type": "array", "items": { "type": "string", "example": "first_name" }, "description": "List of column names to use as input data for the AI enrichment. These are the fields from your leads that will be used to generate content." }, "model_version": { "type": "string", "enum": [ "3.5", "4.0", "gpt-4o", "o3", "gpt-4.1", "gpt-4.1-mini", "gpt-5-mini", "gpt-5-nano", "gpt-5", "gpt-5.4", "claude-3.7-sonnet", "claude-3.5-sonnet", "claude-4.5-sonnet", "r1", "grok-4", "gemini-2.0-flash", "gemini-3.0-flash", "gemini-3.0-pro", "sonar", "sonar-pro", "instantly-ai-lightspeed-agent-for-web-research", "instantly-ai-lightspeed-agent-for-email-generation" ], "x-enumDescriptions": { "3.5": "GPT-3.5 Turbo - OpenAI's standard model with good performance and low cost", "gpt-5": "GPT-5 is OpenAI’s most advanced model, offering major improvements in reasoning, code quality, and user experience.", "gpt-5.4": "GPT-5.4 is the latest generation non-reasoning model, optimized for fast, high-quality responses at low latency.", "gpt-5-mini": "GPT-5 Mini is a compact version of GPT-5, designed to handle lighter-weight reasoning tasks.", "gpt-5-nano": "GPT-5-Nano is the smallest and fastest variant in the GPT-5 system, optimized for developer tools, rapid interactions, and ultra-low latency environments.", "4.0": "GPT-4 - OpenAI's advanced model with improved reasoning", "gpt-4o": "GPT-4o - OpenAI's optimized model with improved performance", "o3": "o3 is a well-rounded and powerful model across domains. It sets a new standard for math, science, coding, and visual reasoning tasks.", "gpt-4.1": "GPT-4.1 is a flagship large language model optimized for advanced instruction following, real-world software engineering, and long-context reasoning.", "gpt-4.1-mini": "GPT-4.1 Mini is a mid-sized model delivering performance competitive with GPT-4o at substantially lower latency and cost.", "claude-3.7-sonnet": "Claude 3.7 Sonnet - Anthropic's most capable model", "claude-3.5-sonnet": "Claude 3.5 Sonnet - Anthropic's balanced model", "claude-4.5-sonnet": "Claude Sonnet 4.5 is Anthropic's most advanced Sonnet model to date, optimized for real-world agents and coding workflows.", "r1": "R1 - Deepseek's advanced chat model", "grok-4": "Grok 4 - X AI's latest reasoning model", "gemini-2.0-flash": "Gemini 2.0 Flash - Google's powerful and versatile model", "gemini-3.0-flash": "Gemini 3.0 Flash - Is a high speed, high value thinking model designed for agentic workflows, multi turn chat, and coding assistance", "gemini-3.0-pro": "Gemini 3.0 Pro - Google's latest model with improved capabilities", "sonar": "Sonar - Perplexity's lightweight, affordable, fast, and simple to use model.", "sonar-pro": "Sonar Pro - Perplexity's most advanced model.", "instantly-ai-lightspeed-agent-for-web-research": "Instantly AI - LightSpeed Agent for Web Research", "instantly-ai-lightspeed-agent-for-email-generation": "Instantly AI - LightSpeed Agent for Email Generation" }, "description": "Version of the AI model to use for enrichment. Different models have different capabilities, costs, and token limits.", "example": "gpt-4o" }, "use_instantly_account": { "type": "boolean", "description": "When true, the enrichment will use Instantly's account for API calls. When false, it will use your own API keys configured in settings.", "example": true }, "overwrite": { "type": "boolean", "description": "When true, will overwrite existing values in the output column. When false, only empty fields will be enriched.", "example": false }, "auto_update": { "type": "boolean", "description": "When true, new leads added to the campaign/list will be automatically enriched using these same settings.", "example": true }, "skip_leads_without_email": { "type": "boolean", "description": "When true, leads without an email will be skipped.", "example": false }, "limit": { "type": "number", "description": "Maximum number of leads to enrich.", "minimum": 1, "maximum": 1000000, "example": 100 }, "prompt": { "type": "string", "description": "Custom prompt to guide the AI enrichment. Use {{variables}} to reference input data. Only used when templateId is not provided.", "example": "Write a personalized email to {{first_name}} from {{company_name}} about our new product" }, "template_id": { "type": "string", "description": "ID of a predefined AI prompt template to use instead of a custom prompt. Templates are reusable prompt configurations.", "example": "123" }, "status": { "type": "number", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "Job is pending processing", "2": "Job is currently being processed", "3": "Job has been completed successfully", "4": "Job processing failed" }, "description": "Status of the job", "example": 1 }, "filters": { "type": "array", "items": { "type": "object", "properties": {}, "description": "Filters to apply to the enrichment", "example": { "column_name": "email", "type": 1, "value": [ "test@test.com" ] } } } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_id": { "type": "string", "format": "uuid", "description": "ID of the resource being enriched", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_type": { "type": "number", "description": "Type of the resource (1 for Campaign, 2 for List)", "enum": [ "CAMPAIGN", "LIST", 1, 2 ], "x-enumDescriptions": { "1": "Campaign", "2": "List" }, "example": 1 }, "output_column": { "type": "string", "description": "Name of the column where results will be stored", "example": "ai_generated_content" }, "status": { "type": "number", "description": "Status of the enrichment job", "example": 1 }, "model_version": { "type": "string", "description": "AI model version used for enrichment", "example": "gpt-4o" }, "input_columns": { "type": "array", "items": { "type": "string", "example": "first_name" }, "description": "Input columns used for enrichment" }, "overwrite": { "type": "boolean", "description": "Whether to overwrite existing data", "example": false }, "auto_update": { "type": "boolean", "description": "Whether to auto-update new leads", "example": true }, "limit": { "type": "number", "description": "Maximum number of leads to process", "example": 100 }, "template_id": { "type": [ "null", "string" ], "description": "ID of the prompt template used", "example": "15762598695796759" } }, "required": [ "id", "resource_id", "resource_type", "output_column", "status", "model_version", "overwrite", "auto_update" ], "additionalProperties": false } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/ai/{resource_id}/in-progress": { "get": { "operationId": "getAiEnrichmentForResource", "summary": "Get AI enrichment for resource", "tags": [ "SuperSearchEnrichment" ], "description": "Get the AI enrichment for a specific resource\n\n\nRequires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "format": "uuid", "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "resource_id", "required": true, "description": "The ID of the list or campaign to retrieve the AI enrichment." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "organization_id": { "type": "string", "format": "uuid", "description": "Organization ID that owns this enrichment", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_id": { "type": "string", "format": "uuid", "description": "ID of the resource being enriched", "example": "01234567-89ab-cdef-0123-456789abcdef" }, "resource_type": { "type": "number", "description": "Type of the resource (1 for Campaign, 2 for List)", "enum": [ "CAMPAIGN", "LIST", 1, 2 ], "x-enumDescriptions": { "1": "Campaign", "2": "List" }, "example": 1 }, "output_column": { "type": "string", "description": "Name of the column where results will be stored", "example": "ai_generated_content" }, "status": { "type": "number", "description": "Status of the enrichment job", "example": 1 } }, "required": [ "organization_id", "resource_id", "resource_type", "output_column", "status" ] } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/history/{resource_id}": { "get": { "operationId": "getEnrichmentHistory", "summary": "Get enrichment history", "tags": [ "SuperSearchEnrichment" ], "description": "Retrieve the enrichment history for a specific resource\n\n\nRequires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "number", "example": 0 }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "number", "example": 10 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "in": "path", "name": "resource_id", "required": true, "description": "ID of the resource to retrieve" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/run": { "post": { "operationId": "runEnrichment", "summary": "Run enrichment for resource", "tags": [ "SuperSearchEnrichment" ], "description": "Run all enrichments associated with a resource for a list of leads or for all the leads that haven't been enriched yet", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resource_id": { "type": "string", "format": "uuid", "description": "The ID of the resource (list or campaign) to run enrichments for", "example": "123e4567-e89b-12d3-a456-426614174000" }, "lead_ids": { "type": "array", "items": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "maxItems": 10000, "minItems": 1, "description": "List of lead IDs to enrich (optional)" }, "limit": { "type": "integer", "description": "If set, only the first N leads will be enriched", "example": 10 }, "column_name": { "type": "string", "description": "AI enrichment column to run.", "example": "email_subject" }, "overwrite": { "type": "boolean", "description": "(AI re-run parameter) If true, run even if column has value. If false (default), only process empty/null columns. Requires column_name.", "example": false }, "starting_row": { "type": "integer", "description": "(AI re-run parameter) Starting lead position (inclusive, 1-indexed). Defaults to 1 if not provided. Requires column_name.", "minimum": 1, "example": 1 }, "count": { "type": "integer", "description": "(AI re-run parameter) How many leads to process. If not provided, processes all remaining leads from starting_row to the end. Requires column_name.", "minimum": 1, "example": 10 }, "filters": { "type": "array", "description": "Conditional formula filters to apply when processing leads. Only leads matching all filters will be enriched.", "items": { "type": "object", "properties": { "column_name": { "type": "string", "description": "Lead column key to filter on", "example": "companyName" }, "type": { "type": "number", "description": "Backend filter type enum value", "example": 1 }, "value": { "type": "array", "description": "Filter values (empty array for is-empty / is-not-empty style filters)", "items": { "type": "string", "example": "Acme" }, "example": [ "Acme" ] } }, "required": [ "column_name", "type", "value" ], "additionalProperties": false }, "example": [ { "column_name": "companyName", "type": 1, "value": [ "Acme" ] } ] } }, "required": [ "resource_id" ] } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the enrichment", "example": "123e4567-e89b-12d3-a456-426614174000" }, "resource_id": { "type": "string", "description": "The ID of the resource (list or campaign) to enrich", "example": "123e4567-e89b-12d3-a456-426614174000" }, "enrichment_payload": { "type": "object", "description": "The payload of the enrichment" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "All the leads have already been enriched" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/count-leads-from-supersearch": { "post": { "operationId": "countLeadsFromSupersearch", "summary": "Count leads from supersearch", "tags": [ "SuperSearchEnrichment" ], "description": "Count the number of leads matching a SuperSearch query without enriching them. This endpoint is intended to estimate lead availability before running an enrichment.\n\n\nRequires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "search_filters" ], "properties": { "search_filters": { "type": "object", "description": "Search filters to find leads.", "properties": { "locations": { "oneOf": [ { "type": "array", "description": "Legacy format: Array of locations to include in the search. For new integrations, use the object format with include/exclude properties.", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] } }, { "type": "object", "description": "Locations to include or exclude in the search", "properties": { "include": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to include in the search" }, "exclude": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to exclude from the search" } } } ] }, "department": { "type": "array", "items": { "type": "string", "enum": [ "Engineering", "Finance & Administration", "Human Resources", "IT & IS", "Marketing", "Operations", "Sales", "Support", "Other" ], "x-enumDescriptions": { "Engineering": "Engineering", "Finance & Administration": "Finance & Administration", "Human Resources": "Human Resources", "IT & IS": "IT & IS", "Marketing": "Marketing", "Operations": "Operations", "Sales": "Sales", "Support": "Support", "Other": "Other" }, "description": "Department of the lead", "example": "Engineering" } }, "level": { "type": "array", "items": { "type": "string", "enum": [ "C-Level", "VP-Level", "Director-Level", "Manager-Level", "Staff", "Entry level", "Mid-Senior level", "Director", "Associate", "Owner", "Executive", "Manager", "Senior", "Chief X Officer (CxO)", "Internship", "Vice President (VP)", "Unpaid / Internship", "Partner" ], "x-enumDescriptions": { "C-Level": "C-Level", "VP-Level": "VP-Level", "Director-Level": "Director-Level", "Manager-Level": "Manager-Level", "Staff": "Staff", "Entry level": "Entry level", "Mid-Senior level": "Mid-Senior level", "Director": "Director", "Associate": "Associate", "Owner": "Owner", "Executive": "Executive", "Manager": "Manager", "Senior": "Senior", "Chief X Officer (CxO)": "Chief X Officer (CxO)", "Internship": "Internship", "Vice President (VP)": "Vice President (VP)", "Unpaid / Internship": "Unpaid / Internship", "Partner": "Partner" }, "description": "Level of the lead", "example": "Entry level" } }, "employeeCount": { "type": "array", "description": "Employee count filters.", "items": { "oneOf": [ { "type": "string", "enum": [ "0 - 25", "25 - 100", "100 - 250", "250 - 1000", "1K - 10K", "10K - 50K", "50K - 100K", "> 100K" ], "description": "Legacy format: Predefined employee count range", "x-enumDescriptions": { "0 - 25": "0 - 25", "25 - 100": "25 - 100", "100 - 250": "100 - 250", "250 - 1000": "250 - 1000", "1K - 10K": "1K - 10K", "10K - 50K": "10K - 50K", "50K - 100K": "50K - 100K", "> 100K": "> 100K" }, "example": "0 - 25" }, { "type": "object", "description": "Custom employee count range", "properties": { "op": { "type": "string", "description": "Operation type.", "example": "between" }, "min": { "type": "number", "description": "Minimum employee count (inclusive), used for \"between\" and \"gte\" operations", "example": 50 }, "max": { "type": "number", "description": "Maximum employee count (inclusive), used for \"between\" and \"lte\" operations", "example": 200 } }, "required": [ "op" ], "additionalProperties": false } ] } }, "revenue": { "type": "array", "items": { "type": "string", "enum": [ "$0 - 1M", "$1 - 10M", "$10 - 50M", "$50 - 100M", "$100 - 250M", "$250 - 500M", "$500M - 1B", "> $1B" ], "x-enumDescriptions": { "$0 - 1M": "$0 - 1M", "$1 - 10M": "$1M - 10M", "$10 - 50M": "$10M - 50M", "$50 - 100M": "$50M - 100M", "$100 - 250M": "$100M - 250M", "$250 - 500M": "$250M - 500M", "$500M - 1B": "$500M - 1B", "> $1B": "> $1B" }, "description": "Revenue of the lead company", "example": "$1 - 10M" } }, "news": { "type": "array", "items": { "type": "string", "enum": [ "launches", "expands_offices_to", "hires", "partners_with", "leaves", "receives_financing", "recognized_as", "closes_offices_in", "is_developing", "has_issues_with", "promotes", "opens_new_location", "receives_award", "acquires", "invests_into_assets", "signs_new_client", "increases_headcount_by", "retires_from", "invests_into", "integrates_with", "expands_facilities", "goes_public", "sells_assets_to", "identified_as_competitor_of", "decreases_headcount_by", "expands_offices_in", "files_suit_against", "merges_with" ], "x-enumDescriptions": { "launches": "Launches", "expands_offices_to": "Expands Offices To", "hires": "Hires", "partners_with": "Partners With", "leaves": "Leaves", "receives_financing": "Receives Financing", "recognized_as": "Recognized As", "closes_offices_in": "Closes Offices In", "is_developing": "Is Developing", "has_issues_with": "Has Issues With", "promotes": "Promotes", "opens_new_location": "Opens New Location", "receives_award": "Receives Award", "acquires": "Acquires", "invests_into_assets": "Invests Into Assets", "signs_new_client": "Signs New Client", "increases_headcount_by": "Increases Headcount By", "retires_from": "Retires From", "invests_into": "Invests Into", "integrates_with": "Integrates With", "expands_facilities": "Expands Facilities", "goes_public": "Goes Public", "sells_assets_to": "Sells Assets To", "identified_as_competitor_of": "Identified As Competitor Of", "decreases_headcount_by": "Decreases Headcount By", "expands_offices_in": "Expands Offices In", "files_suit_against": "Files Suit Against", "merges_with": "Merges With" }, "description": "News about the lead company", "example": "launches" } }, "title": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "CEO" }, "description": "Titles of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "VP" }, "description": "Titles of the lead to exclude in the search" } } }, "name": { "type": "array", "items": { "type": "string", "example": "John Doe" }, "description": "Names of the lead to include in the search" }, "company_name": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "Google" }, "description": "Companies of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "Amazon" }, "description": "Companies of the lead to exclude in the search" } } }, "look_alike": { "type": "string", "description": "If set, the lead finder will find companies that are similar to the look-alike domain", "example": "google.com" }, "keyword_filter": { "type": "object", "properties": { "exclude": { "type": "string", "example": "sales" }, "include": { "type": "string", "example": "marketing" } } }, "industry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "example": "Agriculture & Mining" }, "description": "Industries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "description": "Industries of the lead company to include in the search", "example": "Agriculture & Mining" } } } }, "subIndustry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to include in the search" } } }, "domains": { "type": "array", "items": { "type": "string", "description": "Domains of the lead company to include in the search", "example": "google.com" } }, "funding_type": { "type": "array", "items": { "type": "string", "enum": [ "angel", "seed", "pre_seed", "series_a", "pre_series_a", "series_b", "pre_series_b", "series_c", "pre_series_c", "series_d", "pre_series_d", "series_e", "pre_series_e", "series_f", "pre_series_f", "series_g", "pre_series_g", "series_h", "pre_series_h", "series_i", "pre_series_i", "series_j", "pre_series_j" ], "x-enumDescriptions": { "angel": "Angel", "seed": "Seed", "pre_seed": "Pre-Seed", "series_a": "Series A", "series_b": "Series B", "series_c": "Series C", "series_d": "Series D", "series_e": "Series E", "series_f": "Series F", "series_g": "Series G", "series_h": "Series H", "series_i": "Series I", "series_j": "Series J", "pre_series_a": "Pre-Series A", "pre_series_b": "Pre-Series B", "pre_series_c": "Pre-Series C", "pre_series_d": "Pre-Series D", "pre_series_e": "Pre-Series E", "pre_series_f": "Pre-Series F", "pre_series_g": "Pre-Series G", "pre_series_h": "Pre-Series H", "pre_series_i": "Pre-Series I", "pre_series_j": "Pre-Series J" }, "description": "Funding types of the lead company to include in the search", "example": "angel" } }, "signals": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Signal category name. Uses the default 30-day freshness window.", "example": "job_change" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Signal category to filter by.", "example": "job_change" }, "period_days": { "type": "number", "description": "Freshness window in days. Only leads whose most recent signal of this category is within this window are returned. Defaults to 30 if omitted.", "example": 7 }, "keywords": { "oneOf": [ { "type": "array", "items": { "type": "string", "example": "artificial intelligence" }, "description": "Legacy flat list of keyword tokens (OR-matched across every keyword index field for the category)." }, { "type": "object", "description": "Per-field map of keyword tokens. Each property name is a keyword index field; each value is the list of tokens to OR-match within that field. Records must have at least one matching token in EACH selected field — fields act as additional filters. Example: `{ \"objection_type\": [\"security\"], \"buying_stage\": [\"consideration\"] }`.", "additionalProperties": { "type": "array", "items": { "type": "string", "example": "security" } } } ] } }, "additionalProperties": false } ] }, "description": "Filter leads by Autobound signal categories (e.g. job changes, traffic surges, LinkedIn activity). Leads matching ANY of the specified signals within the per-signal freshness window will be returned." }, "skip_owned_leads": { "type": "boolean", "description": "If set, the lead finder will skip leads that are owned by the user", "example": true }, "show_one_lead_per_company": { "type": "boolean", "description": "If set, the lead finder will show only one lead per company", "example": true }, "location_mode": { "type": "string", "enum": [ "contact", "company" ], "description": "Whether to filter/display by contact location or company HQ location. Defaults to contact.", "example": "contact" } } }, "skip_owned_leads": { "type": "boolean", "description": "Skip leads that belong to the current workspace.", "example": true }, "show_one_lead_per_company": { "type": "boolean", "description": "Return only one lead per company.", "example": true } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "number_of_leads": { "type": "number", "description": "Number of leads found for this specific search. A value of 0 indicates that no leads match the criteria. Values greater than 1,000,000 are returned as 1,000,000.", "example": 100 } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/supersearch-enrichment/preview-leads-from-supersearch": { "post": { "operationId": "previewLeadsFromSupersearch", "summary": "Preview leads from supersearch", "tags": [ "SuperSearchEnrichment" ], "description": "Preview the leads matching a SuperSearch query without enriching them\n\n\nRequires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "search_filters" ], "properties": { "search_filters": { "type": "object", "description": "Search filters to find leads.", "properties": { "locations": { "oneOf": [ { "type": "array", "description": "Legacy format: Array of locations to include in the search. For new integrations, use the object format with include/exclude properties.", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] } }, { "type": "object", "description": "Locations to include or exclude in the search", "properties": { "include": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to include in the search" }, "exclude": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "place_id": { "type": "string", "description": "Google Maps Place ID of the lead's location (https://developers.google.com/maps/documentation/places/web-service/place-id)", "example": "ChIJN1t_t3uEmsRUso9K6W47H4" }, "label": { "type": "string", "description": "Label of the lead's location", "example": "San Francisco, CA, USA" } }, "required": [ "place_id" ], "additionalProperties": false }, { "type": "object", "properties": { "city": { "type": "string", "description": "City of the lead", "example": "San Francisco" }, "state": { "type": "string", "description": "State of the lead", "example": "California" }, "country": { "type": "string", "description": "Country of the lead", "example": "United States" } }, "anyOf": [ { "required": [ "city" ] }, { "required": [ "state" ] }, { "required": [ "country" ] } ], "additionalProperties": false } ] }, "description": "Locations to exclude from the search" } } } ] }, "department": { "type": "array", "items": { "type": "string", "enum": [ "Engineering", "Finance & Administration", "Human Resources", "IT & IS", "Marketing", "Operations", "Sales", "Support", "Other" ], "x-enumDescriptions": { "Engineering": "Engineering", "Finance & Administration": "Finance & Administration", "Human Resources": "Human Resources", "IT & IS": "IT & IS", "Marketing": "Marketing", "Operations": "Operations", "Sales": "Sales", "Support": "Support", "Other": "Other" }, "description": "Department of the lead", "example": "Engineering" } }, "level": { "type": "array", "items": { "type": "string", "enum": [ "C-Level", "VP-Level", "Director-Level", "Manager-Level", "Staff", "Entry level", "Mid-Senior level", "Director", "Associate", "Owner", "Executive", "Manager", "Senior", "Chief X Officer (CxO)", "Internship", "Vice President (VP)", "Unpaid / Internship", "Partner" ], "x-enumDescriptions": { "C-Level": "C-Level", "VP-Level": "VP-Level", "Director-Level": "Director-Level", "Manager-Level": "Manager-Level", "Staff": "Staff", "Entry level": "Entry level", "Mid-Senior level": "Mid-Senior level", "Director": "Director", "Associate": "Associate", "Owner": "Owner", "Executive": "Executive", "Manager": "Manager", "Senior": "Senior", "Chief X Officer (CxO)": "Chief X Officer (CxO)", "Internship": "Internship", "Vice President (VP)": "Vice President (VP)", "Unpaid / Internship": "Unpaid / Internship", "Partner": "Partner" }, "description": "Level of the lead", "example": "Entry level" } }, "employeeCount": { "type": "array", "description": "Employee count filters.", "items": { "oneOf": [ { "type": "string", "enum": [ "0 - 25", "25 - 100", "100 - 250", "250 - 1000", "1K - 10K", "10K - 50K", "50K - 100K", "> 100K" ], "description": "Legacy format: Predefined employee count range", "x-enumDescriptions": { "0 - 25": "0 - 25", "25 - 100": "25 - 100", "100 - 250": "100 - 250", "250 - 1000": "250 - 1000", "1K - 10K": "1K - 10K", "10K - 50K": "10K - 50K", "50K - 100K": "50K - 100K", "> 100K": "> 100K" }, "example": "0 - 25" }, { "type": "object", "description": "Custom employee count range", "properties": { "op": { "type": "string", "description": "Operation type.", "example": "between" }, "min": { "type": "number", "description": "Minimum employee count (inclusive), used for \"between\" and \"gte\" operations", "example": 50 }, "max": { "type": "number", "description": "Maximum employee count (inclusive), used for \"between\" and \"lte\" operations", "example": 200 } }, "required": [ "op" ], "additionalProperties": false } ] } }, "revenue": { "type": "array", "items": { "type": "string", "enum": [ "$0 - 1M", "$1 - 10M", "$10 - 50M", "$50 - 100M", "$100 - 250M", "$250 - 500M", "$500M - 1B", "> $1B" ], "x-enumDescriptions": { "$0 - 1M": "$0 - 1M", "$1 - 10M": "$1M - 10M", "$10 - 50M": "$10M - 50M", "$50 - 100M": "$50M - 100M", "$100 - 250M": "$100M - 250M", "$250 - 500M": "$250M - 500M", "$500M - 1B": "$500M - 1B", "> $1B": "> $1B" }, "description": "Revenue of the lead company", "example": "$1 - 10M" } }, "news": { "type": "array", "items": { "type": "string", "enum": [ "launches", "expands_offices_to", "hires", "partners_with", "leaves", "receives_financing", "recognized_as", "closes_offices_in", "is_developing", "has_issues_with", "promotes", "opens_new_location", "receives_award", "acquires", "invests_into_assets", "signs_new_client", "increases_headcount_by", "retires_from", "invests_into", "integrates_with", "expands_facilities", "goes_public", "sells_assets_to", "identified_as_competitor_of", "decreases_headcount_by", "expands_offices_in", "files_suit_against", "merges_with" ], "x-enumDescriptions": { "launches": "Launches", "expands_offices_to": "Expands Offices To", "hires": "Hires", "partners_with": "Partners With", "leaves": "Leaves", "receives_financing": "Receives Financing", "recognized_as": "Recognized As", "closes_offices_in": "Closes Offices In", "is_developing": "Is Developing", "has_issues_with": "Has Issues With", "promotes": "Promotes", "opens_new_location": "Opens New Location", "receives_award": "Receives Award", "acquires": "Acquires", "invests_into_assets": "Invests Into Assets", "signs_new_client": "Signs New Client", "increases_headcount_by": "Increases Headcount By", "retires_from": "Retires From", "invests_into": "Invests Into", "integrates_with": "Integrates With", "expands_facilities": "Expands Facilities", "goes_public": "Goes Public", "sells_assets_to": "Sells Assets To", "identified_as_competitor_of": "Identified As Competitor Of", "decreases_headcount_by": "Decreases Headcount By", "expands_offices_in": "Expands Offices In", "files_suit_against": "Files Suit Against", "merges_with": "Merges With" }, "description": "News about the lead company", "example": "launches" } }, "title": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "CEO" }, "description": "Titles of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "VP" }, "description": "Titles of the lead to exclude in the search" } } }, "name": { "type": "array", "items": { "type": "string", "example": "John Doe" }, "description": "Names of the lead to include in the search" }, "company_name": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "example": "Google" }, "description": "Companies of the lead to include in the search" }, "exclude": { "type": "array", "items": { "type": "string", "example": "Amazon" }, "description": "Companies of the lead to exclude in the search" } } }, "look_alike": { "type": "string", "description": "If set, the lead finder will find companies that are similar to the look-alike domain", "example": "google.com" }, "keyword_filter": { "type": "object", "properties": { "exclude": { "type": "string", "example": "sales" }, "include": { "type": "string", "example": "marketing" } } }, "industry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "example": "Agriculture & Mining" }, "description": "Industries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Agriculture & Mining", "Business Services", "Computers & Electronics", "Consumer Services", "Education", "Energy & Utilities", "Financial Services", "Government", "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing", "Media & Entertainment", "Non-Profit", "Other", "Real Estate & Construction", "Retail", "Software & Internet", "Telecommunications", "Transportation & Storage", "Travel, Recreation, and Leisure", "Wholesale & Distribution" ], "x-enumDescriptions": { "Agriculture & Mining": "Agriculture & Mining", "Business Services": "Business Services", "Financial Services": "Financial Services", "Computers & Electronics": "Computers & Electronics", "Consumer Services": "Consumer Services", "Education": "Education", "Energy & Utilities": "Energy & Utilities", "Healthcare, Pharmaceuticals, & Biotech": "Healthcare, Pharmaceuticals, & Biotech", "Manufacturing": "Manufacturing", "Media & Entertainment": "Media & Entertainment", "Non-Profit": "Non-Profit", "Other": "Other", "Real Estate & Construction": "Real Estate & Construction", "Retail": "Retail", "Software & Internet": "Software & Internet", "Telecommunications": "Telecommunications", "Transportation & Storage": "Transportation & Storage", "Travel, Recreation, and Leisure": "Travel, Recreation, and Leisure", "Wholesale & Distribution": "Wholesale & Distribution", "Government": "Government" }, "description": "Industries of the lead company to include in the search", "example": "Agriculture & Mining" } } } }, "subIndustry": { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to exclude in the search" }, "include": { "type": "array", "items": { "type": "string", "enum": [ "Dairy", "Farming", "Fishery", "Food & Beverages", "Food Production", "Mining & Metals", "Paper & Forest Products", "Ranching", "Tobacco", "Alternative Dispute Resolution", "Animation", "Business Supplies and Equipment", "Design", "Environmental Services", "Events Services", "Executive Office", "Facilities Services", "Fund-Raising", "Graphic Design", "Human Resources", "Import and Export", "Individual & Family Services", "Information Services", "International Trade and Development", "Law Practice", "Legal Services", "Management Consulting", "Market Research", "Marketing and Advertising", "Outsourcing/Offshoring", "Professional Training & Coaching", "Program Development", "Public Relations and Communications", "Public Safety", "Security and Investigations", "Staffing and Recruiting", "Think Tanks", "Translation and Localization", "Writing and Editing", "Computer Games", "Computer Hardware", "Computer Networking", "Consumer Electronics", "Semiconductors", "Consumer Goods", "Consumer Services", "Education Management", "E-Learning", "Higher Education", "Primary/Secondary Education", "Research", "Oil & Energy", "Renewables & Environment", "Utilities", "Accounting", "Banking", "Capital Markets", "Financial Services", "Insurance", "Investment Banking", "Investment Management", "Venture Capital & Private Equity", "Defense & Space", "Government Administration", "Government Relations", "International Affairs", "Judiciary", "Law Enforcement", "Legislative Office", "Military", "Museums and Institutions", "Public Policy", "Alternative Medicine", "Biotechnology", "Health, Wellness and Fitness", "Hospital & Health Care", "Medical Devices", "Medical Practice", "Mental Health Care", "Pharmaceuticals", "Veterinary", "Automotive", "Aviation & Aerospace", "Chemicals", "Electrical/Electronic Manufacturing", "Furniture", "Industrial Automation", "Machinery", "Mechanical or Industrial Engineering", "Plastics", "Railroad Manufacture", "Shipbuilding", "Textiles", "Broadcast Media", "Media Production", "Motion Pictures and Film", "Music", "Newspapers", "Online Media", "Printing", "Publishing", "Civic & Social Organization", "Libraries", "Non-Profit Organization Management", "Philanthropy", "Political Organization", "Religious Institutions", "Arts and Crafts", "Nanotechnology", "Architecture & Planning", "Building Materials", "Civil Engineering", "Commercial Real Estate", "Construction", "Glass, Ceramics & Concrete", "Real Estate", "Apparel & Fashion", "Cosmetics", "Luxury Goods & Jewelry", "Retail", "Supermarkets", "Computer & Network Security", "Computer Software", "Information Technology and Services", "Internet", "Telecommunications", "Wireless", "Airlines/Aviation", "Logistics and Supply Chain", "Maritime", "Package/Freight Delivery", "Packaging and Containers", "Warehousing", "Transportation/Trucking/Railroad", "Entertainment", "Fine Art", "Gambling & Casinos", "Hospitality", "Leisure, Travel & Tourism", "Performing Arts", "Photography", "Recreational Facilities and Services", "Restaurants", "Sporting Goods", "Sports", "Wine and Spirits", "Wholesale" ], "x-enumDescriptions": { "Dairy": "Dairy", "Farming": "Farming", "Fishery": "Fishery", "Food & Beverages": "Food & Beverages", "Food Production": "Food Production", "Mining & Metals": "Mining & Metals", "Paper & Forest Products": "Paper & Forest Products", "Ranching": "Ranching", "Tobacco": "Tobacco", "Alternative Dispute Resolution": "Alternative Dispute Resolution", "Animation": "Animation", "Business Supplies and Equipment": "Business Supplies and Equipment", "Design": "Design", "Environmental Services": "Environmental Services", "Events Services": "Events Services", "Executive Office": "Executive Office", "Facilities Services": "Facilities Services", "Fund-Raising": "Fund-Raising", "Graphic Design": "Graphic Design", "Human Resources": "Human Resources", "Import and Export": "Import and Export", "Individual & Family Services": "Individual & Family Services", "Information Services": "Information Services", "International Trade and Development": "International Trade and Development", "Law Practice": "Law Practice", "Legal Services": "Legal Services", "Management Consulting": "Management Consulting", "Market Research": "Market Research", "Marketing and Advertising": "Marketing and Advertising", "Outsourcing/Offshoring": "Outsourcing/Offshoring", "Professional Training & Coaching": "Professional Training & Coaching", "Program Development": "Program Development", "Public Relations and Communications": "Public Relations and Communications", "Public Safety": "Public Safety", "Security and Investigations": "Security and Investigations", "Staffing and Recruiting": "Staffing and Recruiting", "Think Tanks": "Think Tanks", "Translation and Localization": "Translation and Localization", "Writing and Editing": "Writing and Editing", "Computer Games": "Computer Games", "Computer Hardware": "Computer Hardware", "Computer Networking": "Computer Networking", "Consumer Electronics": "Consumer Electronics", "Semiconductors": "Semiconductors", "Consumer Goods": "Consumer Goods", "Consumer Services": "Consumer Services", "Education Management": "Education Management", "E-Learning": "E-Learning", "Higher Education": "Higher Education", "Primary/Secondary Education": "Primary/Secondary Education", "Research": "Research", "Oil & Energy": "Oil & Energy", "Renewables & Environment": "Renewables & Environment", "Utilities": "Utilities", "Accounting": "Accounting", "Banking": "Banking", "Capital Markets": "Capital Markets", "Financial Services": "Financial Services", "Insurance": "Insurance", "Investment Banking": "Investment Banking", "Investment Management": "Investment Management", "Venture Capital & Private Equity": "Venture Capital & Private Equity", "Defense & Space": "Defense & Space", "Government Administration": "Government Administration", "Government Relations": "Government Relations", "International Affairs": "International Affairs", "Judiciary": "Judiciary", "Law Enforcement": "Law Enforcement", "Legislative Office": "Legislative Office", "Military": "Military", "Museums and Institutions": "Museums and Institutions", "Public Policy": "Public Policy", "Alternative Medicine": "Alternative Medicine", "Biotechnology": "Biotechnology", "Health, Wellness and Fitness": "Health, Wellness and Fitness", "Hospital & Health Care": "Hospital & Health Care", "Medical Devices": "Medical Devices", "Medical Practice": "Medical Practice", "Mental Health Care": "Mental Health Care", "Pharmaceuticals": "Pharmaceuticals", "Veterinary": "Veterinary", "Automotive": "Automotive", "Aviation & Aerospace": "Aviation & Aerospace", "Chemicals": "Chemicals", "Electrical/Electronic Manufacturing": "Electrical/Electronic Manufacturing", "Furniture": "Furniture", "Industrial Automation": "Industrial Automation", "Machinery": "Machinery", "Mechanical or Industrial Engineering": "Mechanical or Industrial Engineering", "Plastics": "Plastics", "Railroad Manufacture": "Railroad Manufacture", "Shipbuilding": "Shipbuilding", "Textiles": "Textiles", "Broadcast Media": "Broadcast Media", "Media Production": "Media Production", "Motion Pictures and Film": "Motion Pictures and Film", "Music": "Music", "Newspapers": "Newspapers", "Online Media": "Online Media", "Printing": "Printing", "Publishing": "Publishing", "Civic & Social Organization": "Civic & Social Organization", "Libraries": "Libraries", "Non-Profit Organization Management": "Non-Profit Organization Management", "Philanthropy": "Philanthropy", "Political Organization": "Political Organization", "Religious Institutions": "Religious Institutions", "Arts and Crafts": "Arts and Crafts", "Nanotechnology": "Nanotechnology", "Architecture & Planning": "Architecture & Planning", "Building Materials": "Building Materials", "Civil Engineering": "Civil Engineering", "Commercial Real Estate": "Commercial Real Estate", "Construction": "Construction", "Glass, Ceramics & Concrete": "Glass, Ceramics & Concrete", "Real Estate": "Real Estate", "Apparel & Fashion": "Apparel & Fashion", "Cosmetics": "Cosmetics", "Luxury Goods & Jewelry": "Luxury Goods & Jewelry", "Retail": "Retail", "Supermarkets": "Supermarkets", "Computer & Network Security": "Computer & Network Security", "Computer Software": "Computer Software", "Information Technology and Services": "Information Technology and Services", "Internet": "Internet", "Telecommunications": "Telecommunications", "Wireless": "Wireless", "Airlines/Aviation": "Airlines/Aviation", "Logistics and Supply Chain": "Logistics and Supply Chain", "Maritime": "Maritime", "Package/Freight Delivery": "Package/Freight Delivery", "Packaging and Containers": "Packaging and Containers", "Warehousing": "Warehousing", "Transportation/Trucking/Railroad": "Transportation/Trucking/Railroad", "Entertainment": "Entertainment", "Fine Art": "Fine Art", "Gambling & Casinos": "Gambling & Casinos", "Hospitality": "Hospitality", "Leisure, Travel & Tourism": "Leisure, Travel & Tourism", "Performing Arts": "Performing Arts", "Photography": "Photography", "Recreational Facilities and Services": "Recreational Facilities and Services", "Restaurants": "Restaurants", "Sporting Goods": "Sporting Goods", "Sports": "Sports", "Wine and Spirits": "Wine and Spirits", "Wholesale": "Wholesale" }, "example": "Animation" }, "description": "Subindustries of the lead company to include in the search" } } }, "domains": { "type": "array", "items": { "type": "string", "description": "Domains of the lead company to include in the search", "example": "google.com" } }, "funding_type": { "type": "array", "items": { "type": "string", "enum": [ "angel", "seed", "pre_seed", "series_a", "pre_series_a", "series_b", "pre_series_b", "series_c", "pre_series_c", "series_d", "pre_series_d", "series_e", "pre_series_e", "series_f", "pre_series_f", "series_g", "pre_series_g", "series_h", "pre_series_h", "series_i", "pre_series_i", "series_j", "pre_series_j" ], "x-enumDescriptions": { "angel": "Angel", "seed": "Seed", "pre_seed": "Pre-Seed", "series_a": "Series A", "series_b": "Series B", "series_c": "Series C", "series_d": "Series D", "series_e": "Series E", "series_f": "Series F", "series_g": "Series G", "series_h": "Series H", "series_i": "Series I", "series_j": "Series J", "pre_series_a": "Pre-Series A", "pre_series_b": "Pre-Series B", "pre_series_c": "Pre-Series C", "pre_series_d": "Pre-Series D", "pre_series_e": "Pre-Series E", "pre_series_f": "Pre-Series F", "pre_series_g": "Pre-Series G", "pre_series_h": "Pre-Series H", "pre_series_i": "Pre-Series I", "pre_series_j": "Pre-Series J" }, "description": "Funding types of the lead company to include in the search", "example": "angel" } }, "signals": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Signal category name. Uses the default 30-day freshness window.", "example": "job_change" }, { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Signal category to filter by.", "example": "job_change" }, "period_days": { "type": "number", "description": "Freshness window in days. Only leads whose most recent signal of this category is within this window are returned. Defaults to 30 if omitted.", "example": 7 }, "keywords": { "oneOf": [ { "type": "array", "items": { "type": "string", "example": "artificial intelligence" }, "description": "Legacy flat list of keyword tokens (OR-matched across every keyword index field for the category)." }, { "type": "object", "description": "Per-field map of keyword tokens. Each property name is a keyword index field; each value is the list of tokens to OR-match within that field. Records must have at least one matching token in EACH selected field — fields act as additional filters. Example: `{ \"objection_type\": [\"security\"], \"buying_stage\": [\"consideration\"] }`.", "additionalProperties": { "type": "array", "items": { "type": "string", "example": "security" } } } ] } }, "additionalProperties": false } ] }, "description": "Filter leads by Autobound signal categories (e.g. job changes, traffic surges, LinkedIn activity). Leads matching ANY of the specified signals within the per-signal freshness window will be returned." }, "skip_owned_leads": { "type": "boolean", "description": "If set, the lead finder will skip leads that are owned by the user", "example": true }, "show_one_lead_per_company": { "type": "boolean", "description": "If set, the lead finder will show only one lead per company", "example": true }, "location_mode": { "type": "string", "enum": [ "contact", "company" ], "description": "Whether to filter/display by contact location or company HQ location. Defaults to contact.", "example": "contact" } } }, "skip_owned_leads": { "type": "boolean", "description": "Skip leads that belong to the current workspace", "example": true }, "show_one_lead_per_company": { "type": "boolean", "description": "Return only one lead per company", "example": true } } } } }, "required": true }, "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "number_of_leads": { "type": "number", "description": "Number of leads found for this specific search. A value of 0 indicates that no leads match the criteria. Values greater than 1,000,000 are returned as 1,000,000.", "example": 100 }, "number_of_redacted_results": { "type": "number", "description": "Number of results that were redacted/hidden (for trial users).", "example": 0 }, "leads": { "type": "array", "description": "The leads matching the search criteria", "items": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the lead", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the lead", "example": "Doe" }, "fullName": { "type": "string", "description": "The full name of the lead", "example": "John Doe" }, "jobTitle": { "type": "string", "description": "The current job title of the lead", "example": "Software Engineer" }, "location": { "type": "string", "description": "The location of the lead (contact location or company HQ depending on location_mode filter)", "example": "San Francisco, California, United States" }, "linkedIn": { "type": "string", "description": "LinkedIn profile URL of the lead", "example": "linkedin.com/in/john-doe" }, "companyName": { "type": "string", "description": "The name of the lead’s company", "example": "Acme Corp" }, "companyLogo": { "type": "string", "description": "URL of the company logo", "example": "https://example.com/logo.png" }, "companyId": { "type": "string", "description": "The LinkedIn company ID, used for viewing company details", "example": "123456" } }, "additionalProperties": false } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/email-verification": { "post": { "operationId": "createEmailVerification", "summary": "Create email verification", "tags": [ "EmailVerification" ], "description": "If an email takes longer than 10 seconds to verify, the endpoint will return the status as `pending`. In that case, you may use the `/email-verification/:email` endpoint to check the status of the verification job.\n\nAlternatively, you can send a `webhook_url` to receive the results instead of polling the status endpoint.\n\n\nRequires one of the following scopes: `email_verifications:create`\n\n\nRequires one of the following scopes: `email_verifications:create`, `email_verifications:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateEmail Verification", "description": "The Email Verification to create", "type": "object", "properties": { "email": { "type": "string", "description": "The email address to verify", "example": "example@example.com" }, "webhook_url": { "type": "string", "description": "A webhook URL to receive the verification results. If the email verification takes more than 10 seconds we will send the results to this URL.", "example": "https://example.com/webhook" } }, "required": [ "email" ], "additionalProperties": false } } }, "required": true, "description": "The Email Verification to create" }, "responses": { "200": { "description": "The Email Verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-3" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/email-verification/{email}": { "get": { "operationId": "checkVerificationStatus", "summary": "Check an email verification status", "tags": [ "EmailVerification" ], "description": "Requires one of the following scopes: `email_verifications:read`, `email_verifications:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "email", "example": "user@example.com" }, "in": "path", "name": "email", "required": true, "description": "The email address to verify" } ], "responses": { "200": { "description": "The requested Email Verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-3" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhook-events": { "get": { "operationId": "listWebhookEvent", "summary": "List webhook event", "tags": [ "WebhookEvent" ], "description": "Requires one of the following scopes: `webhook_events:read`, `webhook_events:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "boolean", "example": true }, "in": "query", "name": "success", "required": false, "description": "Filter by success status" }, { "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "in": "query", "name": "from", "required": false, "description": "Inclusive start of the window (YYYY-MM-DD)." }, { "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "in": "query", "name": "to", "required": false, "description": "Inclusive end of the window (YYYY-MM-DD)." }, { "schema": { "type": "string", "example": "https://webhook.site/unique-url" }, "in": "query", "name": "search", "required": false, "description": "Search by exact webhook URL or lead email match" } ], "responses": { "200": { "description": "The list of Webhook Event", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Webhook Event", "items": { "$ref": "#/components/schemas/def-41" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6387-7dbf-a532-07728d4ed76d" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhook-events/{id}": { "get": { "operationId": "getWebhookEvent", "summary": "Get webhook event", "tags": [ "WebhookEvent" ], "description": "Requires one of the following scopes: `webhook_events:read`, `webhook_events:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6388-7732-b00f-3333e71d1a6a" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Webhook Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-41" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhook-events/summary": { "get": { "operationId": "getWebhookEventsSummary", "summary": "Get overview aggregates for webhook events", "tags": [ "WebhookEvent" ], "description": "Get overview aggregates for webhook events including success/failure rates", "parameters": [ { "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "in": "query", "name": "from", "required": false, "description": "Inclusive start of the window (YYYY-MM-DD)." }, { "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "in": "query", "name": "to", "required": false, "description": "Inclusive end of the window (YYYY-MM-DD)." } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_events": { "type": "number", "description": "Total number of webhook events", "example": 100 }, "successful_events": { "type": "number", "description": "Total number of successful webhook events", "example": 100 }, "failed_events": { "type": "number", "description": "Total number of failed webhook events", "example": 100 }, "success_rate": { "type": "number", "description": "Percentage (0-100) of successful webhook calls", "example": 50 }, "failure_rate": { "type": "number", "description": "Percentage (0-100) of failed webhook calls", "example": 50 } }, "required": [ "total_events", "successful_events", "failed_events", "success_rate", "failure_rate" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhook-events/summary-by-date": { "get": { "operationId": "getWebhookEventsSummaryByDate", "summary": "Get overview aggregates for webhook events by date", "tags": [ "WebhookEvent" ], "description": "Get overview aggregates for webhook events by Date for charts", "parameters": [ { "schema": { "type": "string", "format": "date", "example": "2024-01-01" }, "in": "query", "name": "from", "required": false, "description": "Inclusive start of the window (YYYY-MM-DD)." }, { "schema": { "type": "string", "format": "date", "example": "2024-01-31" }, "in": "query", "name": "to", "required": false, "description": "Inclusive end of the window (YYYY-MM-DD)." } ], "responses": { "200": { "description": "List of webhook event KPIs grouped by date", "content": { "application/json": { "schema": { "type": "object", "description": "List of webhook event KPIs grouped by date", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Date of the webhook event", "example": "2024-01-01" }, "total_events": { "type": "number", "description": "Total number of webhook events", "example": 100 }, "successful_events": { "type": "number", "description": "Total number of successful webhook events", "example": 100 }, "failed_events": { "type": "number", "description": "Total number of failed webhook events", "example": 100 }, "success_rate": { "type": "number", "description": "Success rate of the webhook events", "example": 50 } }, "required": [ "date", "total_events", "successful_events", "failed_events", "success_rate" ] } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhooks": { "get": { "operationId": "listWebhook", "summary": "List webhooks", "tags": [ "Webhook" ], "description": "List all webhooks for the workspace with optional filters", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." }, { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6396-7db1-a930-1a5593fc0156" }, "in": "query", "name": "campaign", "required": false, "description": "Filter by campaign ID" }, { "schema": { "type": "string", "enum": [ "all_events", "email_sent", "email_opened", "email_link_clicked", "reply_received", "email_bounced", "lead_unsubscribed", "campaign_completed", "account_error", "lead_neutral", "lead_interested", "lead_not_interested", "lead_meeting_booked", "lead_meeting_completed", "lead_closed", "lead_out_of_office", "lead_wrong_person" ], "example": "all_events" }, "in": "query", "name": "event_type", "required": false, "description": "Filter by event type (e.g., email_sent, lead_interested, all_events)" } ], "responses": { "200": { "description": "The list of Webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Webhook", "items": { "$ref": "#/components/schemas/def-39" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-6397-7d09-8cdd-14ab29c44641" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create webhook", "tags": [ "Webhook" ], "description": "Requires one of the following scopes: `webhooks:create`, `webhooks:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateWebhook", "description": "The Webhook to create", "type": "object", "properties": { "campaign": { "type": [ "string", "null" ], "description": "Optional campaign UUID to filter events (null = all campaigns in workspace)", "format": "uuid", "example": "019e0e40-2b00-7e1f-9534-f6fea1b4c1b2" }, "name": { "type": [ "string", "null" ], "description": "Optional user-defined name for the webhook", "example": "Zapier Positive Replies" }, "target_hook_url": { "type": "string", "description": "Target URL to send webhook payloads", "format": "uri", "pattern": "^https?://", "example": "https://webhook.site/unique-url" }, "event_type": { "type": [ "string", "null" ], "description": "Type of event to trigger the webhook (null for custom label events). Set to \"all_events\" to subscribe to all events - including custom label events", "enum": [ "all_events", "email_sent", "email_opened", "email_link_clicked", "reply_received", "email_bounced", "lead_unsubscribed", "campaign_completed", "account_error", "lead_neutral", "lead_interested", "lead_not_interested", "lead_meeting_booked", "lead_meeting_completed", "lead_closed", "lead_out_of_office", "lead_wrong_person", "lead_no_show", "supersearch_enrichment_completed" ], "example": "email_sent" }, "custom_interest_value": { "type": [ "number", "null" ], "description": "Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)", "example": 1 }, "headers": { "type": [ "object", "null" ], "description": "Optional HTTP headers to include when delivering webhook payloads (key-value pairs)", "additionalProperties": { "type": "string", "example": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" }, "example": { "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" } } }, "required": [ "target_hook_url" ], "additionalProperties": false } } }, "required": true, "description": "The Webhook to create" }, "responses": { "200": { "description": "The Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-39" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get webhook", "tags": [ "Webhook" ], "description": "Requires one of the following scopes: `webhooks:read`, `webhooks:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-6398-7a30-9c76-4b6681209b40" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-39" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchWebhook", "summary": "Patch webhook", "tags": [ "Webhook" ], "description": "Requires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign": { "type": [ "string", "null" ], "description": "Optional campaign UUID to filter events (null = all campaigns in workspace)", "format": "uuid", "example": "019e0e40-2b00-7e1f-9534-f6fea1b4c1b2" }, "name": { "type": [ "string", "null" ], "description": "Optional user-defined name for the webhook", "example": "Zapier Positive Replies" }, "target_hook_url": { "type": "string", "description": "Target URL to send webhook payloads", "format": "uri", "pattern": "^https?://", "example": "https://webhook.site/unique-url" }, "event_type": { "type": [ "string", "null" ], "description": "Type of event to trigger the webhook (null for custom label events). Set to \"all_events\" to subscribe to all events - including custom label events", "enum": [ "all_events", "email_sent", "email_opened", "email_link_clicked", "reply_received", "email_bounced", "lead_unsubscribed", "campaign_completed", "account_error", "lead_neutral", "lead_interested", "lead_not_interested", "lead_meeting_booked", "lead_meeting_completed", "lead_closed", "lead_out_of_office", "lead_wrong_person", "lead_no_show", "supersearch_enrichment_completed" ], "example": "email_sent" }, "custom_interest_value": { "type": [ "number", "null" ], "description": "Custom interest value - corresponds to LeadLabel.interest_status (used for custom label events)", "example": 1 }, "headers": { "type": [ "object", "null" ], "description": "Optional HTTP headers to include when delivering webhook payloads (key-value pairs)", "additionalProperties": { "type": "string", "example": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" }, "example": { "Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ=" } } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-639a-752c-8dcb-a56b5d9d3e42" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-39" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete webhook", "tags": [ "Webhook" ], "description": "Requires one of the following scopes: `webhooks:delete`, `webhooks:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-639a-752c-8dcb-a56c490ae151" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-39" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhooks/event-types": { "get": { "operationId": "listWebhookEventTypes", "summary": "List available event types", "tags": [ "Webhook" ], "description": "Get all available webhook event types including custom labels", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "event_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "email_sent" }, "label": { "type": "string", "example": "Email Sent" }, "type": { "type": "string", "example": "standard" } } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Test a webhook", "tags": [ "Webhook" ], "description": "Send a test payload to a webhook URL to verify it is working", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-639c-7bcf-8d10-85c5ef62adcc" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Webhook test successful" }, "response_time_ms": { "type": "number", "example": 250 }, "status_code": { "type": "number", "example": 200 }, "error": { "type": "string", "example": "Connection timeout" } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/webhooks/{id}/resume": { "post": { "operationId": "resumeWebhook", "summary": "Resume a webhook", "tags": [ "Webhook" ], "description": "Resume a webhook that was disabled due to repeated delivery failures\n\n\nRequires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-639c-7bcf-8d10-85c6083d6ad3" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "The requested Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-39" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-billing/plan-details": { "get": { "operationId": "getWorkspacePlanDetails", "summary": "Get workspace plan details", "tags": [ "WorkspaceBilling" ], "description": "Requires one of the following scopes: `workspace_billing:read`, `workspace_billing:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "The id of workspace", "example": "019e0e40-63ab-7533-9c05-c741e26a97e6" }, "organization_name": { "type": "string", "description": "The name of workspace", "example": "My Default Workspace" }, "subscriptions": { "type": "object", "properties": { "outreach": { "type": "object", "properties": { "plan_name": { "type": "string", "description": "Plan name", "example": "Free Trial" }, "addons_qty": { "type": "number", "description": "Addons total quantity", "example": 2 }, "total_lead_limit": { "type": "number", "description": "Total Outreach plan limit including addons", "example": 100 }, "current_lead_count": { "type": "number", "description": "Current number of leads counted toward the plan", "example": 10 } } } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-billing/subscription-details": { "get": { "operationId": "getWorkspaceSubscriptionDetails", "summary": "Get workspace subscription details", "tags": [ "WorkspaceBilling" ], "description": "Requires one of the following scopes: `workspace_billing:read`, `workspace_billing:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "description": "The ID of the workspace", "example": "019e0e40-63ae-7c5c-8096-26e35853f9c4" }, "interval": { "type": "string", "enum": [ "month", "year" ], "description": "The billing interval of the subscription", "example": "month" }, "quantity": { "type": "number", "description": "The quantity of subscribed items", "example": 1 }, "product_id": { "type": "string", "description": "The Id of outreach plan subscribed to", "enum": [ "pid_ls_v1", "pid_hg_v1", "pid_g_v1", "pid_g_v2", "pid_nic_v1", "pid_nic_v1_annual", "pid_gic_v1", "pid_gic_v1_annual", "pid_sic_v1", "pid_sic_v1_annual", "pid_hic_v1", "pid_hic_v1_annual", "pid_verify_v1_monthly", "pid_hv_v1", "pid_hv_v1_annual", "pid_lsv_v1", "pid_lsv_v1_annual", "pid_crm_hg", "pid_crm_g", "pid_ip_g", "pid_ip_hg", "pid_addon_25kl_v1", "pid_addon_lf_10k_v1", "pid_addon_ic_50k_v1", "pid_addon_lf_10k_v1_annual", "pid_addon_ic_50k_v1_annual" ], "x-enumDescriptions": { "pid_g_v1": "Growth Plan", "pid_g_v2": "Growth Plan V2", "pid_hg_v1": "Hypergrowth Plan", "pid_ls_v1": "LightSpeed Plan", "pid_nic_v1": "Instantly Credits Nano", "pid_nic_v1_annual": "Instantly Credits Nano Annual", "pid_gic_v1": "Instantly Credits Growth", "pid_gic_v1_annual": "Instantly Credits Growth Annual", "pid_sic_v1": "Instantly Credits Supersonic", "pid_sic_v1_annual": "Instantly Credits Supersonic Annual", "pid_hic_v1": "Instantly Credits Hyper Leads", "pid_hic_v1_annual": "Instantly Credits Hyper Leads Annual", "pid_verify_v1_monthly": "Verification Monthly", "pid_hv_v1": "Website Visitor Hypergrowth Monthly", "pid_hv_v1_annual": "Website Visitor Hypergrowth Annual", "pid_lsv_v1": "Website Visitor Lightspeed Monthly", "pid_lsv_v1_annual": "Website Visitor Lightspeed Annual", "pid_crm_hg": "CRM", "pid_crm_g": "Growth CRM", "pid_ip_g": "Inbox Placement Growth Monthly", "pid_ip_hg": "Inbox Placement Hypergrowth Monthly", "pid_addon_25kl_v1": "Addon Lead 25K", "pid_addon_lf_10k_v1": "Addon Lead Finder", "pid_addon_ic_50k_v1": "Addon Instantly Credits", "pid_addon_lf_10k_v1_annual": "Addon Lead Finder Annual", "pid_addon_ic_50k_v1_annual": "Addon Instantly Credits Annual" }, "example": "pid_g_v1" }, "product_type": { "type": "string", "enum": [ "prt_outreach", "prt_leadfinder" ], "description": "The type of product subscribed to", "example": "prt_outreach" }, "plan_type": { "type": "string", "enum": [ "plt_addon", "plt_primary" ], "description": "The type of plan - either primary plan or addon", "example": "plt_primary" }, "current_period_end": { "type": "number", "description": "Unix timestamp when the current billing period ends", "example": 1704067200 }, "cancel_at_time": { "type": [ "null", "number" ], "description": "Unix timestamp when the subscription will be canceled, null if not scheduled for cancellation", "example": 1704067200 }, "price_in_dollars": { "type": "number", "description": "The price of the subscription in dollars", "example": 97 }, "price_id": { "type": "string", "description": "The Stripe price ID associated with this subscription", "example": "price_H5UMXtIFH7Rh9K" } } } }, "all_subs_cancelled": { "type": "boolean", "description": "Indicates whether all subscriptions are either already canceled or scheduled to be canceled at the end of their current billing cycles", "example": false } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-group-members": { "post": { "operationId": "createWorkspaceGroupMember", "summary": "Create workspace group member", "tags": [ "WorkspaceGroupMember" ], "description": "This endpoint allows you to send an invitation for a sub workspace to join the admin workspace. The sub workspace will be added as a sub workspace of the admin workspace only if the sub workspace owner accepts the invitation.\n\n\nRequires one of the following scopes: `workspace_group_members:create`, `workspace_group_members:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateWorkspace Group Member", "description": "The Workspace Group Member to create", "type": "object", "properties": { "sub_workspace_id": { "type": "string", "description": "The id of the sub workspace", "format": "uuid", "example": "019e0e40-2aa2-7a3b-94cf-d0a1374c2304" } }, "required": [ "sub_workspace_id" ], "additionalProperties": false } } }, "required": true, "description": "The Workspace Group Member to create" }, "responses": { "200": { "description": "The Workspace Group Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-24" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listWorkspaceGroupMember", "summary": "List workspace group member", "tags": [ "WorkspaceGroupMember" ], "description": "Requires one of the following scopes: `workspace_group_members:read`, `workspace_group_members:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." } ], "responses": { "200": { "description": "The list of Workspace Group Member", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Workspace Group Member", "items": { "$ref": "#/components/schemas/def-24" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-63d2-7a8a-8881-bcdcb8dfc146" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-group-members/{id}": { "get": { "operationId": "getWorkspaceGroupMember", "summary": "Get workspace group member", "tags": [ "WorkspaceGroupMember" ], "description": "Requires one of the following scopes: `workspace_group_members:read`, `workspace_group_members:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-63d0-7f61-8767-2fe09fb48017" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Workspace Group Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-24" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteWorkspaceGroupMember", "summary": "Delete workspace group member", "tags": [ "WorkspaceGroupMember" ], "description": "Requires one of the following scopes: `workspace_group_members:delete`, `workspace_group_members:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-63d4-7a92-914c-d7bd415325b4" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Workspace Group Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-24" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-group-members/admin": { "get": { "operationId": "getAdminWorkspaceGroupMember", "summary": "Get the current workspace admin workspace", "tags": [ "WorkspaceGroupMember" ], "description": "Get the details of the admin workspace of the current workspace", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace_name": { "description": "The workspace name of the admin workspace. When the current workspace has no admin workspace, the workspace name will be \"Undefined\".", "type": "string", "example": "My Workspace" }, "has_admin_workspace": { "description": "Whether the current workspace has an admin workspace", "type": "boolean", "example": true }, "workspace_group_member_id": { "description": "The id of the workspace group member. You can use it to leave the admin workspace by calling the DELETE /workspace-group-members/:id endpoint", "type": "string", "example": "019e0e40-63d3-7c66-933d-8c4d872feb03" } }, "required": [ "workspace_name", "has_admin_workspace" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-members": { "post": { "operationId": "createWorkspaceMember", "summary": "Create workspace member", "tags": [ "WorkspaceMember" ], "description": "Requires one of the following scopes: `workspace_members:create`, `workspace_members:all`, `all:create`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "title": "CreateWorkspace Member", "description": "The Workspace Member to create", "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the workspace member", "format": "email", "example": "user@example.com" }, "user_email": { "type": [ "string", "null" ], "description": "Email address of the user", "format": "email", "example": "user@example.com" }, "role": { "type": "string", "description": "THe role of the workspace member defining their access level. While the \"owner\" role is listed in the enum, it cannot be created via the API, and is only assigned to the user who creates the workspace.", "enum": [ "owner", "admin", "editor", "view", "client" ], "x-enumDescriptions": { "owner": "Owner - Full access and workspace management", "admin": "Admin - Full access except workspace deletion", "editor": "Editor - Can edit but not manage workspace settings", "view": "View - Read-only access", "client": "This is a special role for users in the whitelabel (agency) view. It is not available in the API." }, "example": "editor" }, "permissions": { "type": [ "array", "null" ], "description": "The permissions for this workspace member. Used in the app to restrict access to certain sections", "items": { "type": "string", "enum": [ "dashboard.view", "campaigns.view", "campaigns.create", "campaigns.edit", "campaigns.delete", "organization.manage", "organization.integrations", "organization.billing", "organization.users.manage", "leadFinder.view", "customLeadLabels.create", "customLeadLabels.edit", "customLeadLabels.delete", "unibox.all", "analytics.view", "agency.manage", "accounts.view", "accounts.manage", "leadManagement.view", "leads.move", "crm.view", "websiteVisitors.view", "blocklist.manage", "preferences.manage", "inboxPlacement.view", "aiAgents.manage", "workspaceGroupMembers.invite", "workspaceGroupMembers.remove", "workspaceGroupMembers.leave" ], "x-enumDescriptions": { "dashboard.view": "View the dashboard", "campaigns.view": "View campaigns", "campaigns.create": "Create campaigns", "campaigns.edit": "Edit campaigns", "campaigns.delete": "Delete campaigns", "organization.manage": "Manage organization", "organization.integrations": "Manage organization integrations", "organization.billing": "Manage organization billing", "organization.users.manage": "Manage organization users", "leadFinder.view": "View lead finder", "customLeadLabels.create": "Create custom lead labels", "customLeadLabels.edit": "Edit custom lead labels", "customLeadLabels.delete": "Delete custom lead labels", "unibox.all": "View all unibox", "analytics.view": "View analytics", "agency.manage": "Manage agency", "accounts.view": "View accounts", "accounts.manage": "Manage accounts", "leadManagement.view": "View lead management", "leads.move": "Move leads", "crm.view": "View CRM", "websiteVisitors.view": "View website visitors", "blocklist.manage": "Manage blocklist", "preferences.manage": "Manage preferences", "inboxPlacement.view": "Manage inbox placement", "aiAgents.manage": "Manage AI agents", "workspaceGroupMembers.invite": "Invite workspace group members", "workspaceGroupMembers.remove": "Remove workspace group members", "workspaceGroupMembers.leave": "Leave workspace group" }, "example": "unibox.all" } } }, "required": [ "email", "role" ], "additionalProperties": false } } }, "required": true, "description": "The Workspace Member to create" }, "responses": { "200": { "description": "The Workspace Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-25" } } } }, "400": { "description": "Invalid request body (e.g. missing required fields, or invalid field values)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 400 ], "example": 400 }, "error": { "type": "string", "enum": [ "Bad Request" ], "example": "Bad Request" }, "message": { "type": "string", "example": "body must have required property 'name'" } }, "required": [ "statusCode", "error", "message" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "listWorkspaceMember", "summary": "List workspace member", "tags": [ "WorkspaceMember" ], "description": "Requires one of the following scopes: `workspace_members:read`, `workspace_members:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "example": 10 }, "in": "query", "name": "limit", "required": false, "description": "The number of items to return" }, { "schema": { "type": "string", "example": "01956fbd-0eb1-72db-a565-82977a586084" }, "in": "query", "name": "starting_after", "required": false, "description": "The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response." } ], "responses": { "200": { "description": "The list of Workspace Member", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of Workspace Member", "items": { "$ref": "#/components/schemas/def-25" } }, "next_starting_after": { "type": "string", "description": "The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API", "example": "019e0e40-63e2-71c0-a1b5-74a04ab9807e" } }, "additionalProperties": false, "required": [ "items" ] } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspace-members/{id}": { "get": { "operationId": "getWorkspaceMember", "summary": "Get workspace member", "tags": [ "WorkspaceMember" ], "description": "Requires one of the following scopes: `workspace_members:read`, `workspace_members:all`, `all:read`, `all:all`", "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-63e5-77f3-96f7-071e82f95b3e" }, "in": "path", "name": "id", "required": true, "description": "The ID of the requested item" } ], "responses": { "200": { "description": "The requested Workspace Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-25" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchWorkspaceMember", "summary": "Patch workspace member", "tags": [ "WorkspaceMember" ], "description": "Requires one of the following scopes: `workspace_members:update`, `workspace_members:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "THe role of the workspace member defining their access level. While the \"owner\" role is listed in the enum, it cannot be created via the API, and is only assigned to the user who creates the workspace.", "enum": [ "owner", "admin", "editor", "view", "client" ], "x-enumDescriptions": { "owner": "Owner - Full access and workspace management", "admin": "Admin - Full access except workspace deletion", "editor": "Editor - Can edit but not manage workspace settings", "view": "View - Read-only access", "client": "This is a special role for users in the whitelabel (agency) view. It is not available in the API." }, "example": "editor" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-63e6-7493-9be3-e29cb5bc9ce2" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to update" } ], "responses": { "200": { "description": "The updated Workspace Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-25" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteWorkspaceMember", "summary": "Delete workspace member", "tags": [ "WorkspaceMember" ], "description": "Requires one of the following scopes: `workspace_members:delete`, `workspace_members:all`, `all:delete`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "null", "example": null } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "019e0e40-63e7-7809-be32-09cdc8ae4a96" }, "in": "path", "name": "id", "required": true, "description": "The ID of the item to delete" } ], "responses": { "200": { "description": "The deleted Workspace Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-25" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspaces/current": { "get": { "operationId": "getWorkspace", "summary": "Get workspace", "tags": [ "Workspace" ], "description": "Get your current workspace details. Note that this endpoint doesn't require any parameters. It will return the workspace based on the API key sent in the headers.\n\n\nRequires one of the following scopes: `workspaces:read`, `workspaces:all`, `all:read`, `all:all`", "responses": { "200": { "description": "The requested Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-20" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "patch": { "operationId": "patchWorkspace", "summary": "Patch workspace", "tags": [ "Workspace" ], "description": "Update your current workspace details. Note that this endpoint doesn't require any parameters. It will update the workspace based on the API key sent in the headers.\n\n\nRequires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the workspace", "example": "My Workspace" }, "org_logo_url": { "type": [ "string", "null" ], "description": "URL to workspace logo", "example": "https://example.com/logo.png" } }, "required": [], "additionalProperties": false, "minProperties": 1 } } } }, "responses": { "200": { "description": "The updated Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-20" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspaces/current/whitelabel-domain": { "post": { "operationId": "addWorkspaceAgencyDomain", "summary": "Set the agency domain for the workspace", "tags": [ "Workspace" ], "description": "Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The agency domain to set for the workspace", "example": "agency.example.com" } }, "required": [ "domain" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-20" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "get": { "operationId": "getWorkspaceDomainInfo", "summary": "Get organization verified agency domain information", "tags": [ "Workspace" ], "description": "Requires one of the following scopes: `workspaces:read`, `workspaces:all`, `all:read`, `all:all`", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "description": "Whether the domain is verified", "example": true }, "name": { "type": "string", "description": "The domain name", "example": "example.com" }, "verification": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The verification type", "example": "TXT" }, "domain": { "type": "string", "description": "The domain name", "example": "example.com" }, "value": { "type": "string", "description": "The verification value", "example": "vercel-challenge=xyz123" }, "reason": { "type": "string", "description": "The reason for the verification", "example": "TXT record required for domain verification" } } } } } } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } }, "delete": { "operationId": "deleteWorkspaceDomain", "summary": "Delete organization agency domain", "tags": [ "Workspace" ], "description": "Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`", "responses": { "200": { "description": "The requested Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-20" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } }, "/api/v2/workspaces/current/change-owner": { "post": { "operationId": "changeWorkspaceOwner", "summary": "Change workspace owner", "tags": [ "Workspace" ], "description": "Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "sec": { "type": "string", "example": "SECRET_TOKEN" } }, "required": [ "email", "sec" ] } } }, "required": true }, "responses": { "200": { "description": "The requested Workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-20" } } } }, "401": { "description": "This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 401 ], "example": 401 }, "error": { "type": "string", "enum": [ "Unauthorized" ], "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing Authorization header" } }, "required": [ "statusCode", "error", "message" ] } } } }, "402": { "description": "This request cannot be fulfilled because the workspace does not have an active paid plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 402 ], "example": 402 }, "error": { "type": "string", "enum": [ "Payment Required" ], "example": "Payment Required" }, "message": { "type": "string", "example": "Workspace does not have an active paid plan" } }, "required": [ "statusCode", "error", "message" ] } } } }, "404": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 404 ], "example": 404 }, "error": { "type": "string", "enum": [ "Not Found" ], "example": "Not Found" }, "message": { "type": "string", "example": "Resource not found" } }, "required": [ "statusCode", "error", "message" ] } } } }, "429": { "description": "You have exceeded the rate limit. Please check the rate limit docs for more information.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "enum": [ 429 ], "example": 429 }, "error": { "type": "string", "enum": [ "Too Many Requests" ], "example": "Too Many Requests" }, "message": { "type": "string", "example": "Rate limit exceeded" } }, "required": [ "statusCode", "error", "message" ] } } } } } } } }, "servers": [ { "url": "https://api.instantly.ai", "description": "Instantly API Server" } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Analytics", "description": "Endpoints related to analytics", "x-displayName": "Analytics" }, { "name": "OAuth", "description": "OAuth authentication endpoints for connecting Google and Microsoft email accounts", "x-displayName": "OAuth" }, { "name": "Account", "description": "An email account that can be used to send campaigns", "x-displayName": "Account" }, { "name": "Campaign", "description": "A campaign that can be sent to a list of recipients", "x-displayName": "Campaign" }, { "name": "Email", "description": "A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox", "x-displayName": "Email" }, { "name": "EmailVerification", "description": "A single email verification", "x-displayName": "Email Verification" }, { "name": "LeadList", "description": "A list used to store leads", "x-displayName": "Lead List" }, { "name": "InboxPlacementTest", "description": "An inbox placement test", "x-displayName": "Inbox Placement Test" }, { "name": "InboxPlacementAnalytics", "description": "Analytics data for individual emails in inbox placement tests", "x-displayName": "Inbox Placement Analytics" }, { "name": "InboxPlacementBlacklist&SpamAssassinReport", "description": "Report data for an inbox placement test", "x-displayName": "Inbox Placement Blacklist & SpamAssassin Report" }, { "name": "APIKey", "description": "API Key", "x-displayName": "API Key" }, { "name": "AccountCampaignMapping", "description": "Account Campaign Mapping", "x-displayName": "Account Campaign Mapping" }, { "name": "Lead", "description": "A lead entity representing an individual lead", "x-displayName": "Lead" }, { "name": "BackgroundJob", "description": "A background job that can be used to perform long-running tasks", "x-displayName": "Background Job" }, { "name": "CustomTag", "description": "A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.", "x-displayName": "Custom Tag" }, { "name": "CustomTagMapping", "description": "This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (`tag_id` field) with the email account (`resource_id` field). You can use it to see which tag si connected to which resource.", "x-displayName": "Custom Tag Mapping" }, { "name": "BlockListEntry", "description": "A blocked email or domain", "x-displayName": "Block List Entry" }, { "name": "LeadLabel", "description": "A custom label for categorizing and managing leads", "x-displayName": "Lead Label" }, { "name": "Workspace", "description": "A workspace entity representing a workspace", "x-displayName": "Workspace" }, { "name": "SuperSearchEnrichment", "description": "An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it.", "x-displayName": "SuperSearch Enrichment" }, { "name": "WorkspaceGroupMember", "description": "A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.", "x-displayName": "Workspace Group Member" }, { "name": "WorkspaceMember", "description": "A member of a workspace with associated user details", "x-displayName": "Workspace Member" }, { "name": "CampaignSubsequence", "description": "A subsequence entity representing a follow-up sequence", "x-displayName": "Campaign Subsequence" }, { "name": "AuditLog", "description": "Audit log records for tracking system activities", "x-displayName": "Audit Log" }, { "name": "Webhook", "description": "A webhook subscription for receiving event notifications", "x-displayName": "Webhook" }, { "name": "WebhookEvent", "description": "A webhook event that was sent or attempted to be sent", "x-displayName": "Webhook Event" }, { "name": "DFYEmailAccountOrder", "description": "A Done-For-You email account order", "x-displayName": "DFY Email Account Order" }, { "name": "CustomPromptTemplate", "description": "Custom prompt templates for creating custom prompts", "x-displayName": "Custom Prompt Template" }, { "name": "SalesFlow", "description": "Manages how sales users view and interact with campaign and lead lists within the sales flow.", "x-displayName": "Sales Flow" }, { "name": "EmailTemplate", "description": "A campaign email template", "x-displayName": "Email Template" }, { "name": "WorkspaceBilling", "description": "Workspace Billing", "x-displayName": "Workspace Billing" }, { "name": "CRMActions", "description": "CRM related actions", "x-displayName": "CRM Actions" } ] }