Skip to main content

​
Opportunities

Opportunities represent deals or pipeline records. The public record_type is opportunity.

​
Supported actions

ActionEndpoint
CreatePOST /api/v2/opportunity
ReadGET /api/v2/opportunity/{opportunity_id}
QueryPOST /api/v2/opportunity/_query
UpdatePATCH /api/v2/opportunity/{opportunity_id}
ArchiveDELETE /api/v2/opportunity/{opportunity_id}
Create or updateNot available
Relationships/api/v2/opportunity/{opportunity_id}/relationship/{api_name}

​
Common fields

FieldValue typeNotes
display_namestringDeal name
amountcurrencyDeal value
stageopportunity_stageRequired on create; patchable
stage_last_shifted_attimestampRead-only where available
outcomeenum-like valueRead-only
statusenum-like valueRead-only
closed_attimestampRead-only
owner_user_idrecord_referenceOwner user reference
Use GET /api/v2/_schema/opportunity for the complete field list in your workspace.

​
Create an opportunity

{
  "attributes": {
    "display_name": "Acme - Enterprise Deal",
    "amount": 150000,
    "stage": "proposal",
    "account_id": "<account_id>"
  }
}

​
Change stage

Patch the stage attribute. Do not write outcome, status, closed_at, or stage_last_shifted_at directly. 
{
  "attributes": {
    "stage": "closed_won"
  }
}

​
Contacts relationship

Opportunities expose typed contact relationship routes. 
GET  /api/v2/opportunity/{opportunity_id}/relationship/contacts
POST /api/v2/opportunity/{opportunity_id}/relationship/contacts

​
Common errors

Error codeUsually means
field_required_missingRequired opportunity field, such as display_name, stage, or account_id, was omitted
field_value_invalidStage or field value could not be resolved
field_not_updatableRequest tried to write a read-only field
unknown_relationshipRelationship API name is not declared