# Create a lead

> Records a lead against a chatbot, optionally linked to a conversation, and emits the `lead.created` webhook.

Source: https://www.hey.support/docs/api/leads/create-lead

---

<ApiEndpoint method="POST" path="/leads" />

Deduplicated per conversation: when `conversation_id` is provided and a lead already exists for it, the existing lead is returned with `existing: true` rather than a duplicate being created.

## Request body

<TypeTable
  type={{
  "chatbot_id": { type: "string", description: "Sqid-encoded chatbot id", required: true },
  "conversation_id": { type: "string", description: "", required: false },
  "name": { type: "string", description: "", required: false },
  "email": { type: "string (email)", description: "", required: false },
  "phone": { type: "string", description: "", required: false },
  "company": { type: "string", description: "", required: false },
  "source": { type: "string", description: "", required: false },
  "source_url": { type: "string (uri)", description: "", required: false },
  "status": { type: "string", description: "", required: false },
  "notes": { type: "string", description: "", required: false }
}}
/>

## Response `200`

<TypeTable
  type={{
  "id": { type: "string", description: "", required: true },
  "chatbot_id": { type: "string", description: "", required: true },
  "name": { type: "string", description: "", required: false },
  "email": { type: "string (email)", description: "", required: false },
  "phone": { type: "string", description: "", required: false },
  "status": { type: "string", description: "", required: true },
  "notes": { type: "string", description: "", required: false },
  "conversation_id": { type: "string", description: "", required: false },
  "created_at": { type: "string (date-time)", description: "", required: true }
}}
/>

### Errors

* `400` — Invalid request body
* `401` — Missing or invalid API key
* `404` — Chatbot or conversation not found
* `429` — Rate limit exceeded

Every error shares [one envelope](/docs/api/errors).

## Example

```bash
curl -X POST \
  https://www.hey.support/api/v1/leads \
  -H 'Authorization: Bearer hs_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"chatbot_id":"<chatbot_id>"}'
```