Create a deal

POST

/v1/deals

• Production

Creates a deal in an active stage. Creating a deal already won/lost is rejected (won books revenue — close from the panel). Requires scope deals:write.

Authorizations

• bearerAuth

Request Body ^required

object

title

required

string

<= 200 characters

contactId

integer

nullable

value

number

0

currency

string

default: USD

stage

string

default: lead

Allowed values: lead qualified proposal negotiation

probability

integer

<= 100

expectedCloseAt

string format: date-time

nullable

notes

string

nullable

Responses

201

Deal created.

A sales pipeline deal. tasks is populated on GET by id, omitted in list responses.

object

id

integer

title

string

contactId

integer

nullable

contactName

string

nullable

value

number

currency

string

stage

string

Allowed values: Lead Qualified Proposal Negotiation Won Lost

probability

0-100.

integer

expectedCloseAt

string format: date-time

nullable

closedAt

string format: date-time

nullable

notes

string

nullable

openTaskCount

integer

createdAt

string format: date-time

updatedAt

string format: date-time

nullable

tasks

Array<object>

nullable

object

id

integer

title

string

status

string

Allowed values: Open InProgress Done

priority

string

Allowed values: Low Medium High

dueAt

string format: date-time

nullable

isOverdue

boolean

400

The request body or parameters failed validation.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "bad_request",
  "message": "at least one of name, username, phone is required"
}

401

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

403

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error

message

Human-readable explanation of the error.

string

details

Optional structured context (field-level validation errors, etc.).

nullable

Example

{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}