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

# Create a 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`).

## Example

```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()
```

## Response

**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"
  }
}
```

**400 Bad Request**

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "At least phone or email is required"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.