# Update a lead

`PATCH https://app.whatsetter.com/api/v1/leads/{id}`

Update a lead from your CRM: status, tags, **owner**, **next action**
and **outcome**. Only the fields you send change; at least one is
required. Setting status to `qualified` stamps the qualification date
(once).

- `assigned_to`: the id of a workspace member (`GET /team/members`),
  or `null` to release the lead. Any other value answers `422`.
- `next_action_at` / `next_action_label`: the next human step. `null`
  on `next_action_at` clears both; a label needs a date.
- `deal_status`: `open` / `won` / `lost`. A lost deal needs a
  `lost_reason` from the dashboard's list (`price`, `timing`,
  `unqualified`, `competitor`, `unreachable`, `other`); it is cleared
  when the deal is open or won.

Every owner / next-action / outcome change is written to the lead's
journal, by the API key's name, exactly like an edit from the
dashboard. Requires scope `leads:write`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | qualified \| in_progress \| not_interested \| cold \| pending \| stopped \| queued | no |  |
| `tags` | array | no |  |
| `assigned_to` | string,null | no | A member id from `GET /team/members`, or `null` to unassign. |
| `next_action_at` | string,null | no | ISO 8601, or `null` to clear the next action. |
| `next_action_label` | string,null | no | Short label for the next action (needs `next_action_at`). |
| `deal_status` | open \| won \| lost | no |  |
| `lost_reason` | price \| timing \| unqualified \| competitor \| unreachable \| other \|  | no | Required when `deal_status` is `lost`; ignored otherwise. |

```json
{
  "assigned_to": "66a1f2c3d4e5f60718293a4b",
  "next_action_at": "2026-09-22T09:00:00.000Z",
  "next_action_label": "Call back",
  "deal_status": "open"
}
```

## Example request

```bash
curl --request PATCH \
  --url 'https://app.whatsetter.com/api/v1/leads/{id}' \
  --header 'Authorization: Bearer ws_live_…'
  --header 'Content-Type: application/json' \
  --data '{"assigned_to":"66a1f2c3d4e5f60718293a4b","next_action_at":"2026-09-22T09:00:00.000Z","next_action_label":"Call back","deal_status":"open"}'
```

## Responses

### 200: The updated lead

```json
{
  "data": {
    "id": "68e0a1b2c3d4e5f6a7b8c9d0",
    "phone": "33612345678",
    "whatsapp_id": "33612345678@c.us",
    "name": "Marie Dupont",
    "status": "in_progress",
    "qualified": false,
    "qualified_at": null,
    "replied": true,
    "campaign_id": "auto24-maroc-4-bu76",
    "list_id": null,
    "source": "instagram",
    "source_confidence": "certain",
    "tracked_link_id": "68d9aa11bb22cc33dd44ee55",
    "external_reference": "4471",
    "channel": "whatsapp",
    "ig_username": null,
    "email": "marie@acme.fr",
    "tags": [
      "hot"
    ],
    "messages_count": 7,
    "booking_status": null,
    "assigned_to": "66a1f2c3d4e5f60718293a4b",
    "stage": "conversation",
    "deal_status": "open",
    "lost_reason": null,
    "next_action_at": "2026-09-22T09:00:00.000Z",
    "next_action_label": "Call back",
    "first_contact_at": "2026-09-15T10:02:11.000Z",
    "last_message_at": "2026-09-18T16:40:03.000Z",
    "last_message_direction": "inbound",
    "created_at": "2026-09-15T10:02:11.000Z",
    "updated_at": "2026-09-19T08:12:45.000Z"
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 422: Invalid field, unknown member id, or nothing to update

```json
{
  "error": {
    "code": "validation_error",
    "message": "\"assigned_to\" must be the id of a member of this workspace (see GET /team/members), or null."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/updatelead/
