# Opportunities

> Sales projects — with stage, value, health, BANT, and checklist steps.

An opportunity (`opportunity` in the API, `opp` for short) is a sales project you run with a company. The UI calls it a **Project** (*Proje*) or an **Opportunity** (*Fırsat*). Every opportunity belongs to a company, sits in a stage, and moves forward through stage gates until it closes.

## Stages

Stages vary by installation (**Settings → Stages** (*Ayarlar → Aşamalar*)). New installations start with two open stages (*Aday* · *Devam ediyor*, meaning prospect and in progress); industrial installations such as Makro use five open stages and stage gates:

`Qualify` → `Viable` → `Present Solution` → `Negotiation` → `Expect to Close` → `Win` / `Lost` / `Cancel`

The closing keys are `Win`, `Lost`, and `Cancel` on every installation; their display names can differ. The installation's stage keys and names are returned in `constants.stages`, `constants.open_stages`, and `constants.stage_labels` in the [`GET /api/v1/me`](/rest-api/auth/me) response. Details: [Stages and gates](/concepts/pipeline).

## Account follow-up containers

The ongoing relationship with won customers is kept in **Account Follow-up** (*Müşteri Takibi*) containers in the `Account` stage. These containers don't count toward the sales pipeline, and visits and orders link to them. Fetch them from the list with `stage=account`; they carry `is_account: true`.

## Fields

| Field | Type | Description |
|---|---|---|
| `id`, `rid` | integer, string | ID and permanent record ID (`006…`). |
| `name` | string | Display name (generated from the product and type if there's no name). |
| `customer_id`, `customer` | integer, string | Company. |
| `stage`, `stage_label` | string | Stage key and display name. |
| `is_open`, `is_account` | boolean | Open opportunity · account follow-up container. |
| `potential_kg`, `offer_price`, `payment_days` | number | Monthly volume, unit price, payment term. |
| `unit`, `pu`, `cur_sym` | string | The product's unit, price unit (e.g. `€/kg`), and currency symbol. |
| `value`, `value_short` | number, string | Annual value = volume × price × 12 (otherwise the manually entered value). |
| `value_base`, `base_currency` | number, string | The value converted to the installation's base currency. |
| `probability`, `prob`, `fc` | number, string | Probability (%) and forecast category. |
| `health`, `health_color` | object, string | Health score and color (`g` green, `y` yellow, `r` red). |
| `health_manual`, `health_note` | boolean, string | Whether the user set the color manually, and their note. |
| `sla_days`, `sla_left`, `days_in_stage` | integer | Stage duration target, days left, days spent in the stage. |
| `lifetime_left` | integer | Days left in the project's lifetime. |
| `next_step`, `close_date` | string, date | Next step and expected close date. |
| `bant` | integer | Number of BANT criteria met (0–4). |
| `owner` | user | Owner. |

The single-record endpoint also returns `steps` (checklist), `gate_ok`, `gate_problems`, `next_stage`, `bant_b/a/n/t`, `offers`, `visits`, `demos`, `orders`, `tasks`, `logs` (stage history), `notes`, `tags`, `threads`, and, if the opportunity is closed, `close_category`, `close_reason`, and `closed_at`.

## How value is calculated

If a product, monthly volume, and unit price are set, the annual value is **volume × price × 12** and can't be edited manually. Otherwise, the manually entered value in the `value` field is used. Dashboards and totals are always calculated with `value_base`, in the base currency.

## Health

The health score (0–100) is calculated automatically. Exceeding the stage SLA or the project lifetime, time since the last activity, the next step's date and postponements, a close date in the past, stage gate problems, and a missing quoted price during negotiation lower the score; activity in the last 7 days and a positive trial raise it. 75 and above is green, 50–74 is yellow, and anything lower is red. Users can pick the color manually and write a short note; a manually chosen color overrides the calculated one (`health_manual: true`). `sort=health` sorts the list with red opportunities first.

## Related endpoints

:::cards
- [List opportunities](/rest-api/deals/list) list | Stage, sorting, pagination.
- [Change the stage](/rest-api/deals/stage) arrow | With stage gates enforced.
- [Update an opportunity](/rest-api/deals/update) pencil | Volume, price, close date, forecast.
- [Add a step](/rest-api/deals/steps-create) check | Checklist.
:::