Skip to main content
PATCH
/
api
/
v1
/
leads
/
{lead_id}
curl -X PATCH "https://api.foxreach.io/api/v1/leads/cld_abc123" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Acme Corp (acquired)",
    "title": "SVP of Sales"
  }'

{
  "data": {
    "id": "cld_abc123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Corp (acquired)",
    "title": "SVP of Sales",
    "phone": "+1-555-0100",
    "linkedinUrl": "https://linkedin.com/in/johndoe",
    "website": "https://acme.com",
    "customFields": { "industry": "SaaS" },
    "notes": null,
    "source": "csv_import",
    "status": "active",
    "lastContactedAt": null,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-16T08:00:00"
  }
}

​
Path Parameters

​
lead_id
string
required
The unique identifier of the lead.

​
Request Body

All fields are optional. Only include the fields you want to update.
​
email
string
New email address. 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.
​
customFields
object
Custom key-value fields (replaces entire object).
​
notes
string
Freeform notes.
​
status
string
Lead status.
curl -X PATCH "https://api.foxreach.io/api/v1/leads/cld_abc123" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Acme Corp (acquired)",
    "title": "SVP of Sales"
  }'

{
  "data": {
    "id": "cld_abc123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "company": "Acme Corp (acquired)",
    "title": "SVP of Sales",
    "phone": "+1-555-0100",
    "linkedinUrl": "https://linkedin.com/in/johndoe",
    "website": "https://acme.com",
    "customFields": { "industry": "SaaS" },
    "notes": null,
    "source": "csv_import",
    "status": "active",
    "lastContactedAt": null,
    "createdAt": "2025-01-15T10:30:00",
    "updatedAt": "2025-01-16T08:00:00"
  }
}

​
Errors

StatusDescription
404Lead not found
409A lead with the new email already exists in the workspace

​
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).
For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.