Skip to main content
OpportunitiesVersion: v3New

Update Opportunity

PUT/opportunities/{id}

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.

Scope:opportunities.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version. Send v3.

Available optionsv3
Example:v3

Path Parameters

idstringrequired

Opportunity Id

Example:yWQobCRIhRguQtD2llvk

Body

pipelineIdstring

pipeline Id

Example:bCkKGpDsyPP4peuKowkG
namestring

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.

Example
[
  {
    "id": "6dvNaf7VhkQ9snc5vnjJ",
    "fieldValue": "9039160788"
  }
]

Response

Successful response

opportunityobject

The created or retrieved opportunity object