Skip to main content
PATCH
Update a deal

Authorizations

Authorization
string
header
required

A workspace API key, created in workspace settings and sent as Authorization: Bearer op_live_…. Session cookies are not accepted. Scopes: signals:read, accounts:read, listeners:read, listeners:analyse, pipeline:read, pipeline:write, collections:write, export:read.

Path Parameters

id
string
required

The id of the resource.

Body

application/json

The fields to change. Omitted fields are left alone.

stage
enum<string>

Where to move it. stageFirstAt records only the first arrival at each stage, so a deal that goes backwards and forwards keeps its real history.

Available options:
new,
contacted,
meeting,
won,
lost
ownerUserId
string | null

Clerk user id to assign it to, or null to unassign.

Maximum string length: 120
dealValueMinor
integer | null

Value in minor units — pence, cents — as an integer, or null to clear it. Never a float: 0.1 + 0.2 is not 0.3, and a revenue total out by a penny is a revenue total nobody trusts.

Required range: 0 <= x <= 1000000000
currency
string

ISO 4217. Upper-cased on write.

Required string length: 3
lostReason
string

Why it was lost. Trimmed on write.

Maximum string length: 280
contact
object

Who to actually contact. Merged into whatever is already stored; send a field as "" to remove it.

Response

The deal after the update.

One deal on the board. Attached to a signal, never to an account: an entry that could do either would count one deal twice, once against the signal and once against the company, and nobody would notice for a quarter.

The signal* fields are a snapshot copied when the deal was made, not a mirror. If the signal is later re-classified the card still says what the lead looked like when somebody decided to act on it, which explains the decision rather than second-guessing it. They are absent on deals created before each field existed.

id
string
required

Stable identifier. What PATCH /v1/pipeline/{id} takes.

orgId
string
required

The workspace this belongs to (org_…).

signalId
string
required

The signal this came from. Unique per workspace — one deal per signal.

stage
enum<string>
required

Where it is on the board.

Available options:
new,
contacted,
meeting,
won,
lost
enteredStageAt
string<date-time>
required

When it entered the stage it is in now.

stageFirstAt
object
required

First time it reached each stage. Kept per stage rather than as one timestamp so cycle time survives a deal moving backwards, which real deals do. Sparse: stages it has never reached are absent.

createdAt
string<date-time>
required

When the deal was opened.

createdBy
string
required

Clerk user id of whoever opened it.

updatedAt
string<date-time>
required

When the row last changed. The pagination sort key.

signalTitle
string

The signal's title at the moment the deal was made.

signalClassification
enum<string>

What the signal was judged to be then.

Available options:
high_intent,
evaluating,
relevant,
competitor,
content,
strong_match,
worth_a_look,
stretch,
mismatch,
stale,
hiring_now,
expanding,
replacing,
adjacent,
switching,
frustrated,
comparing,
praise,
pain_confirmed,
at_risk,
healthy,
noise
signalScore
integer

Its relevanceScore then.

Required range: 0 <= x <= 100
signalCategory
enum<string>

Its category then.

Available options:
direct_intent,
hire_vs_buy,
competitor_pain,
growth,
funding,
procurement,
construction,
regulatory,
operational_pain,
tech_change,
leadership_change,
real_estate,
new_business,
cx_failure,
missing_capability,
incident
signalUrgency
enum<string>

Its urgency then.

Available options:
low,
medium,
high,
immediate
signalUrl
string<uri>

Link to the post itself.

signalSource
enum<string>

Which platform it came from.

Available options:
x,
linkedin,
facebook,
reddit,
hackernews,
linkedin_jobs,
indeed,
ashby,
greenhouse,
lever,
google_reviews,
g2,
trustpilot,
youtube,
vendor_community
signalSummary
string

The post's text, copied from the signal's excerpt.

accountKey
string

Denormalised so revenue can be grouped by company without a join.

ownerUserId
string

Clerk user id of whoever owns it. Unassigned is a legitimate state.

dealValueMinor
integer

Value in minor units, as an integer — pence, cents. Never a float: a revenue total out by a penny is a revenue total nobody trusts.

Required range: x >= 0
currency
string

ISO 4217, upper-cased. Stored beside the value rather than assumed.

Required string length: 3
lostReason
string

Why it was lost, when somebody said.

contact
object

A person at the other end of a deal. On the deal rather than on the account, because most market signals resolve no accountKey at all. Every field is optional: a name with no email is a better record than no record.

closedAt
string<date-time>

When it reached won or lost. Removed again if it reopens.