> ## Documentation Index
> Fetch the complete documentation index at: https://docs.foxreach.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Lead

> Create a new lead in your workspace.

## Request Body

<ParamField body="email" type="string" required>
  Email address of the lead. Must be unique within the workspace.
</ParamField>

<ParamField body="firstName" type="string">
  First name.
</ParamField>

<ParamField body="lastName" type="string">
  Last name.
</ParamField>

<ParamField body="company" type="string">
  Company name.
</ParamField>

<ParamField body="title" type="string">
  Job title.
</ParamField>

<ParamField body="phone" type="string">
  Phone number.
</ParamField>

<ParamField body="linkedinUrl" type="string">
  LinkedIn profile URL.
</ParamField>

<ParamField body="website" type="string">
  Website URL.
</ParamField>

<ParamField body="tags" type="array">
  List of tag names to apply to the lead (e.g., `["enterprise", "conference"]`).
</ParamField>

<ParamField body="customFields" type="object">
  Custom key-value fields for additional data.
</ParamField>

<ParamField body="notes" type="string">
  Freeform notes about the lead.
</ParamField>

<ParamField body="source" type="string" default="api">
  Source tracking (e.g., `api`, `csv_import`, `manual`).
</ParamField>

<ParamField body="status" type="string" default="active">
  Initial status: `active`, `bounced`, `unsubscribed`, or `replied`.
</ParamField>

## Response

Returns the created lead object with a `201` status code.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.foxreach.io/api/v1/leads" \
    -H "X-API-Key: otr_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "company": "TechCorp",
      "title": "CTO",
      "customFields": { "industry": "FinTech", "employees": "50-100" }
    }'
  ```

  ```python Python SDK theme={null}
  from foxreach import FoxReach, LeadCreate

  client = FoxReach(api_key="otr_your_key")

  lead = client.leads.create(
      LeadCreate(
          email="jane@example.com",
          first_name="Jane",
          last_name="Smith",
          company="TechCorp",
          title="CTO",
          custom_fields={"industry": "FinTech", "employees": "50-100"},
      )
  )
  ```

  ```typescript TypeScript SDK theme={null}
  import { FoxReach } from "foxreach";

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

  const lead = await client.leads.create({
    email: "jane@example.com",
    firstName: "Jane",
    lastName: "Smith",
    company: "TechCorp",
    title: "CTO",
    customFields: { industry: "FinTech", employees: "50-100" },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "id": "cld_xyz789",
      "email": "jane@example.com",
      "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"
    }
  }
  ```
</ResponseExample>

## 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).

<Tip>
  Importing many leads at once? Use [`POST /api/v1/leads/import`](/api-reference/leads/import-leads) 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.
</Tip>

For client-side patterns (`Retry-After`, exponential backoff, monitoring `X-RateLimit-Remaining`), see [Rate Limiting](/rate-limiting).