HighLevel: Opportunities schemas

← Opportunities operations · All schemas

Add Followers — opportunities add Followers Opportunity — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
followers	array	Required within parent	Array of user IDs to add or remove as followers (max 10)
followers[]	string	Each item

Add Followers — opportunities add Followers Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
followers	array	Optional	Current list of all follower user IDs after the operation
followers[]	string	Each item
followersAdded	array	Optional	User IDs that were successfully added as followers
followersAdded[]	string	Each item

Create Opportunity — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Identifier of the user the opportunity is assigned to
contactId	string	Required within parent	Identifier of the contact linked to the opportunity
customFields	array	Optional	Add custom fields to opportunities.
customFields[]	JSON	Each item
customFields[] (anyOf 1)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input String Schema V3
customFields[] (anyOf 2)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Array Schema V3
customFields[] (anyOf 3)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Object Schema V3
forecastExpectedCloseDate	string	Optional	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
forecastProbability	number	Optional	Forecast probability
locationId	string	Required within parent	Identifier of the location (sub-account)
monetaryValue	number	Optional	Monetary value of the opportunity
name	string	Required within parent	Name of the opportunity
pipelineId	string	Required within parent	pipeline Id
pipelineStageId	string	Optional	Identifier of the pipeline stage
status	string	Required within parent	Current status of the opportunity One of: open, won, lost, abandoned, all

Referenced models: Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Array Schema V3, Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Object Schema V3, Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input String Schema V3

Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Array Schema V3

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	array	Optional	Value of the custom field
fieldValue[]	string	Each item
id	string	Required within parent	Pass either `id` or `key` of custom field
key	string	Optional	Pass either `id` or `key` of custom field

Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Object Schema V3

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	object	Optional	Value of the custom field
id	string	Required within parent	Pass either `id` or `key` of custom field
key	string	Optional	Pass either `id` or `key` of custom field

Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input String Schema V3

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	string	Optional	Value of the custom field
id	string	Optional	Pass either `id` or `key` of custom field
key	string	Optional	Pass either `id` or `key` of custom field

Delete Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
succeded	boolean	Optional	Indicates whether the operation was successful. Deprecated — use `success` instead.
success	boolean	Optional	Indicates whether the operation was successful

Get Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
opportunity	JSON	Optional	The created or retrieved opportunity object
opportunity (allOf 1)	Model	All variants apply	Expand Search Opportunity — response body — opportunities item

Referenced models: Search Opportunity — response body — opportunities item

Get Pipelines — response body

Field	Type	Presence	Description and constraints
$	object	Root
pipelines	array	Optional	List of pipelines for the location
pipelines[]	Model	Each item	Expand Get Pipelines — response body — pipelines item

Referenced models: Get Pipelines — response body — pipelines item

Get Pipelines — response body — pipelines item

Field	Type	Presence	Description and constraints
$	object	Root
colorRenderMode	string	Optional	How pipeline/stage colors are rendered Known values: dot, bg-tint, none
id	string	Optional	Unique identifier of the pipeline
locationId	string	Optional	Identifier of the location (sub-account) this pipeline belongs to
name	string	Optional	Name of the pipeline
showInFunnel	boolean	Optional	Whether the pipeline is shown in the funnel view
showInPieChart	boolean	Optional	Whether the pipeline is shown in the pie chart view
stages	array	Optional	Stages belonging to this pipeline
stages[]	array	Each item
useOpportunityProbability	boolean	Optional	Whether stage-level win probability is enabled for this pipeline

Get lost reason — response body

Field	Type	Presence	Description and constraints
$	object	Root
lostReasons	array	Optional	List of lost reasons for the location
lostReasons[]	Model	Each item	Expand Get lost reason — response body — lost Reasons item
total	JSON	Optional
total (anyOf 1)	number	Alternative	Total number of lost reasons matching the query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Get lost reason — response body — lost Reasons item

Get lost reason — response body — lost Reasons item

Field	Type	Presence	Description and constraints
$	object	Root
createdAt	string	Optional	created at Format: date-time
id	string	Optional	lost reason id
locationId	string	Optional	location id
name	string	Optional	lost reason name
updatedAt	string	Optional	updated at Format: date-time

Remove Followers — opportunities remove Followers Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
followers	array	Optional	Current list of all follower user IDs after the operation
followers[]	string	Each item
followersRemoved	array	Optional	User IDs that were successfully removed as followers
followersRemoved[]	string	Each item

Search Opportunities — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
additionalDetails	JSON	Required within parent	Flags to include additional related entities in the response
additionalDetails (allOf 1)	Model	All variants apply	Expand Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations
limit	number	Required within parent	Maximum number of results to return per page
locationId	string	Required within parent	Location Id
page	number	Required within parent	Page number (0-indexed)
query	string	Required within parent	Full-text search query string (max 75 characters)
searchAfter	array	Required within parent	Search-after cursor values for deep pagination
searchAfter[]	string	Each item

