---
title: "List deals"
method: GET
path: "/public-api/v1/deals"
tags: ["Deals"]
---

# List deals

`GET /public-api/v1/deals`

## Request

- Base URL: `https://app.hellobonsai.com`
- URL: `https://app.hellobonsai.com/public-api/v1/deals`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hellobonsai.com/oauth/authorize`
    - Token URL: `https://app.hellobonsai.com/oauth/token`
  - HTTP bearer

Lists the deals in your pipeline, a page at a time.

## Filtering

- `filter[title]` — searches deal titles, matching from the start of any
  word and ignoring case.
- `filter[deal_number]` — searches deal references the same way.
- `filter[assignee_member_id]` — one or more team member ids, or `me` for
  whoever the token belongs to.
- `filter[board_group_id]` — one or more pipeline stage ids. Returns the
  deals sitting in those stages.

## Query parameters

- `page[number]` integer
- `page[size]` integer
- `filter[title]` string
- `filter[deal_number]` string
- `filter[assignee_member_id]` string
- `filter[board_group_id]` string

## Response `200`

A page of deals.

- object
  - `data` Deal[], required
    - `id` integer, required: Unique identifier for the deal.
    - `title` string, required: Deal title.
    - `deal_number` string, required: Human-readable deal reference, unique within your account and assigned on creation.
    - `deal_value` string, nullable, required: What the deal is worth, as a decimal string in `currency`. `null` when no value has been set.
    - `currency` string, required: Three-letter ISO 4217 currency code for `deal_value`.
    - `probability` integer, nullable, required: Chance of winning the deal, as a whole percentage from 0 to 100. `null` when unset.
    - `close_date` string, date, nullable, required: Date the deal is expected to close, or `null` when unset.
    - `archived_at` string, date-time, nullable, required: When the deal was archived, or `null` while it is active.
    - `assignee_member_id` integer, nullable, required: Team member id of the deal owner, or `null` when the deal is unassigned.
    - `board_group_id` string, uuid, nullable, required: Id of the pipeline stage the deal sits in, or `null` when it is not on a board.
    - `status` string, required: Name of the pipeline stage the deal sits in — the label form of `board_group_id`. Stages are configurable per account, so this is free text rather than a fixed set of values, and it is an empty string when the deal is not on a board.
    - `company_name` string, nullable, required: Name of the client the deal is with, or `null`.
    - `assignee_member_name` string, nullable, required: Name of the deal owner, or `null` when the deal is unassigned.
    - `contact_ids` integer[], required: Ids of the contacts attached to the deal.
    - `url` string, required: Absolute link to the deal in the Bonsai app. Opens the pipeline with the deal expanded.
  - `meta` PaginatedMeta, required: Metadata returned alongside every list response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.
    - `pagination` Pagination, required: Where the returned page sits in the full result set.
      - `page` integer, required: The page that was returned.
      - `page_size` integer, required: How many records this page can hold.
      - `has_more` boolean, required: Whether at least one more page follows this one. Keep incrementing `page[number]` while this is `true`.

## Other responses

- `400`: A filter key is unknown, a filter value is not allowed, or a pagination parameter is not an integer.
- `401`: The access token is missing, expired or invalid.
- `403`: This token is not allowed to see deals.
- `429`: Rate limit exceeded. Wait at least `Retry-After` seconds before trying again.

---

[API](https://skmtc.dev/hellobonsai/apis/bonsai-api.md) - [All operations](https://skmtc.dev/hellobonsai/apis/bonsai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hellobonsai/apis/bonsai-api/revisions/abf12ed6a8d3?raw)