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

# Create a deal / opportunity

`POST /deals`

## Request

- Base URL: `https://www.sagaris.ai/api/v1`
- URL: `https://www.sagaris.ai/api/v1/deals`
- Auth: HTTP bearer

Create an opportunity for a workspace-owned contact. When the contact's lifecycle requires it, a valid bant_assessment is mandatory (same BANT gate as the internal create path). Requires the deals.write scope.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `contact_id` string, required: A contact in the key's workspace.
  - `title` string, required
  - `value` number: Deal value; defaults to 0.
  - `currency` string: ISO currency code; defaults to USD.
  - `stage` 'prospecting' | 'qualification' | 'proposal' | 'negotiation' | 'closed_won' | 'closed_lost'
  - `bant_assessment` object: Required only when the contact's lifecycle gate demands BANT confirmation.

## Response `201`

The created opportunity.

- object
  - `data` Deal, required
    - `id` string
    - `contact_id` string
    - `workspace_id` string
    - `title` string
    - `value` number
    - `currency` string
    - `stage` string
    - `probability` number, nullable
    - `expected_close_date` string, date, nullable
    - `created_at` string, date-time
  - `error` unknown, required

## Other responses

- `400`: Validation failure or BANT confirmation required (code bant_required).
- `401`: Missing, malformed, invalid, revoked, or expired API key.
- `403`: The key does not hold the required scope for this operation.
- `404`: The referenced resource was not found in the key's workspace.
- `429`: Per-key write rate limit exceeded (60 requests / 60s).
- `500`: Lookup or insert failure.
- `503`: The database / API-keys table is not provisioned.

---

[API](https://skmtc.dev/sagaris/apis/sagaris-public-api.md) · [All operations](https://skmtc.dev/sagaris/apis/sagaris-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sagaris/apis/sagaris-public-api/revisions/ac70219a7080?raw)