List or filter opportunities
List the opportunities in your organization, most recently created first. Only opportunities you have access to are returned.
-
All opportunity list responses contain the following aggregate values about all the matching objects (regardless of pagination / limits):
total_results: the total number of objects,count_by_value_period: a dictionary containing the number of opportunities by value period, e.g.{ 'one_time': 2, 'annual': 1, 'monthly': 1 },total_value_one_time: the sum of the values of all one time opportunities,total_value_monthly: the sum of the values of all monthly opportunities,total_value_annual: the sum of the values of all annual opportunities,total_value_annualized: the sum of the values of all opportunities where monthly opportunity values are multiplied by 12,expected_value_one_time: the sum of the values of all one time opportunities multiplied by their confidence,expected_value_monthly: the sum of the values of all monthly opportunities multiplied by their confidence,expected_value_annual: the sum of the values of all annual opportunities multiplied by their confidence,expected_value_annualized: the sum of the values of all opportunities multiplied by their confidence where monthly opportunity values are multiplied by 12,
-
When grouping results with
_group_by, thedataarray contains a list of groups instead of objects. A group consists of the following fields:keycontaining a unique group key,objectscontaining the list of objects for the given group,total_resultscontaining the number of total objects for the given group,- all aggregate values for the given group,
- if grouping by year:
year, containing the year for the given group, - if grouping by month:
yearandmonth, containing the year and month (1-12) for the given group, - if grouping by quarter:
yearandquarter, containing the year and quarter (1-4) for the given group, - if grouping by week:
weekyearandweek, containing the ISO week year and ISO week number for the given group, - if grouping by user:
user_idanduser_name, containing the user ID and full name of the user for the given group.
Note that pagination still applies to objects and not groups. The last or first group may be cut off during pagination, therefore
total_resultsmay not match the length ofobjects. When paginating, thekeyvalue may be used to combine groups across multiple pages. Sorting using_order_bymay be applied and sorts the items within each of the groups. When grouping byuser_id, results are ordered by the user’s full name.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Query parameters
Comma-separated list of fields to include in the response.
Only return opportunities on this lead, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O
Only return opportunities owned by this user, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. A group ID (group_...) matches opportunities owned by any member of the group.
Comma-separated list of user or group IDs. Only return opportunities owned by any of them.
Only return opportunities with this status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk
Comma-separated list of status IDs. Only return opportunities with any of these statuses.
Only return opportunities whose status has this type: active, won or lost
Comma-separated list of status types, e.g. active,won. Only return opportunities whose status has any of these types.
Only return opportunities whose status has this label, e.g. Active. Matching ignores case. Returns an error if more than one status has the label.
Comma-separated list of status labels. Only return opportunities whose status has any of these labels. Matching ignores case.
Only return opportunities with this status, given as a status ID or label. See status_id and status_label.
Comma-separated list of status IDs or labels. Only return opportunities with any of these statuses.
Only return opportunities whose date_won is on or after this date, e.g. 2024-01-31. Any time part is ignored.
Only return opportunities whose date_won is after this date, e.g. 2024-01-31. Any time part is ignored.
Only return opportunities whose date_won is on or before this date, e.g. 2024-01-31. Any time part is ignored.
Only return opportunities whose date_won is before this date, e.g. 2024-01-31. Any time part is ignored.
Only return opportunities created at or after this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities created after this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities created at or before this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities created before this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities last updated at or after this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities last updated after this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities last updated at or before this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities last updated before this time, as an ISO 8601 date or timestamp, e.g. 2024-01-31T09:00:00Z. Values without a UTC offset are treated as UTC.
Only return opportunities with this value_period: one_time, monthly or annual
Comma-separated list of value periods, e.g. monthly,annual. Only return opportunities with any of these value periods.
Deprecated: use Advanced Filtering instead. Search query in Close’s search syntax, matched against opportunity fields, e.g. note:important or status_change(old_status:active new_status:won date:yesterday)
Deprecated: use Advanced Filtering instead. Search query in Close’s search syntax. Only return opportunities on leads that match it. Can’t be combined with lead_saved_search_id.
ID of a lead Smart View, e.g. save_.... Only return opportunities on leads in the Smart View. Can’t be combined with lead_query.
true to only return stalled opportunities, or false to only return opportunities that aren’t stalled
Field to sort by: date_won, date_updated, date_created, confidence, user_name, value, annualized_value or annualized_expected_value. Prefix with - for descending order, e.g. -date_won. Defaults to -date_created. Invalid values are ignored.
Group results by user_id, date_won__week, date_won__month, date_won__quarter or date_won__year. Prefix with - to reverse the order of the groups. When set, data holds groups of opportunities instead of opportunities.