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. The API can't create leads or change outreach status, drafts or contacts.
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, most recently updated deal first.
Can leads:write create or import leads?
Revnu creates leads itself: send it a list as a message or a webhook and it researches them. leads:write updates leads that exist, adds notes, takes a lead over, removes wrong people, deletes a lead Revnu never worked and manages the block list.
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.