# Leads

A lead is one person in one campaign, identified by their phone number. Push leads from your website or backend, merge in more details as the visitor tells you more, read them back and move their pipeline card.

Writes merge, so a multi-step form can send its whole state on every step: `null`, empty and whitespace-only values mean "not provided" and never clear a stored value, a non-empty value replaces the stored one, and `custom_fields` and `attribution` merge key by key (stored keys you do not send are kept).

Write responses carry identifiers only and never echo personal data; read a lead back with `GET /v1/leads/{lead_id}`.

## Endpoints

### [Create or update a lead](/api/leads/create)

`POST /v1/leads`

Creates a lead in a campaign, or merges into the campaign's existing lead with the same phone number.

### [Update a lead](/api/leads/update)

`PATCH /v1/leads/{lead_id}`

Merges more details into a lead, typically from later steps of a form.

### [Retrieve a lead](/api/leads/get)

`GET /v1/leads/{lead_id}`

Returns a lead's details and its pipeline card as it is on the board now.

### [Move a lead's card](/api/leads/move-stage)

`PUT /v1/leads/{lead_id}/stage`

Moves the lead's pipeline card to another stage of its pipeline, the way a move on the board does.