Update an opportunity. Unless the location allows duplicate opportunities (allowDuplicateOpportunity), a contact can have only one opportunity per pipeline. Opportunities without a contact are never treated as duplicates. Moving an opportunity to a pipeline where its contact already has an opportunity returns 400 with code: OPPORTUNITY_NO_DUPLICATE.
Authorizations
Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <token>, where <token> is your access token.
Name of the opportunity, up to 150 characters. A longer name returns 422, unless it is the name already stored.
Possible values:<= 150 characters
Example:First Opps
pipelineStageIdstring
Identifier of the pipeline stage
Example:7915dedc-8f18-44d5-8bc3-77c04e994a10
statusstring
Current status of the opportunity
Available optionsopenwonlostabandoned
Example:open
monetaryValuenumber
Monetary value of the opportunity. null leaves the stored value unchanged, and the response shows the stored value. An empty string is ignored the same way. Send 0 to clear the value.
Possible values:>= 0
Example:220
forecastExpectedCloseDatestring
Expected close date. Supported formats: YYYY/MM/DD, MM/DD/YYYY, YYYY-MM-DD, MM-DD-YYYY, YYYY.MM.DD, MM.DD.YYYY, or ISO 8601
Example:2026-04-23
forecastProbabilitynumber
Forecast probability
Example:20
assignedTostring
Identifier of the user the opportunity is assigned to
Example:082goXVW3lIExEQPOnd3
lostReasonIdstring
Lost reason id (24-character hex) from GET /opportunities/lost-reason. Used only when the opportunity's status is, or is set to, lost; any other status clears the stored lost reason, and null clears it too. A malformed id returns 400 LOST_REASON_NOT_FOUND; an id that is unknown, deleted or from another location is saved as null.
Example:65f1c2a4e8b9d3f7a2c4e6b8
customFieldsobject[]
Custom field values to update, each with fieldValue. Identify each field by id or by key (without the opportunity. prefix). Entries that match no opportunity custom field in the location are ignored, not rejected. field_value is the 2021-07-28 name and is ignored in v3.
Custom field id. Pass either id or key. An id that matches no opportunity custom field in the location is ignored.
Example:6dvNaf7VhkQ9snc5vnjJ
customFields[].keystring
Custom field key without the opportunity. prefix (for opportunity.my_custom_field, send my_custom_field). Pass either id or key. A key sent with the prefix, or one that matches no custom field, is ignored.
Example:my_custom_field
customFields[].fieldValuestring
Value of the custom field
Example:9039160788
Response
application/json
Successful response
opportunityobject
The created or retrieved opportunity object
opportunity.idstring
Unique identifier of the opportunity
Example:yWQobCRIhRguQtD2llvk
opportunity.namestring
Name of the opportunity
Example:testing
opportunity.monetaryValuenumber
Monetary value of the opportunity
Example:500
opportunity.pipelineIdstring
Identifier of the pipeline the opportunity belongs to
Example:VDm7RPYC2GLUvdpKmBfC
opportunity.pipelineStageIdstring
Identifier of the pipeline stage the opportunity is in
Example:e93ba61a-53b3-45e7-985a-c7732dbcdb69
opportunity.assignedTostring
Identifier of the user the opportunity is assigned to
Example:zT46WSCPbudrq4zhWMk6
opportunity.statusstring
Current status of the opportunity
Example:open
opportunity.sourcestring
Source of the opportunity
Example:
opportunity.lastStatusChangeAtstring
ISO 8601 timestamp of the last status change
Example:2021-08-03T04:55:17.355Z
opportunity.lastStageChangeAtstring
ISO 8601 timestamp of the last stage change
Example:2021-08-03T04:55:17.355Z
opportunity.lastActionDatestring
ISO 8601 timestamp of the last action on the opportunity
Example:2021-08-03T04:55:17.355Z
opportunity.createdAtstring
ISO 8601 timestamp when the opportunity was created
Example:2021-08-03T04:55:17.355Z
opportunity.updatedAtstring
ISO 8601 timestamp when the opportunity was last updated
Example:2021-08-03T04:55:17.355Z
opportunity.forecastExpectedCloseDatestring
Expected close date for the forecast (YYYY-MM-DD)
Example:2026-05-20
opportunity.forecastOriginalCloseDatestring
Original forecast close date before any slippage (YYYY-MM-DD)
Example:2026-05-01
opportunity.forecastSlippageCountnumber
Number of times the close date has slipped
Example:2
opportunity.forecastDaysSlippednumber
Total days the close date has slipped
Example:19
opportunity.forecastLastSlippedAtstring
ISO 8601 timestamp of the last close-date slip
Example:2026-05-22T10:30:00.000Z
opportunity.forecastProbabilitynumber
Forecast win probability percentage (0–100)
Example:20
opportunity.effectiveProbabilitynumber
Effective win probability after stage and forecast adjustments (0–100)
Example:40
opportunity.contactIdstringnullable
Identifier of the contact linked to the opportunity. Absent/null for contactless opportunities.
Example:zT46WSCPbudrq4zhWMk6
opportunity.locationIdstring
Identifier of the location (sub-account) the opportunity belongs to
Same value as pipelineStageId, kept for older clients. Search results only.
Example:e93ba61a-53b3-45e7-985a-c7732dbcdb69
opportunity.relationsobject[]
Records linked to the opportunity through associations. Search results only. When the opportunity has a contact, this always includes the primary contact relation (associationIdOPPORTUNITIES_CONTACTS_ASSOCIATION, primary: true, objectKeycontact, recordId the contact id).
opportunity.attributionsobject[]
Attribution sessions recorded for the opportunity (first and last touch). Search results only; an empty list when there are none.
opportunity.sortobject[]
Sort values of this opportunity in the result set. To get the next page of POST /opportunities/search, send the sort of the last opportunity as searchAfter, unchanged. Search results only.