---
title: "Update a deal"
method: PATCH
path: "/public-api/v1/deals/{id}"
tags: ["Deals"]
---

# Update a deal

`PATCH /public-api/v1/deals/{id}`

## Request

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

Updates a deal. Every field is optional, and anything you leave out keeps
its current value.

Send `board_group_id` to move the deal to another stage of your pipeline —
that is how you advance a deal, mark it won, or mark it lost.

Changing `company_id` moves the deal to a different client and re-points
its contact to that client's primary contact. To choose the contacts
yourself, send `contact_ids` as well: it replaces the deal's contacts
with exactly the ids you give, and wins over the automatic re-point.

## Path parameters

- `id` integer, required

## Request body

- object
  - `deal` object, required
    - `title` string: New deal title.
    - `company_id` integer, nullable: Id of the client company the deal is with. Find one with `GET /public-api/v1/companies`.
    - `contact_ids` integer[]: The contacts on the deal, replacing whatever is there now. Send an empty array to remove them all. Leave the field out to keep the deal's current contacts.
    - `assignee_member_id` union: Who owns the deal: a team member id, or `me` for whoever the token belongs to. Send `null` to leave it unassigned.
      - integer, nullable: Team member id of the owner.
      - 'me': Assigns the deal to whoever the token belongs to.
    - `board_group_id` string, uuid, nullable: Id of the pipeline stage to move the deal to. Find one with `GET /public-api/v1/board_groups`.
    - `deal_value` string, nullable: What the deal is worth, as a decimal string. Must be zero or greater. `null` is ignored rather than clearing the value.
    - `probability` integer, nullable: Chance of winning the deal, as a whole percentage from 0 to 100. `null` is ignored rather than clearing the value.
    - `close_date` string, date, nullable: Date the deal is expected to close. Send `null` to clear it.

## Response `200`

The deal was updated.

- object
  - `data` Deal, required: An opportunity in your sales pipeline, sitting in one stage of the deal board.
    - `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` Meta, required: Metadata returned alongside every single-resource response.
    - `request_id` string, required: Identifier for this request. Quote it when contacting support about a specific call.

## Other responses

- `400`: The request body is missing its `deal` wrapper.
- `401`: The access token is missing, expired or invalid.
- `403`: This token can see the deal but is not allowed to change it.
- `404`: No deal with that id in your account.
- `422`: The deal could not be saved. `invalid_value` means a field was the wrong shape or out of range; `not_accessible` means `company_id`, `contact_ids`, `assignee_member_id` or `board_group_id` names something that is not in your account.
- `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)