# Update a lead's labels

> Set vertical, archetype and tags on a lead. The only write on leads: the API can't create leads or change status, drafts or contacts.

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

```bash
curl -X PATCH -H "Authorization: Bearer $REVNU_API_TOKEN" \
  -H "content-type: application/json" \
  -d '{"vertical":"hpc","archetype":"operator","tags":["eu","gpu"]}' \
  https://revnu.com/api/v1/leads/sn7…
```

## Body

Any of `vertical`, `archetype` (strings, at most 120 characters) and `tags` (up to 20 strings of at most 64 characters, deduplicated, order kept). `null` clears a field. Unknown fields are a `400`, so a typo never silently does nothing.

## Response

`{ "lead": { id, domain, vertical, archetype, tags } }`, the labels as stored. The response carries nothing a `leads:read` token would show; read the lead back for the rest. Status, drafts, contacts and research stay read-only; the agent and the dashboard own them. `404` for an unknown or another account's lead.

## Frequently asked questions

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

Revnu creates leads itself: send it a list as a [message](https://revnu.com/docs/agent-messages.md) or a [webhook](https://revnu.com/docs/webhooks.md) and it researches them. `leads:write` sets these three labels 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.

### Are responses cached?

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