---
title: "Create a deal"
method: POST
path: "/public-api/v1/deals"
tags: ["Deals"]
---

# Create a deal

`POST /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

Creates a deal. `title` and `company_id` are required — every deal is
with a client.

A few things are filled in for you when you leave them out: the deal
lands in the first stage of your deal board, and the client's primary
contact is attached to it. Pass `board_group_id` or `contact_id` to
choose instead.

The ids this endpoint takes come from other endpoints:
`GET /public-api/v1/companies` for `company_id` and `contact_id`,
`GET /public-api/v1/board_groups` for `board_group_id`, and
`GET /public-api/v1/team_members` for `assignee_member_id`.

## Request body

- object
  - `deal` object, required
    - `title` string, required: Deal title. Required.
    - `company_id` integer, required: Id of the client company the deal is with. Required.
    - `contact_id` integer, nullable: Id of a contact at that company to attach to the deal. Defaults to the company's primary contact.
    - `assignee_member_id` union: Who owns the deal: a team member id, or `me` for whoever the token belongs to. Send `null` or leave it out for an unassigned deal.
      - 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 put the deal in. Defaults to the first stage of your deal board.
    - `deal_value` string, nullable: What the deal is worth, as a decimal string. Must be zero or greater.

## Response `201`

The deal was created.

- 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 is not allowed to create deals.
- `422`: The deal could not be saved. `blank` or `invalid_value` means a field was empty or the wrong shape; `not_accessible` means `company_id`, `contact_id`, `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)