# Update a lead

> Set a lead's owner, move its deal (stage, value, close date), fill your own lead columns, and set vertical, archetype and tags. Creating a lead and saving its people are separate endpoints; this one can't change outreach status or drafts.

Canonical: https://revnu.com/docs/lead-update
Last updated: 2026-11-11

```bash
curl -X PATCH -H "Authorization: Bearer $REVNU_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"stage":"proposal","dealValue":12000,"currency":"USD","closeDate":"2026-12-01","customFields":{"crm_id":"0065g00000XyZ"}}' \
  https://revnu.com/api/v1/leads/sn7…
```

## Body

Every field is optional, and `null` clears one, except `currency`, which can't be cleared. Unknown fields are a `400`, so a typo never silently does nothing.

| Field | Meaning |
|---|---|
| `stage` | The deal's stage: `interested` (a positive reply), `meeting` (booked or held), `proposal` (pricing or a proposal sent), `won` (paying) or `lost`. Setting it on a lead with no deal opens one. `null` removes the deal (the timeline keeps its history), with no other deal field; a deal that ended is `lost`, not removed. |
| `dealValue` | What the deal is worth, in major units (`12000` is $12,000), or `null`. |
| `currency` | ISO 4217 code for `dealValue`, such as `USD` or `GBP`. Any other value is a `400`. Defaults to `USD`. |
| `closeDate` | Expected close date as `YYYY-MM-DD`, or `null`. |
| `owner` | The teammate who owns the lead: their name, first name or email as it appears on your team in Settings, or `null` to unassign. A name that matches nobody, or more than one person, is a `400` listing who it could be. It belongs to the lead, not the deal, so it holds with no deal open. |
| `lostReason` | Why it was lost, up to 200 characters. Kept only while the stage is `lost`. |
| `customFields` | Values for your account's own lead columns, by column key (the `key` in a lead's `fields`), up to 1,000 characters each; `null` clears one. A key that isn't one of your columns is a `400` that lists the keys you have. |
| `vertical`, `archetype` | Strings, at most 120 characters. |
| `tags` | Up to 20 strings of at most 64 characters, deduplicated, order kept. Replaces the whole list. |

Every stage change is added to the lead's timeline with the token's label as the author, so the dashboard and your Revnu agent see who moved it. A deal never changes what Revnu sends: to stop outreach to a company, mark it in the dashboard or ask Revnu.

## Response

`{ "lead": { id, domain, vertical, archetype, tags, owner?, deal?, fields? } }`. `owner` is returned only when you sent it. `deal` is returned only when you sent a deal field, and holds only those fields as stored (for example `{ "stage": "proposal", "amount": 12000 }`), or `null` when the lead has no deal. `fields` is returned only when you sent `customFields`, and holds only the columns you wrote. The response carries nothing else a `leads:read` token would show; read the lead back for the rest. `400` for a value Revnu can't store, such as a bad currency or close date, with the reason. `404` for an unknown or another account's lead.

## Frequently asked questions

### How do I keep my CRM's deal stage in Revnu?

PATCH `stage` (and `dealValue`, `closeDate`) whenever your CRM moves the deal. List one stage with [`GET /leads?stage=meeting`](https://revnu.com/docs/leads.md), most recently updated deal first.

### Can leads:write create or import leads?

Yes, one company at a time: [Create a lead](https://revnu.com/docs/lead-create.md) saves a company with the people you know there, and [Save lead contacts](https://revnu.com/docs/lead-contacts-save.md) adds or updates people on a lead. To have Revnu find and research a list, send it as a [message](https://revnu.com/docs/agent-messages.md) or a [webhook](https://revnu.com/docs/webhooks.md). `leads:write` also updates leads that exist, adds [notes](https://revnu.com/docs/lead-notes.md), [takes a lead over](https://revnu.com/docs/lead-take-over.md), [removes wrong people](https://revnu.com/docs/lead-people-remove.md), [deletes a lead](https://revnu.com/docs/lead-delete.md) Revnu never worked and manages the [block list](https://revnu.com/docs/blocklist-add.md).

### Which scope does this need?

`leads:write`. A token without it gets `403` with `requiredScope` in the body. `GET /me` shows a token's scopes.

### Does the agent read tags?

No. `tags` is yours: market and sub-market slugs, campaign names, whatever your own dashboard keys on. `vertical` and `archetype` are shown in the dashboard and used to segment the leads table. The agent does read the deal and your lead columns.

### Are responses cached?

No. Every response is `Cache-Control: no-store`, so what you read is current.
