POST /leads/bulk

Authentication

Send your organization API key as a Bearer credential.

Authorization: Bearer YOUR_API_KEY

Body

application/json

Bulk lead data

campaign string required

UUID of the campaign to which the leads will be associated

Example: 550e8400-e29b-41d4-a716-446655440000
items object[] required

Lead data items

Show child attributes Hide child attributes
items.email string required

Email address of the lead

Example: john.doe@example.com
items.first_name string

First name of the lead

Example: John
items.last_name string

Last name of the lead

Example: Doe
items.company string

Company name of the lead

Example: Coldy
items.website string

Website of the lead

Example: https://coldy.ai
items.personalization string

Personalization text for the lead

Example: Hi John, I saw you work at Coldy.ai and thought this might be useful...
items.custom_variables object

Custom variables as key-value pairs where key is field name and value is its value

Example: {"position":"CTO","linkedin":"https://linkedin.com/in/coldy.ai"}
skip_if_in_campaign object

Whether to skip if the lead is already in the campaign (default: true)

Example: true
skip_if_in_workspace object

Whether to skip if the lead is already in the workspace (default: true)

Example: true
skip_if_in_blacklist object

Whether to skip if the lead is in blacklist (default: true)

Example: true

Response

application/json

Bulk lead creation result

created number required

Number of leads created

Example: 2
skipped number required

Number of leads skipped

Example: 1
leads object[] required

Created leads

Show child attributes Hide child attributes
leads.id number required

ID of the lead

Example: 1
leads.email string required

Email address of the lead

Example: john.doe@example.com
leads.first_name string required

First name of the lead

Example: John
leads.last_name string required

Last name of the lead

Example: Doe
leads.company string required

Company of the lead

Example: OpenAI
leads.website string required

Website of the lead

Example: https://openai.com
leads.personalization string required

Personalization text

Example: Hi John, I saw you work at OpenAI…
leads.sender string required

The email account from which the email was sent

Example: outbound@coldy.ai
leads.verification_status string required

Verification status of the email

Allowed values: valid, unknown, accept_all, invalid, disposable, not_verified

Example: valid
leads.status string required

Current status of the lead

Allowed values: Not contacted, Sent, Bounce, Replied, Opened

Example: Not contacted
leads.campaign_id string required

ID of the associated campaign

Example: 550e8400-e29b-41d4-a716-446655440000
leads.id_previous_sending_sequence number required

ID of previous sending sequence

Example: 0
leads.amount_sequences_sent number required

Number of sequences already sent

Example: 2
leads.date_last_sequence_send string required

Date of the last sequence sent

Example: 2025-10-01T12:34:56.000Z
leads.reply_text string required

Reply text if lead responded

Example: Sure, let’s talk next week.
leads.reply_status string required

Reply status

Example: positive
leads.reply_status_tag_id number required

ID of the attached reply tag

Example: 12
leads.stop_sending boolean required

Whether sending is stopped for this lead

Example: false
leads.stop_sending_type string required

Type of stop sending rule applied

Example: manual
leads.chosen_sender number required

Chosen sender account ID

Example: 101
leads.provider string required

Provider used for sending

Example: gmail
skipped_items object[] required

Skipped lead items and reasons

Show child attributes Hide child attributes
skipped_items.index number required

Zero-based index of the skipped item in request items

Example: 1
skipped_items.email string required

Email address of the skipped lead

Example: john.doe@example.com
skipped_items.reason string required

Reason why the lead was skipped

Allowed values: blacklist, workspace_duplicate, campaign_duplicate

Example: campaign_duplicate