Skip to main content
An opportunity is a deal: a named amount of money, in a currency, sitting at a stage of a pipeline. Opportunities are created in the Cockpit — often converted from a campaign lead, in which case the deal keeps a sourceLeadId pointing back at it.

​
Pipelines and stages

A pipeline is an ordered set of stages, and each stage has a type: A deal’s status comes from its stage’s type, not from a field on the deal. That’s why GET /v1/pipelines returns stages inline — without them you can’t interpret a stageId or tell which stages mean won.
Filtering by status is shorthand for “any stage of that type”, so it keeps working when someone renames a stage:

​
Deal value

value is a decimal string and always travels with its currency:
Strings rather than numbers, so nothing is lost to floating point on the way to you. minValue and maxValue still compare numerically, so ?minValue=9000 behaves the way you’d expect.

​
One-off or recurring

A deal also carries a value basis — whether its value is a single payment or a repeating one. It defaults to one-off. This matters more than it looks. A £500-a-month subscription and a £500 project are not the same deal, and a pipeline that adds them together is wrong in a way nobody notices until a forecast misses. Set it when you create the opportunity; correcting it later means every total that included it was wrong in the meantime.
Existing deals default to one-off, which preserves the totals they already reported. If you sell subscriptions, check the basis on anything created before you started setting it.

​
Probability and weighted value

Every open deal has an effective close probability, and there are two places it can come from:
  1. The deal’s own override, if someone set one.
  2. Otherwise its stage’s default.
The probability field on the response is already resolved — you don’t need to work out which applied. Weighted value is each deal’s value multiplied by its own probability, then summed, which is what makes it a forecast rather than a wish:

​
Pipeline value

GET /v1/metrics/pipeline gives you the whole picture in one call — open, won and lost, broken down by stage, pipeline and owner:
It accepts the same filters as GET /v1/opportunities, so any list view you can build you can also total.
Totals are reported per currency, as an array — never as one combined figure. A pipeline holding GBP and USD deals returns an entry for each, because adding them without a conversion rate produces a number that looks precise and means nothing. Convert on your side, with whatever rate your finance team uses.
winRate is won / (won + lost) across the closed deals in the set, and is null rather than 0 when nothing has closed yet.

​
Resolving owners

ownerId is a user id. Resolve it with GET /v1/users, which returns each person’s display name, email and title.