Sales Pipelines

Read boards and deals, create and move a deal, close it as lost, and avoid overwriting changes.

A pipeline is a board of stages; a deal is a card on it. Every workspace has a default board, marked with is_default: true in the list. Boards and stages are managed in the dashboard; read the board id from the list endpoint.

List boards and their deals

curl https://app.softsolz.uk/api/v1/services/pipelines/pipelines \
  -H "Authorization: Bearer sk_live_your_key"

Add a deal

curl -X POST https://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"Website rebuild","value_cents":250000,"contact_id":"..."}'

Move it to another stage

Send only stage_id to move a deal. Send other fields to edit it in place. Both go to the same endpoint.

curl -X PATCH https://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals/{deal_id} \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stage_id":"..."}'

Close a deal as lost

Moving a deal to a lost stage closes it. Send lost_reason (text) or lost_reason_id with the move, or afterwards while the deal is lost. A reason on a deal that is not lost is refused with 409 deal_not_lost. Moving it back to a working stage reopens it and clears the reason.

Avoid overwriting someone else

Send expected_updated_at (the updated_at you last read) with an update. If somebody changed the deal first you get a 409 instead of a silent overwrite; read the deal again and retry.

Line items and the deal value

Once a deal has line items, its value is the sum of the lines, so add or change lines instead of sending value_cents. Quantity must be more than zero, unit prices are whole cents, and a discount is 0 to 100 percent. Out of range values answer 400 with a code such as invalid_quantity.

Strict input

A field that is not documented is refused with 400 unknown_field naming it. The deal status cannot be sent: it follows the stage. A board that does not exist answers 404 pipeline_not_found, and a deal that is not on that board answers 404 deal_not_found.

Events

Register a webhook endpoint to receive pipelines.deal_created, pipelines.deal_stage_changed, pipelines.stage_entered, pipelines.deal_won, pipelines.deal_lost, pipelines.deal_rotting, pipelines.deal_assigned and pipelines.deal_value_changed.