Deals

Deals represent sales opportunities linked to a contact. Each deal has a stage, value, and close date. Deals move across stages on the pipeline board.

GET/api/v1/deals

Return a paginated list of deals for your tenant.

Query parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page — max 100 (default: 25)
`stage`	string	Filter by stage name
`contact_id`	integer	Filter by associated contact ID
`won`	boolean	Filter won deals only
`lost`	boolean	Filter lost deals only

Example response

{
  "deals": [
    {
      "id": 201,
      "title": "Annual contract — Acme Corp",
      "value": 12000,
      "currency": "USD",
      "stage": "proposal",
      "contact_id": 1042,
      "close_date": "2026-04-01",
      "won": false,
      "lost": false,
      "addedtime": 1710000000
    }
  ],
  "total": 34,
  "page": 1,
  "limit": 25
}

GET/api/v1/deals/:id

Fetch a single deal by ID.

Example response

{
  "id": 201,
  "title": "Annual contract — Acme Corp",
  "value": 12000,
  "currency": "USD",
  "stage": "proposal",
  "contact_id": 1042,
  "close_date": "2026-04-01",
  "won": false,
  "lost": false
}

POST/api/v1/deals

Create a new deal linked to a contact.

Request body

Field	Type	Description
`title`required	string	Deal name
`contact_id`required	integer	ID of the associated contact
`value`	number	Deal value in the currency's smallest unit
`currency`	string	ISO 4217 currency code (default: USD)
`stage`	string	Pipeline stage name
`close_date`	string	Expected close date (YYYY-MM-DD)

Example request

curl -X POST https://app.pushbuttoncrm.com/api/v1/deals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Annual contract — Acme Corp",
    "contact_id": 1042,
    "value": 12000,
    "stage": "proposal",
    "close_date": "2026-04-01"
  }'

Example response

{
  "id": 202,
  "title": "Annual contract — Acme Corp",
  "value": 12000,
  "currency": "USD",
  "stage": "proposal",
  "contact_id": 1042,
  "close_date": "2026-04-01",
  "won": false,
  "lost": false,
  "addedtime": 1710100000
}

PUT/api/v1/deals/:id

Update all fields on a deal. To mark a deal as won or lost, set won or lost to true.

Request body

Field	Type	Description
`title`required	string	Deal name
`value`	number	Deal value
`stage`	string	Pipeline stage name
`close_date`	string	Expected close date (YYYY-MM-DD)
`won`	boolean	Mark deal as won
`lost`	boolean	Mark deal as lost

Example response

{ "id": 201, "won": true, "stage": "closed-won", ... }

DELETE/api/v1/deals/:id

Permanently delete a deal. This action is irreversible.

Example response

{ "id": 201, "deleted": true }