ChatGPT ↗
Claude ↗This page documents the canonical HTTP contract. Switch to the CLI example when you want the operator workflow.
PATCH fields are at the top level of the JSON body. Moving into a won stage can mark direct contacts as customers and exit linked account leads from prospecting sequences. Archive through DELETE when the Deal should leave default active lists.
Path parameters
deal_idrequiredstring
Exact Deal ID.
| Name | Type | Description |
|---|---|---|
| deal_idrequired | string | Exact Deal ID. |
Body parameters
name· optionalstring
New Deal name.
primary_company_id· optionalstring | null
Primary linked company ID.
company_ids· optionalarray<string> | null
Linked company IDs; null clears the list.
lead_ids· optionalarray<string> | null
Linked lead IDs; null clears the list.
owner_user_id· optionalstring | null
Active owner user in this organization, or null to clear.
amount· optionalobject | null
Deal value, or null to clear.
pipeline_id· optionalstring | null
Pipeline ID; set with stage_id when changing pipelines.
stage_id· optionalstring | null
Stage in the selected active pipeline.
expected_close_date· optionaldate | null
actual_close_date· optionaldate | null
next_step· optionalstring | null
custom_fields· optionalobject
Updates validated Deal custom-field values.
record_status· optionalstring
active or archived. Use active to restore an archived Deal; DELETE also archives.
| Name | Type | Description |
|---|---|---|
| name | string | New Deal name. |
| primary_company_id | string | null | Primary linked company ID. |
| company_ids | array<string> | null | Linked company IDs; null clears the list. |
| lead_ids | array<string> | null | Linked lead IDs; null clears the list. |
| owner_user_id | string | null | Active owner user in this organization, or null to clear. |
| amount | object | null | Deal value, or null to clear. |
| pipeline_id | string | null | Pipeline ID; set with stage_id when changing pipelines. |
| stage_id | string | null | Stage in the selected active pipeline. |
| expected_close_date | date | null | - |
| actual_close_date | date | null | - |
| next_step | string | null | - |
| custom_fields | object | Updates validated Deal custom-field values. |
| record_status | string | active or archived. Use active to restore an archived Deal; DELETE also archives. |
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid field, association, owner, pipeline, or stage. |
| 401 | Authentication required. |
| 403 | Missing deals:write scope. |
| 404 | Deal not found in this organization. |
| 422 | Invalid Deal payload. |