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

# Deals

> Opportunities — stage, value, owner. Linked to a person + company.

## Endpoints

| Method   | Path            | Purpose                                                                        |
| -------- | --------------- | ------------------------------------------------------------------------------ |
| `GET`    | `/deals`        | List, paginated. `?expand=primary_company,primary_person`                      |
| `POST`   | `/deals`        | Create                                                                         |
| `POST`   | `/deals/search` | Filter, sort, paginate. `expand` via the body                                  |
| `GET`    | `/deals/:id`    | Fetch one. Same `?expand=` options                                             |
| `PATCH`  | `/deals/:id`    | Update                                                                         |
| `DELETE` | `/deals/:id`    | Soft-delete (moves to 30-day trash; restore via POST /trash/deals/:id/restore) |

## Search

`POST /deals/search` takes the same structured filter body as [people search](/docs/api-reference/people#search): operators `equals | not_equals | contains | gt | gte | lt | lte | is_null`, combinators `and | or`, custom attributes via `custom_attributes.<key>`. Filterable fields: `id`, `name`, `stage`, `value_cents`, `currency`, `primary_company_id`, `primary_person_id`, `created_at`, `updated_at`, `closed_at`. Pass `expand` (e.g. `"primary_company,primary_person"`) and `sort` in the body.

```bash theme={null}
curl -X POST $SALTY_API/deals/search \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"stage":{"equals":"won"}},"sort":[{"value_cents":"desc"}]}'
```

## Fields

| Field                      | Type             | Notes                                                       |
| -------------------------- | ---------------- | ----------------------------------------------------------- |
| `id`                       | uuid             |                                                             |
| `name`                     | string           | Required                                                    |
| `stage`                    | string           | Defaults to `"open"`. Free-form — no enum enforcement in v1 |
| `value_cents`              | string \| null   | bigint serialized as a string (avoids JS precision loss)    |
| `currency`                 | string \| null   | Defaults to `"USD"`; 3 chars                                |
| `primary_company_id`       | uuid \| null     |                                                             |
| `primary_person_id`        | uuid \| null     |                                                             |
| `custom_attributes`        | object           | Validated by the [schema engine](/docs/concepts/schema-engine)   |
| `closed_at`                | datetime \| null | Set when stage moves to a closed state                      |
| `created_at`, `updated_at` | datetime         |                                                             |

## Create

```bash theme={null}
curl -X POST $SALTY_API/deals \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme - Enterprise Q3",
    "stage": "negotiation",
    "value_cents": "15000000",
    "currency": "USD",
    "primary_company_id": "<company-uuid>",
    "primary_person_id": "<person-uuid>"
  }'
```

<Note>
  `value_cents` is a **string** in JSON because Postgres `bigint` exceeds JavaScript's `Number.MAX_SAFE_INTEGER`. Parse it client-side with `BigInt(deal.value_cents)` if you need to do arithmetic.
</Note>

## Expand both relations

```bash theme={null}
curl "$SALTY_API/deals/<id>?expand=primary_company,primary_person" \
  -H "Authorization: Bearer $SALTY_API_KEY"
```

The response inlines `primary_company` and `primary_person` using the same serializers as `/companies/:id` and `/people/:id`.