Create a deal on an account

POST/deals

Requires scope: write:deals

Parameters

Parameter	In	Type	Description
`Idempotency-Key`required	header	string	Stable logical request ID required for every machine mutation; exact retries replay and changed inputs conflict.

Request body

Field	Type	Allowed values
`store_id`required	string	any string
`name`required	string	any string
`value`	number	any number
`stage`	string	`discoveryqualifyingproposalnegotiationwonlost`
`next_step`	string	any string
`next_step_due`	string	any string

Responses

Status	Description
`201`	Created
`400`	Invalid body
`401`	Missing or invalid API key
`403`	Key lacks the required scope
`429`	Rate limit exceeded (see Retry-After)

Is this page helpful?

Request

curl -X POST "https://vergio.ai/api/v1/deals" \
  -H "Authorization: Bearer $VERGIO_API_KEY" \
  -H "Idempotency-Key: replace-with-a-stable-request-id" \
  -H "Content-Type: application/json" \
  -d '{
  "store_id": "b7c9a2e1-0000-4000-8000-000000000000",
  "name": "string",
  "value": 0,
  "stage": "discovery",
  "next_step": "string",
  "next_step_due": "string"
}'

Response (201)

{
  "deal": {
    "id": "b7c9a2e1-0000-4000-8000-000000000000",
    "storeId": "b7c9a2e1-0000-4000-8000-000000000000",
    "accountName": "string",
    "domain": "string",
    "name": "string",
    "value": 0,
    "dealKind": "one_off",
    "currency": "string",
    "stage": "discovery",
    "ownerUserId": "b7c9a2e1-0000-4000-8000-000000000000",
    "nextStep": "string",
    "nextStepDue": "string",
    "source": "string",
    "emailPermissionStatus": "unknown",
    "emailPermissionSource": "direct_request",
    "emailPermissionConfirmedAt": "2026-07-06T12:00:00Z",
    "version": 0,
    "createdAt": "2026-07-06T12:00:00Z",
    "updatedAt": "2026-07-06T12:00:00Z"
  },
  "created": true
}