Deals
Deals represent sales opportunities moving through your pipeline. Assign deals to workflows and stages, track value and currency, map buying-committee contact roles, and forecast revenue.
The Deal Object
Section titled “The Deal Object”| Field | Type | Description |
|---|---|---|
id | uuid | Unique identifier for the deal |
account_id | uuid | ID of the account that owns the deal |
created_by | uuid | ID of the user who created the deal |
name | string | Name of the deal |
description | string | Free-form description of the deal |
stage_id | uuid? | ID of the deal workflow stage the deal is currently in |
stage_label | string | Display label of the current stage (read-only, derived from the stage) |
stage_color | string | Color token of the current stage (read-only, derived from the stage) |
stage_closed | bool | True when the current stage is a closed stage, meaning the deal is no longer open (read-only, derived from the stage) |
stage_won | bool | True when the current stage is a closed-won stage; a closed stage with this false is closed-lost (read-only, derived from the stage) |
workflow_id | uuid? | ID of the deal workflow whose stages this deal moves through |
company_id | uuid? | ID of the company associated with the deal |
company_name | string | Name of the associated company (read-only, derived from the company) |
assigned_to | uuid? | ID of the user the deal is assigned to |
assigned_name | string | Name of the assigned user (read-only, derived from the user) |
value | int? | Monetary value of the deal in integer minor units (cents) of the currency |
probability | int | Probability of winning the deal, as an integer percentage from 0 to 100 |
expected_close_date | string? | Expected close date as an ISO 8601 date (YYYY-MM-DD) |
closed_at | datetime? | ISO 8601 timestamp when the deal was closed; null while open |
closed_reason | string | Reason recorded when the deal was closed |
notes | string | Free-form notes about the deal |
tags | string[] | List of tag labels applied to the deal |
custom_fields | object | Custom field values keyed by field definition, validated against the account’s deal custom field definitions |
currency | string? | ISO 4217 currency code for the deal value One of: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, SEK, NOK, DKK, NZD, SGD, HKD, KRW, MXN, BRL, INR, ZAR, TRY, PLN, CZK, HUF, ILS, THB, MYR, PHP, IDR, RON, BGN, ISK |
timezone | string? | IANA timezone name used for interpreting the deal’s dates |
created_at | datetime | ISO 8601 timestamp when the deal was created |
updated_at | datetime | ISO 8601 timestamp when the deal was last updated |
List deals with expected close dates
Section titled “List deals with expected close dates”Endpoint: deals-calendar
Close a deal (won or lost)
Section titled “Close a deal (won or lost)”Endpoint: deals-close
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | ID of the deal to close |
stage_id | string | No | ID of the closed stage (won or lost) to move the deal into |
reason | string | No | Reason for closing the deal |
curl -X POST https://api.driftwoodapp.com/api/deals-close \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Link a contact to a deal
Section titled “Link a contact to a deal”Endpoint: deals-contacts-add
List contacts linked to a deal
Section titled “List contacts linked to a deal”Endpoint: deals-contacts-list
Remove a contact from a deal
Section titled “Remove a contact from a deal”Endpoint: deals-contacts-remove
Create a new deal
Section titled “Create a new deal”Endpoint: deals-create
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the deal |
description | string | No | Free-form description of the deal |
stage_id | string? | No | ID of the workflow stage to place the deal in; defaults to the workflow’s default stage when omitted |
workflow_id | string? | No | ID of the deal workflow to use; defaults to the account’s default workflow when omitted |
company_id | string? | No | ID of the company to associate with the deal |
assigned_to | string? | No | ID of the user to assign the deal to |
value | int? | No | Monetary value of the deal in integer minor units (cents) of the currency |
probability | int? | No | Win probability as an integer percentage from 0 to 100; values outside the range are clamped. Defaults to the stage’s default probability when omitted |
expected_close_date | string? | No | Expected close date as an ISO 8601 date (YYYY-MM-DD) |
currency | string? | No | ISO 4217 currency code for the deal value; defaults to the account’s default currency when a value is set and this is omitted One of: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, SEK, NOK, DKK, NZD, SGD, HKD, KRW, MXN, BRL, INR, ZAR, TRY, PLN, CZK, HUF, ILS, THB, MYR, PHP, IDR, RON, BGN, ISK |
timezone | string? | No | IANA timezone name used for interpreting the deal’s dates |
notes | string | No | Free-form notes about the deal |
tags | string[] | No | List of tag labels to apply to the deal |
custom_fields | object? | No | Custom field values keyed by field definition, validated against the account’s deal custom field definitions |
curl -X POST https://api.driftwoodapp.com/api/deals-create \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "..."}'Delete a deal
Section titled “Delete a deal”Endpoint: deals-delete
Get a monthly revenue forecast from open deals’ expected close dates
Section titled “Get a monthly revenue forecast from open deals’ expected close dates”Endpoint: deals-forecast
| Field | Type | Required | Description |
|---|---|---|---|
months | int | No | Number of months to forecast forward, from 1 to 24; defaults to 12 and is clamped to 24 |
curl -X POST https://api.driftwoodapp.com/api/deals-forecast \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Get a deal by ID
Section titled “Get a deal by ID”Endpoint: deals-get
Get deal pipeline insights with summary, win rate, and breakdowns
Section titled “Get deal pipeline insights with summary, win rate, and breakdowns”Endpoint: deals-insights
| Field | Type | Required | Description |
|---|---|---|---|
start_date | string | Yes | Start of the reporting period as an ISO 8601 date (YYYY-MM-DD) |
end_date | string | Yes | End of the reporting period as an ISO 8601 date (YYYY-MM-DD), inclusive |
compare_start_date | string | No | Start of an optional comparison period as an ISO 8601 date (YYYY-MM-DD); supply with compare_end_date to include comparison metrics |
compare_end_date | string | No | End of an optional comparison period as an ISO 8601 date (YYYY-MM-DD), inclusive |
curl -X POST https://api.driftwoodapp.com/api/deals-insights \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"start_date": "...", "end_date": "..."}'List deals with filters
Section titled “List deals with filters”Endpoint: deals-list
| Field | Type | Required | Description |
|---|---|---|---|
search | string | No | Text to match against deal name and related fields |
tags | string[] | No | Filter to deals having all of these tag labels |
stage_id | string? | No | Filter to deals in this workflow stage |
company_id | string? | No | Filter to deals associated with this company |
assigned_to | string? | No | Filter to deals assigned to this user |
is_closed | bool? | No | Filter by closed state; true returns closed deals, false returns open deals, omit for all |
cursor | string | No | Opaque pagination cursor returned by a previous list response |
limit | int | No | Maximum number of deals to return in the page |
curl -X POST https://api.driftwoodapp.com/api/deals-list \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Get pipeline value and deal counts broken down by stage
Section titled “Get pipeline value and deal counts broken down by stage”Endpoint: deals-pipeline-stats
| Field | Type | Required | Description |
|---|---|---|---|
workflow_id | string? | No | ID of the workflow to compute pipeline stats for; defaults to the account’s default workflow when omitted |
curl -X POST https://api.driftwoodapp.com/api/deals-pipeline-stats \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Reopen a closed deal
Section titled “Reopen a closed deal”Endpoint: deals-reopen
Update a deal
Section titled “Update a deal”Endpoint: deals-update
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | ID of the deal to update |
workflow_id | string? | No | ID of the workflow to move the deal to; when changed without a stage_id the deal moves to the new workflow’s default stage |
name | string? | No | New name for the deal |
description | string? | No | New description for the deal |
stage_id | string? | No | ID of the workflow stage to move the deal to; changing the stage resets probability to the stage default |
company_id | string? | No | ID of the company to associate; pass an empty string to clear the association |
assigned_to | string? | No | ID of the user to assign; pass an empty string to clear the assignment |
value | int? | No | Monetary value of the deal in integer minor units (cents) of the currency |
probability | int? | No | Win probability as an integer percentage from 0 to 100; values outside the range are clamped |
expected_close_date | string? | No | Expected close date as an ISO 8601 date (YYYY-MM-DD) |
currency | string? | No | ISO 4217 currency code for the deal value One of: USD, EUR, GBP, JPY, CAD, AUD, CHF, CNY, SEK, NOK, DKK, NZD, SGD, HKD, KRW, MXN, BRL, INR, ZAR, TRY, PLN, CZK, HUF, ILS, THB, MYR, PHP, IDR, RON, BGN, ISK |
timezone | string? | No | IANA timezone name used for interpreting the deal’s dates |
notes | string? | No | New notes for the deal |
tags | string[] | No | Replacement list of tag labels for the deal |
custom_fields | object? | No | Custom field values to merge, validated against the account’s deal custom field definitions |
curl -X POST https://api.driftwoodapp.com/api/deals-update \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'Error Codes
Section titled “Error Codes”| Code | Description |
|---|---|
deals.invalid_id | Invalid id |
deals.invalid_stage_id | Invalid stage id |
deals.reason_required | Reason required |
deals.not_found | Not found |
deals.name_required | Name required |
deals.invalid_workflow_id | Invalid workflow id |
deals.invalid_stage | Invalid stage |
deals.invalid_company_id | Invalid company id |
deals.invalid_assigned_to | Invalid assigned to |
deals.invalid_custom_fields | Invalid custom fields |
deals.dates_required | Dates required |
deals.invalid_start_date | Invalid start date |
deals.invalid_end_date | Invalid end date |
deals.invalid_compare_start_date | Invalid compare start date |
deals.invalid_compare_end_date | Invalid compare end date |