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

# Create Lead

> Create a new lead

## Endpoint

<Card>
  <strong>POST</strong> `/backend/leads`
</Card>

## Body Parameters

<ParamField body="name" type="string" required>
  Lead's full name
</ParamField>

<ParamField body="phone" type="string" required>
  Phone with country code (E.164 format)
</ParamField>

<ParamField body="email" type="string">
  Email address
</ParamField>

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

<ParamField body="status_id" type="string">
  Initial status ID
</ParamField>

<ParamField body="tag_ids" type="array">
  Array of tag IDs
</ParamField>

<ParamField body="custom_fields" type="object">
  Custom field values
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/leads" \
    -H "Authorization: Bearer your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Smith",
      "phone": "+15551234567",
      "email": "john@example.com",
      "company": "XYZ Company",
      "status_id": "status-uuid",
      "tag_ids": ["tag-uuid-1", "tag-uuid-2"],
      "custom_fields": {
        "source": "website",
        "interest": "product-a"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/backend/leads', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Smith',
      phone: '+15551234567',
      email: 'john@example.com',
      company: 'XYZ Company',
      status_id: 'status-uuid',
      tag_ids: ['tag-uuid-1', 'tag-uuid-2'],
      custom_fields: {
        source: 'website',
        interest: 'product-a'
      }
    })
  });
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "new-lead-uuid",
    "name": "John Smith",
    "phone": "+15551234567",
    "email": "john@example.com",
    "company": "XYZ Company",
    "status": {
      "id": "status-uuid",
      "name": "New",
      "color": "#10B981"
    },
    "tags": [
      {
        "id": "tag-uuid-1",
        "name": "VIP",
        "color": "#F59E0B"
      }
    ],
    "custom_fields": {
      "source": "website",
      "interest": "product-a"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## Possible Errors

| Code               | Description              |
| ------------------ | ------------------------ |
| `VALIDATION_ERROR` | Invalid data             |
| `ALREADY_EXISTS`   | Phone already registered |
| `NOT_FOUND`        | Status or tag not found  |