Skip to main content
OpportunitiesVersion: v3New

Create Opportunity

POST/opportunities

Create an opportunity. contactId is optional. 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. Creating a second opportunity for the same contact in the same pipeline returns 400 with code: OPPORTUNITY_NO_DUPLICATE and the existing opportunity id in meta.existingId.

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

Body

pipelineIdstringrequired

pipeline Id

Example:VDm7RPYC2GLUvdpKmBfC
locationIdstringrequired

Identifier of the location (sub-account)

Example:ve9EPM428h8vShlRW1KT
namestringrequired

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
statusstringrequired

Current status of the opportunity

Available optionsopenwonlostabandoned
Example:open
contactIdstring

Identifier of the contact linked to the opportunity. Optional: an opportunity can be created without a contact. 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.

Example:mTkSCb1UBjb5tk4OvB69
monetaryValuenumber

Monetary value of the opportunity

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 status is lost, and ignored otherwise. 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 set, 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