Referenced models: Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations

Search Opportunities — request body — body additional Details calendar Events, notes, tasks, un Read Conversations

Field	Type	Presence	Description and constraints
$	object	Root
calendarEvents	boolean	Required within parent	Include calendar events in the response
notes	boolean	Required within parent	Include notes in the response
tasks	boolean	Required within parent	Include tasks in the response
unReadConversations	boolean	Required within parent	Include unread conversations count in the response

Search Opportunities — response body

Field	Type	Presence	Description and constraints
$	object	Root
aggregations	object	Optional	Aggregation results keyed by aggregation name
opportunities	array	Optional	List of opportunities matching the search criteria
opportunities[]	Model	Each item	Expand Search Opportunity — response body — opportunities item
stageAggregations	array	Optional	Per-stage totals when pipeline filter is present
stageAggregations[]	Model	Each item	Expand Search Opportunities — response body — stage Aggregations item
total	JSON	Required within parent
total (anyOf 1)	number	Alternative	Total number of opportunities matching the query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Search Opportunity — response body — opportunities item, Search Opportunities — response body — stage Aggregations item

Search Opportunities — response body — stage Aggregations item

Field	Type	Presence	Description and constraints
$	object	Root
openValue	JSON	Required within parent
openValue (anyOf 1)	number	Alternative	Total value of open opportunities in this stage
openValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
openWeightedValue	JSON	Required within parent
openWeightedValue (anyOf 1)	number	Alternative	Probability-weighted value of open opportunities in this stage
openWeightedValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pipelineStageId	string	Required within parent	Identifier of the pipeline stage being aggregated
totalCount	JSON	Required within parent
totalCount (anyOf 1)	number	Alternative	Total number of opportunities in this stage
totalCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
totalValue	JSON	Required within parent
totalValue (anyOf 1)	number	Alternative	Total monetary value of all opportunities in this stage
totalValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
weightedValue	JSON	Required within parent
weightedValue (anyOf 1)	number	Alternative	Probability-weighted total value of opportunities in this stage
weightedValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
wonValue	JSON	Required within parent
wonValue (anyOf 1)	number	Alternative	Total value of won opportunities in this stage
wonValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Search Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
aggregations	object	Optional	Aggregation results keyed by aggregation name
meta	JSON	Optional	Pagination metadata for the result set
meta (allOf 1)	Model	All variants apply	Expand Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total
opportunities	array	Optional	List of opportunities matching the search criteria
opportunities[]	Model	Each item	Expand Search Opportunity — response body — opportunities item

Referenced models: Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total, Search Opportunity — response body — opportunities item

Search Opportunity — response body — meta current Page, next Page, next Page Url, prev Page, start After, start After Id, total

