Skip to main content
POST
/
api
/
v1
/
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" }
  }'

{
  "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

​
email
string
required
Email address of the lead. Must be unique within the workspace.
​
firstName
string
First name.
​
lastName
string
Last name.
​
company
string
Company name.
​
title
string
Job title.
​
phone
string
Phone number.
​
linkedinUrl
string
LinkedIn profile URL.
​
website
string
Website URL.
​
tags
array
List of tag names to apply to the lead (e.g., ["enterprise", "conference"]).
​
customFields
object
Custom key-value fields for additional data.
​
notes
string
Freeform notes about the lead.
​
source
string
default:"api"
Source tracking (e.g., api, csv_import, manual).
​
status
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" }
  }'

{
  "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

StatusDescription
409A lead with this email already exists in the workspace
422Invalid request body (e.g., invalid email format)
429Rate 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.