> ## Documentation Index
> Fetch the complete documentation index at: https://api.leadey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Opportunities

> Deals, deal value, and the pipelines they move through.

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:

| Type   | Meaning                                     |
| ------ | ------------------------------------------- |
| `open` | Still in play — counts toward your forecast |
| `won`  | Closed successfully                         |
| `lost` | Closed unsuccessfully                       |

A deal's `status` comes from its stage's type, not from a field on the deal. That's why [`GET /v1/pipelines`](/api-reference/pipelines/list-pipelines) returns stages inline — without them you can't interpret a `stageId` or tell which stages mean won.

```bash theme={"dark"}
curl "https://backend.leadey.ai/v1/pipelines" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

Filtering by `status` is shorthand for "any stage of that type", so it keeps working when someone renames a stage:

```
GET /v1/opportunities?status=open
```

## Deal value

`value` is a **decimal string** and always travels with its `currency`:

```json theme={"dark"}
{
  "id": "opp_a1b2c3",
  "name": "Northwind rollout",
  "value": "10000.00",
  "currency": "GBP",
  "probability": 40,
  "status": "open"
}
```

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.

## 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:

```
10,000.00 @ 40%  =  4,000.00
 5,000.50 @ 90%  =  4,500.45
                    --------
weightedValue    =  8,500.45
```

## Pipeline value

[`GET /v1/metrics/pipeline`](/api-reference/metrics/pipeline-value) gives you the whole picture in one call — open, won and lost, broken down by stage, pipeline and owner:

```bash theme={"dark"}
curl "https://backend.leadey.ai/v1/metrics/pipeline?status=open" \
  -H "Authorization: Bearer sk_live_your_key_here"
```

It accepts the same filters as `GET /v1/opportunities`, so any list view you can build you can also total.

<Warning>
  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.
</Warning>

`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`](/api-reference/reference/list-users), which returns each person's display name, email and title.