Field	Type	Presence	Description and constraints
$	object	Root
currentPage	JSON	Optional
currentPage (anyOf 1)	number	Alternative	Current page number
currentPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
nextPage	JSON	Optional
nextPage (anyOf 1)	number	Alternative	Next page number
nextPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
nextPageUrl	string	Optional	URL to retrieve the next page of results
prevPage	JSON	Optional
prevPage (anyOf 1)	number	Alternative	Previous page number
prevPage (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startAfter	JSON	Optional
startAfter (anyOf 1)	number	Alternative	Cursor timestamp to use for pagination (startAfter param)
startAfter (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
startAfterId	string	Optional	Cursor id to use for pagination (startAfterId param)
total	JSON	Optional
total (anyOf 1)	number	Alternative	Total number of opportunities matching the query
total (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Search Opportunity — response body — opportunities item

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Identifier of the user the opportunity is assigned to
calendarEvents	array	Optional	Calendar events attached to the opportunity
calendarEvents[]	array	Each item
contact	JSON	Optional	Contact details associated with the opportunity
contact (allOf 1)	Model	All variants apply	Expand Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags
contactId	string	Optional	Identifier of the contact linked to the opportunity
createdAt	string	Optional	ISO 8601 timestamp when the opportunity was created
customFields	array	Optional	Custom fields associated with the opportunity
customFields[]	Model	Each item	Expand Search Opportunity — response body — opportunities item custom Fields item
effectiveProbability	JSON	Optional
effectiveProbability (anyOf 1)	number	Alternative	Effective win probability after stage and forecast adjustments (0–100)
effectiveProbability (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
externalObjectId	string	Optional	External object identifier for integrations
followers	array	Optional	User IDs following this opportunity
followers[]	array	Each item
forecastDaysSlipped	JSON	Optional
forecastDaysSlipped (anyOf 1)	number	Alternative	Total days the close date has slipped
forecastDaysSlipped (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forecastExpectedCloseDate	string	Optional	Expected close date for the forecast (YYYY-MM-DD)
forecastLastSlippedAt	string	Optional	ISO 8601 timestamp of the last close-date slip
forecastOriginalCloseDate	string	Optional	Original forecast close date before any slippage (YYYY-MM-DD)
forecastProbability	JSON	Optional
forecastProbability (anyOf 1)	number	Alternative	Forecast win probability percentage (0–100)
forecastProbability (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forecastSlippageCount	JSON	Optional
forecastSlippageCount (anyOf 1)	number	Alternative	Number of times the close date has slipped
forecastSlippageCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
id	string	Optional	Unique identifier of the opportunity
indexVersion	string	Optional	Index version of the opportunity record
lastActionDate	string	Optional	ISO 8601 timestamp of the last action on the opportunity
lastStageChangeAt	string	Optional	ISO 8601 timestamp of the last stage change
lastStatusChangeAt	string	Optional	ISO 8601 timestamp of the last status change
locationId	string	Optional	Identifier of the location (sub-account) the opportunity belongs to
lostReasonId	string	Optional	Identifier of the lost reason if the opportunity was marked lost
monetaryValue	JSON	Optional
monetaryValue (anyOf 1)	number	Alternative	Monetary value of the opportunity
monetaryValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Optional	Name of the opportunity
notes	array	Optional	Notes attached to the opportunity
notes[]	array	Each item
pipelineId	string	Optional	Identifier of the pipeline the opportunity belongs to
pipelineStageId	string	Optional	Identifier of the pipeline stage the opportunity is in
source	string	Optional	Source of the opportunity
status	string	Optional	Current status of the opportunity
tasks	array	Optional	Tasks attached to the opportunity
tasks[]	array	Each item
updatedAt	string	Optional	ISO 8601 timestamp when the opportunity was last updated

Referenced models: Search Opportunity — response body — opportunities item custom Fields item, Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags

Search Opportunity — response body — opportunities item contact company Name, email, id, name, phone, tags

Field	Type	Presence	Description and constraints
$	object	Root
companyName	string	Optional	Company name associated with the contact
email	string	Optional	Email address of the contact
id	string	Optional	Unique identifier of the contact
name	string	Optional	Full name of the contact
phone	string	Optional	Phone number of the contact
tags	array	Optional	Tags associated with the contact
tags[]	string	Each item

Search Opportunity — response body — opportunities item custom Fields item

Field	Type	Presence	Description and constraints
$	object	Root
fieldValue	JSON	Required within parent	The value of the custom field
fieldValue (anyOf 1)	string	Alternative
fieldValue (anyOf 2)	object	Alternative
fieldValue (anyOf 3)	array	Alternative
fieldValue (anyOf 3)[]	string	Each item
fieldValue (anyOf 4)	array	Alternative
fieldValue (anyOf 4)[]	object	Each item
id	string	Required within parent	Unique identifier of the custom field

Update Opportunity Status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
lostReasonId	string	Optional	lost reason Id
status	string	Required within parent	New status for the opportunity One of: open, won, lost, abandoned, all

Update Opportunity — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Identifier of the user the opportunity is assigned to
customFields	array	Optional	Update custom fields to opportunities.
customFields[]	JSON	Each item
customFields[] (anyOf 1)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input String Schema V3
customFields[] (anyOf 2)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Array Schema V3
customFields[] (anyOf 3)	Model	Alternative	Expand Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Object Schema V3
forecastExpectedCloseDate	string	Optional	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
forecastProbability	number	Optional	Forecast probability
monetaryValue	number	Optional	Monetary value of the opportunity
name	string	Optional	Name of the opportunity
pipelineId	string	Optional	pipeline Id
pipelineStageId	string	Optional	Identifier of the pipeline stage
status	string	Optional	Current status of the opportunity One of: open, won, lost, abandoned, all

Referenced models: Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Array Schema V3, Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input Object Schema V3, Create Opportunity — request body — body custom Fields item field Value, id, key — custom Fields Input String Schema V3

Upsert Opportunity — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
assignedTo	string	Optional	Identifier of the user the opportunity is assigned to
followers	array	Required within parent	contactId
followers[]	string	Each item
followersActionType	string	Required within parent	followers action type One of: add, remove
forecastExpectedCloseDate	string	Optional	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
forecastProbability	number	Optional	Forecast probability
id	string	Optional	opportunityId
isRemoveAllFollowers	boolean	Required within parent	isRemoveAllFollowers
locationId	string	Required within parent	locationId
lostReasonId	string	Optional	lost reason Id
monetaryValue	object	Optional	Monetary value of the opportunity
name	string	Optional	name
pipelineId	string	Required within parent	pipeline Id
pipelineStageId	string	Optional	Identifier of the pipeline stage
status	string	Optional	Current status of the opportunity One of: open, won, lost, abandoned, all

Upsert Opportunity — response body

Field	Type	Presence	Description and constraints
$	object	Root
new	boolean	Required within parent	Indicates whether the opportunity was newly created (true) or updated (false)
opportunity	object	Required within parent	Updated / New Opportunity