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

# Lead

> Creates a new lead in your workspace.

# Create a Lead

Creates a new lead in your workspace. At least a phone number or email address is required.

## Request

`POST /v1/leads`

### Body Parameters

| Parameter          | Type   | Required    | Description                                         |
| ------------------ | ------ | ----------- | --------------------------------------------------- |
| `first_name`       | string | No          | First name of the lead                              |
| `last_name`        | string | No          | Last name of the lead                               |
| `email`            | string | Conditional | Email address (required if no phone)                |
| `phone`            | string | Conditional | Phone number in E.164 format (required if no email) |
| `company_name`     | string | No          | Company or organization name                        |
| `title`            | string | No          | Job title                                           |
| `linkedin_url`     | string | No          | LinkedIn profile URL                                |
| `company_website`  | string | No          | Company website URL                                 |
| `job_description`  | string | No          | Job description or role details                     |
| `company_size`     | string | No          | Company size range (e.g., "11-50")                  |
| `custom_variables` | object | No          | Key-value pairs for custom data                     |
| `metadata`         | object | No          | Additional metadata as JSON                         |

<Note>
  At least one of `phone` or `email` must be provided. Phone numbers should be in E.164 format (e.g., `+33612345678`).
</Note>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads" \
    -H "Authorization: Bearer rchd_live_xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acme.com",
      "phone": "+33612345678",
      "company_name": "Acme Corp",
      "title": "VP Sales"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer rchd_live_xxxxxxxxxxxx",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        first_name: "John",
        last_name: "Doe",
        email: "john@acme.com",
        phone: "+33612345678",
        company_name: "Acme Corp",
        title: "VP Sales"
      })
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://kdjmltmhxvvmiuehafgl.supabase.co/functions/v1/api-gateway/v1/leads",
      headers={
          "Authorization": "Bearer rchd_live_xxxxxxxxxxxx",
          "Content-Type": "application/json"
      },
      json={
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@acme.com",
          "phone": "+33612345678",
          "company_name": "Acme Corp",
          "title": "VP Sales"
      }
  )
  data = response.json()
  ```
</CodeGroup>

## Response

<Tabs>
  <Tab title="201 Created">
    ```json theme={null}
    {
      "data": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@acme.com",
        "phone": "+33612345678",
        "company_name": "Acme Corp",
        "title": "VP Sales",
        "status": "pending",
        "source": "api",
        "created_at": "2026-03-21T10:00:00.000Z"
      }
    }
    ```
  </Tab>

  <Tab title="400 Bad Request">
    ```json theme={null}
    {
      "error": {
        "code": "bad_request",
        "message": "At least phone or email is required"
      }
    }
    ```
  </Tab>
</Tabs>