Create Lead

curl -X POST "https://api.foxreach.io/api/v1/leads" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "customFields": { "industry": "FinTech", "employees": "50-100" }
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

lead = client.leads.create(
    LeadCreate(
        email="[email protected]",
        first_name="Jane",
        last_name="Smith",
        company="TechCorp",
        title="CTO",
        custom_fields={"industry": "FinTech", "employees": "50-100"},
    )
)

import { FoxReach } from "foxreach";

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

const lead = await client.leads.create({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Smith",
  company: "TechCorp",
  title: "CTO",
  customFields: { industry: "FinTech", employees: "50-100" },
});

{
  "data": {
    "id": "cld_xyz789",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "phone": null,
    "linkedinUrl": null,
    "website": null,
    "customFields": { "industry": "FinTech", "employees": "50-100" },
    "notes": null,
    "source": "api",
    "status": "active",
    "lastContactedAt": null,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-15T10:30:00"
  }
}

POST

api

leads

curl -X POST "https://api.foxreach.io/api/v1/leads" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "customFields": { "industry": "FinTech", "employees": "50-100" }
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

lead = client.leads.create(
    LeadCreate(
        email="[email protected]",
        first_name="Jane",
        last_name="Smith",
        company="TechCorp",
        title="CTO",
        custom_fields={"industry": "FinTech", "employees": "50-100"},
    )
)

import { FoxReach } from "foxreach";

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

const lead = await client.leads.create({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Smith",
  company: "TechCorp",
  title: "CTO",
  customFields: { industry: "FinTech", employees: "50-100" },
});

{
  "data": {
    "id": "cld_xyz789",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "phone": null,
    "linkedinUrl": null,
    "website": null,
    "customFields": { "industry": "FinTech", "employees": "50-100" },
    "notes": null,
    "source": "api",
    "status": "active",
    "lastContactedAt": null,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-15T10:30:00"
  }
}

Request Body

string

required

Email address of the lead. Must be unique within the workspace.

string

First name.

string

Last name.

string

Company name.

string

Job title.

string

Phone number.

string

LinkedIn profile URL.

string

Website URL.

array

List of tag names to apply to the lead (e.g., ["enterprise", "conference"]).

object

Custom key-value fields for additional data.

string

Freeform notes about the lead.

string

default:"api"

Source tracking (e.g., api, csv_import, manual).

string

default:"active"

Initial status: active, bounced, unsubscribed, or replied.

Response

Returns the created lead object with a 201 status code.

curl -X POST "https://api.foxreach.io/api/v1/leads" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "customFields": { "industry": "FinTech", "employees": "50-100" }
  }'

from foxreach import FoxReach, LeadCreate

client = FoxReach(api_key="otr_your_key")

lead = client.leads.create(
    LeadCreate(
        email="[email protected]",
        first_name="Jane",
        last_name="Smith",
        company="TechCorp",
        title="CTO",
        custom_fields={"industry": "FinTech", "employees": "50-100"},
    )
)

import { FoxReach } from "foxreach";

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

const lead = await client.leads.create({
  email: "[email protected]",
  firstName: "Jane",
  lastName: "Smith",
  company: "TechCorp",
  title: "CTO",
  customFields: { industry: "FinTech", employees: "50-100" },
});

{
  "data": {
    "id": "cld_xyz789",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "TechCorp",
    "title": "CTO",
    "phone": null,
    "linkedinUrl": null,
    "website": null,
    "customFields": { "industry": "FinTech", "employees": "50-100" },
    "notes": null,
    "source": "api",
    "status": "active",
    "lastContactedAt": null,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-15T10:30:00"
  }
}

Errors

Status	Description
`409`	A lead with this email already exists in the workspace
`422`	Invalid request body (e.g., invalid email format)
`429`	Rate limit exceeded — see Rate Limit section below

Rate Limit

This endpoint is subject to the v1 API rate limit:

100 requests per minute, per API key (fixed 60-second window).
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch seconds).
A 429 response includes a Retry-After header (seconds until the bucket resets).

Importing many leads at once? Use POST /api/v1/leads/import instead — up to 1000 leads in a single request, with a structured dedup report and automatic restoration of soft-deleted leads. One bulk call costs 1 toward your rate limit; a 1000-row loop of single creates would burn your entire budget for 10 minutes.

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Leads

Campaigns

Sequences

Campaign Leads

Campaign Accounts

Inbox

Email Accounts

Templates

Analytics

Webhooks API

Request Body

Response

Errors

Rate Limit

​Request Body

​Response

​Errors

​Rate Limit

Request Body

Response

Errors

Rate Limit