Bulk Import Leads

curl -X POST "https://api.foxreach.io/api/v1/leads/import" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreSoftDeleted": true,
    "leads": [
      {
        "email": "[email protected]",
        "firstName": "Alex",
        "company": "Acme",
        "tags": ["enterprise", "q1-outreach"],
        "customFields": { "industry": "fintech" }
      },
      {
        "email": "[email protected]",
        "firstName": "Sam",
        "title": "Head of RevOps"
      }
    ]
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

result = client.leads.bulk_import(
    leads=[
        LeadCreate(
            email="[email protected]",
            first_name="Alex",
            company="Acme",
            tags=["enterprise", "q1-outreach"],
            custom_fields={"industry": "fintech"},
        ),
        LeadCreate(
            email="[email protected]",
            first_name="Sam",
            title="Head of RevOps",
        ),
    ],
    restore_soft_deleted=True,
)

print(result.created, result.restored, result.duplicates, result.errors)

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });

const result = await client.leads.bulkImport(
  [
    {
      email: "[email protected]",
      firstName: "Alex",
      company: "Acme",
      tags: ["enterprise", "q1-outreach"],
      customFields: { industry: "fintech" },
    },
    { email: "[email protected]", firstName: "Sam", title: "Head of RevOps" },
  ],
  { restoreSoftDeleted: true },
);

console.log(result.created, result.restored, result.duplicates, result.errors);

{
  "data": {
    "created": 2,
    "restored": 0,
    "duplicates": 0,
    "errors": 0,
    "duplicateEmails": [],
    "errorDetails": []
  }
}

POST

api

leads

import

curl -X POST "https://api.foxreach.io/api/v1/leads/import" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreSoftDeleted": true,
    "leads": [
      {
        "email": "[email protected]",
        "firstName": "Alex",
        "company": "Acme",
        "tags": ["enterprise", "q1-outreach"],
        "customFields": { "industry": "fintech" }
      },
      {
        "email": "[email protected]",
        "firstName": "Sam",
        "title": "Head of RevOps"
      }
    ]
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

result = client.leads.bulk_import(
    leads=[
        LeadCreate(
            email="[email protected]",
            first_name="Alex",
            company="Acme",
            tags=["enterprise", "q1-outreach"],
            custom_fields={"industry": "fintech"},
        ),
        LeadCreate(
            email="[email protected]",
            first_name="Sam",
            title="Head of RevOps",
        ),
    ],
    restore_soft_deleted=True,
)

print(result.created, result.restored, result.duplicates, result.errors)

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });

const result = await client.leads.bulkImport(
  [
    {
      email: "[email protected]",
      firstName: "Alex",
      company: "Acme",
      tags: ["enterprise", "q1-outreach"],
      customFields: { industry: "fintech" },
    },
    { email: "[email protected]", firstName: "Sam", title: "Head of RevOps" },
  ],
  { restoreSoftDeleted: true },
);

console.log(result.created, result.restored, result.duplicates, result.errors);

{
  "data": {
    "created": 2,
    "restored": 0,
    "duplicates": 0,
    "errors": 0,
    "duplicateEmails": [],
    "errorDetails": []
  }
}

Use this endpoint instead of looping Create Lead when you have a list of leads to ingest. You get back a single response with counts of created, restored, duplicates, and errors — no per-row 409s, no manual retry logic.

Request Body

array

required

Array of lead objects. Each item supports the same fields as Create Lead — at minimum email, plus any of firstName, lastName, company, title, phone, linkedinUrl, website, notes, source, status, customFields, tags. Maximum 1000 leads per request.

boolean

default:"true"

When true (default), leads with the same email as a previously soft-deleted record are restored (their deletedAt is cleared and the existing fields are merged with the request payload). When false, those rows are counted as duplicates instead.

Response

{
  "data": {
    "created":        142,
    "restored":         8,
    "duplicates":      12,
    "errors":           1,
    "duplicateEmails": ["[email protected]", "..."],
    "errorDetails":    [{ "email": "", "reason": "empty email" }]
  }
}

Field	Description
`created`	Net-new lead rows inserted.
`restored`	Previously soft-deleted rows whose `deletedAt` was cleared and whose campaign membership counts were re-incremented.
`duplicates`	Rows skipped because an active lead with that email already exists, or because the same email appeared earlier in the request.
`errors`	Rows skipped due to validation issues (empty email, etc.).
`duplicateEmails`	First 100 duplicate emails for debugging.
`errorDetails`	First 100 invalid rows with reasons.

In-request duplicate emails are caught — the first occurrence wins, subsequent rows with the same email are counted as duplicates.

curl -X POST "https://api.foxreach.io/api/v1/leads/import" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreSoftDeleted": true,
    "leads": [
      {
        "email": "[email protected]",
        "firstName": "Alex",
        "company": "Acme",
        "tags": ["enterprise", "q1-outreach"],
        "customFields": { "industry": "fintech" }
      },
      {
        "email": "[email protected]",
        "firstName": "Sam",
        "title": "Head of RevOps"
      }
    ]
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

result = client.leads.bulk_import(
    leads=[
        LeadCreate(
            email="[email protected]",
            first_name="Alex",
            company="Acme",
            tags=["enterprise", "q1-outreach"],
            custom_fields={"industry": "fintech"},
        ),
        LeadCreate(
            email="[email protected]",
            first_name="Sam",
            title="Head of RevOps",
        ),
    ],
    restore_soft_deleted=True,
)

print(result.created, result.restored, result.duplicates, result.errors)

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });

const result = await client.leads.bulkImport(
  [
    {
      email: "[email protected]",
      firstName: "Alex",
      company: "Acme",
      tags: ["enterprise", "q1-outreach"],
      customFields: { industry: "fintech" },
    },
    { email: "[email protected]", firstName: "Sam", title: "Head of RevOps" },
  ],
  { restoreSoftDeleted: true },
);

console.log(result.created, result.restored, result.duplicates, result.errors);

{
  "data": {
    "created": 2,
    "restored": 0,
    "duplicates": 0,
    "errors": 0,
    "duplicateEmails": [],
    "errorDetails": []
  }
}

Errors

Status	Description
`400`	More than 1000 leads in `leads`, or empty array
`402`	Workspace plan contact limit would be exceeded by the request
`422`	Invalid request body (malformed JSON, bad field types)
`429`	Rate limit exceeded — see Rate Limit section below

Rate Limit

100 requests per minute, per API key (the same v1 limit as every other endpoint).
A bulk import of 1000 leads counts as 1 request, not 1000. This is the whole point of the endpoint — your effective ingestion rate goes from 100 leads/minute (looping single create) to 100,000 leads/minute (looping this endpoint).
Response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers.

For client-side retry/backoff patterns, see Rate Limiting.

When to use this vs. Create Lead

Use Create Lead when…	Use Bulk Import when…
You have a single lead from a form or webhook	You’re ingesting from a CSV, spreadsheet, or external data source
You need the full lead row in the response	You need a structured dedup report
You’re inserting fewer than ~10 rows	You have anywhere from 10 to 1000 rows per call
You want a 409 conflict surfaced per row	You want to keep going past dups and restore soft-deleted

Leads

Campaigns

Sequences

Campaign Leads

Campaign Accounts

Inbox

Email Accounts

Templates

Analytics

Webhooks API

Request Body

Response

Errors

Rate Limit

When to use this vs. Create Lead

​Request Body

​Response

​Errors

​Rate Limit

​When to use this vs. Create Lead

Request Body

Response

Errors

Rate Limit

When to use this vs. Create Lead