SoftSolzSoftSolz
Sign up
HomeAPI GuideAPI ReferenceWidget Tester
Sales Pipelines

Create a deal

Creates a deal on the board. Without a stage_id it goes into the first stage. The deal status follows the stage: open for a working stage, won or lost for a closing one. A field that is not listed here is refused with 400 unknown_field naming it (the status cannot be sent, it follows the stage). A board that does not exist answers 404 pipeline_not_found.

POSThttps://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals

Recent Requests

Kept only in this browser
TimeStatusTook
Send a request with Try it to see it here.

Path Params

pipeline_idstringrequired

Headers

Authorizationstringrequired

Bearer token: Bearer sk_live_... (or sk_test_... for sandbox). A login token will not work here.

Idempotency-Keystring

Optional idempotency key for safe retries.

Body Params

titlestringrequired

Deal name, up to 200 characters. Longer text is refused with 400 title_too_long.

value_centsinteger

Deal value in minor units (pence or cents), a whole number of zero or more. A negative, fractional or non-numeric value is refused with 400 invalid_value. While the deal has line items its value is the sum of the lines, and sending a different value is refused with 400 value_set_by_lines.

currencystring

Three-letter currency code. Leave out to use the board currency, or the workspace currency when the board has none.

owner_user_idinteger | null

Workspace member who owns the deal. Must be an active member of the workspace; null leaves it unassigned.

contact_idstring | null

Contact the deal is with. Must be a contact in this workspace. When the contact belongs to a company and company_id is not sent, the deal is linked to that company too.

company_idstring | null

Company the deal is with. Must be a company in this workspace.

expected_close_onstring | null

Expected close date as a plain YYYY-MM-DD date. Anything else is refused with 400 invalid_close_date. The forecast places the deal in this period.

sourcestring | null

Where the deal came from, up to 120 characters.

notesstring | null

Free-text notes, up to 2000 characters.

stage_idstring

Stage to put the deal in. Must be a stage on this board.

Response

Response Body

idstringDeal id.
pipeline_idstringBoard the deal sits on.
stage_idstringStage the deal is in.
stage_namestring | nullName of that stage.
titlestringDeal name.
value_centsintegerDeal value in minor units (pence or cents).
value_from_linesbooleanTrue while the deal has line items. The value is then the sum of the lines and cannot be set directly; removing the last line restores the value the deal had before lines were added, or 0.
value_displaystringThe value formatted with the workspace locale and the deal currency.
currencystring | nullThree-letter currency code. Defaults to the board or workspace currency.
statusstringOpen while in a working stage; won or lost once it reaches a closing stage.
contact_idstring | nullContact the deal is with, or null.
contact_namestring | nullContact name.
contact_emailstring | nullContact email.
company_idstring | nullCompany the deal is with, or null.
company_namestring | nullCompany name.
owner_user_idinteger | nullWorkspace member who owns the deal, or null when unassigned.
owner_namestring | nullOwner name.
expected_close_onstring | nullExpected close date as a plain YYYY-MM-DD date, or null.
closed_atstring | nullWhen the deal was won or lost (set again if it moves between won and lost), or null while open.
lost_reasonstring | nullFree-text reason the deal was lost, kept when it did not match a reason on the workspace list. Null while the deal is open.
lost_reason_idstring | nullId of the chosen lost reason from the workspace list, or null.
lost_reason_labelstring | nullLabel of that lost reason.
sourcestring | nullWhere the deal came from.
notesstring | nullFree-text notes.
win_probabilitynumber | nullWin chance of the current stage, 0-100.
probability_overridenumber | nullWin chance set on this deal that replaces the stage figure, or null.
sort_orderintegerPosition within its stage.
sort_keynumber | nullOrdering key within its stage; lower comes first.
stage_entered_atstring | nullWhen the deal entered its current stage.
rotting_atstring | nullWhen the deal counts as stalled in its current stage, or null when the stage has no stall threshold.
next_activity_atstring | nullDue time of the earliest unfinished activity, or null.
last_activity_atstring | nullWhen activity was last logged, or null.
quote_idstring | nullQuote linked to the deal, or null.
created_atstringWhen the deal was created.
updated_atstringWhen the deal was last changed.

Request

curl --request POST \
  --url https://app.softsolz.uk/api/v1/services/pipelines/pipelines/{pipeline_id}/deals \
  --header 'Authorization: Bearer sk_live_your_key' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "Acme Ltd - annual plan",
  "value_cents": 480000,
  "currency": "GBP",
  "expected_close_on": "2026-12-15",
  "source": "Website",
  "notes": "Asked for a demo next week."
}'

Credentials

Sent as a Bearer token and used in the samples above and in Try it. Kept only in this browser tab until you close it. Use an sk_test_ key to stay in your sandbox.

Response · 201

{
  "data": {
    "id": "345",
    "pipeline_id": "12",
    "stage_id": "71",
    "stage_name": "New",
    "title": "Acme Ltd - annual plan",
    "value_cents": 480000,
    "value_from_lines": false,
    "value_display": "£4,800.00",
    "currency": "GBP",
    "status": "open",
    "contact_id": null,
    "contact_name": null,
    "contact_email": null,
    "company_id": null,
    "company_name": null,
    "owner_user_id": null,
    "owner_name": null,
    "expected_close_on": "2026-12-15",
    "closed_at": null,
    "lost_reason": null,
    "lost_reason_id": null,
    "lost_reason_label": null,
    "source": "Website",
    "notes": "Asked for a demo next week.",
    "win_probability": 10,
    "probability_override": null,
    "sort_order": 0,
    "sort_key": 1000,
    "stage_entered_at": "2026-10-01T09:00:00.000Z",
    "rotting_at": null,
    "next_activity_at": "2026-10-09T10:00:00.000Z",
    "last_activity_at": null,
    "quote_id": null,
    "created_at": "2026-10-01T09:00:00.000Z",
    "updated_at": "2026-10-01T09:00:00.000Z"
  }
}