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

# Leads and deals

> Create leads, convert them to Active clients, attach notes, and sync the deals pipeline.

Leads are client entities with lead status. The same `entityKey` is used after you convert them to Active clients. Deals are a separate pipeline object with their own statuses and sources.

## Settings first

| Route                                | Use when creating             |
| ------------------------------------ | ----------------------------- |
| `GET /api/v1/settings/entity-types`  | `entityType` / `entityTypeID` |
| `GET /api/v1/settings/lead-sources`  | `leadSource` **name**         |
| `GET /api/v1/settings/lead-statuses` | `leadStatus` **name**         |
| `GET /api/v1/settings/deal-sources`  | Deal source names             |
| `GET /api/v1/settings/deal-statuses` | Deal status names             |

## Create a lead

Write access required. `POST /api/v1/leads`.

Individuals / sole traders: `entityName` = given name, `entitySurname` = family name (not auto-split).

Companies: `entityName` = legal or trading name; leave surname unset.

```json theme={null}
{
  "entityType": "Individual",
  "entityName": "Alex",
  "entitySurname": "Morgan",
  "email": "alex@example.com",
  "leadSource": "Website enquiry",
  "leadStatus": "New"
}
```

## Convert to client

```http theme={null}
POST /api/v1/leads/{entityKey}/convert-to-client
```

Sets client status from Lead to **Active**. The `entityKey` does not change. **400** if the entity is already a client.