PATCH /v1/crm/deals/{deal_id}

Move a deal, win, lose or reopen it, or change its title, value, contact or notes.

Moves a deal to another stage, wins, loses or reopens it, or changes its title, value, contact or notes. Send only what changes. It follows the board’s rules:

• Moving it into the pipeline’s won or lost stage wins or loses it; moving it out of one reopens it.
• Setting status to won or lost moves it to the pipeline’s won or lost stage, if the pipeline has one. Setting open on a deal in a closing stage moves it back to the last ordinary stage.
• Sending stage and status together moves it and sets that status, whatever the stage.

A deal stays in its pipeline: stage must be one of that pipeline’s. The change shows in the deal’s history, made by the API key.

Needs the crm.deals:write scope.

Path parameters

Field	Type	Required	Notes
deal_id	string	Yes	The deal’s id.

Body

Field	Type	Required	Notes
stage	integer	No	A stage of the deal’s pipeline to move it to.
status	string	No	open, won or lost.
title	string	No	Up to 200 characters; not empty.
value_minor	integer	No	Its value in the currency’s minor unit: 0 or more.
contact	string	No	The id of one of the account’s contacts; null to take its contact off.
notes	string	No	The deal’s own free text, replaced. Up to 4,000 characters.

Request

cURL

curl -X PATCH "https://api.fireflo.au/v1/crm/deals/5b2e8c1d-7a4f-4e3b-9c6d-1f0a2b3c4d5e" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "won",
  "value_minor": 11800000
}'

Response

200 OK — the deal. A change sends one event to your webhook endpoints: deal.won, deal.lost or deal.reopened when its status changed, otherwise deal.stage_changed when it moved, otherwise deal.updated. A request that changes nothing sends none.

{
  "id": "5b2e8c1d-7a4f-4e3b-9c6d-1f0a2b3c4d5e",
  "title": "Ravi Traders — 50 POS terminals",
  "pipeline": {
    "id": 3,
    "name": "Retail sales"
  },
  "stage": {
    "id": 14,
    "name": "Won"
  },
  "status": "won",
  "value_minor": 11800000,
  "currency": "INR",
  "contact": {
    "id": "9d4f2a61-3c8e-4b7a-a5d2-6e1f0b8c7a34",
    "name": "Ravi Kumar",
    "phone": "[phone]"
  },
  "notes": "Wants delivery before Diwali.",
  "stage_entered_at": "2026-10-06T12:30:05+05:30",
  "closed_at": "2026-10-06T12:30:05+05:30",
  "created_at": "2026-10-01T11:08:12+05:30",
  "updated_at": "2026-10-06T12:30:05+05:30"
}

Errors

Every refusal is {"error": {"code", "message", "field"}}; field is there when one input is at fault.

Status	Error code	When
400	invalid_request	stage isn’t a stage of the deal’s pipeline, status isn’t open, won or lost, title is empty or too long, value_minor isn’t a whole number of 0 or more, contact isn’t one of the account’s, or notes is too long. field names it.
404	not_found	No deal of this account’s has that id.
404	module_off	The account doesn’t have Pipelines on.
403	scope_missing	The key doesn’t have the crm.deals:write scope.

Any request can also be refused for its key, its account or its rate (key_required, invalid_key, account_suspended, plan_excludes_api, address_not_allowed, rate_limited); see the overview.