Skip to navigation

List or filter opportunities

View as Markdown

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, the data array contains a list of groups instead of objects. A group consists of the following fields:

    • key containing a unique group key,
    • objects containing the list of objects for the given group,
    • total_results containing 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: year and month, containing the year and month (1-12) for the given group,
    • if grouping by quarter: year and quarter, containing the year and quarter (1-4) for the given group,
    • if grouping by week: weekyear and week, containing the ISO week year and ISO week number for the given group,
    • if grouping by user: user_id and user_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_results may not match the length of objects. When paginating, the key value may be used to combine groups across multiple pages. Sorting using _order_by may be applied and sorts the items within each of the groups. When grouping by user_id, results are ordered by the user’s full name.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

_limitintegerOptional<=1000Defaults to 100
Number of results to return. The maximum is 250 for requests authenticated with an API key.
_skipintegerOptional<=250000Defaults to 0
Number of results to skip before returning, for pagination. The maximum is 35,000 for some organizations.
_fieldsstringOptional

Comma-separated list of fields to include in the response.

lead_idstring or nullOptional

Only return opportunities on this lead, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O

user_idstring or nullOptional

Only return opportunities owned by this user, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. A group ID (group_...) matches opportunities owned by any member of the group.

user_id__instring or nullOptional

Comma-separated list of user or group IDs. Only return opportunities owned by any of them.

status_idstring or nullOptional

Only return opportunities with this status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk

status_id__instring or nullOptional

Comma-separated list of status IDs. Only return opportunities with any of these statuses.

status_typestring or nullOptional

Only return opportunities whose status has this type: active, won or lost

status_type__instring or nullOptional

Comma-separated list of status types, e.g. active,won. Only return opportunities whose status has any of these types.

status_labelstring or nullOptional

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.

status_label__instring or nullOptional

Comma-separated list of status labels. Only return opportunities whose status has any of these labels. Matching ignores case.

statusstring or nullOptional

Only return opportunities with this status, given as a status ID or label. See status_id and status_label.

status__instring or nullOptional

Comma-separated list of status IDs or labels. Only return opportunities with any of these statuses.

date_won__gtestring or nullOptional

Only return opportunities whose date_won is on or after this date, e.g. 2024-01-31. Any time part is ignored.

date_won__gtstring or nullOptional

Only return opportunities whose date_won is after this date, e.g. 2024-01-31. Any time part is ignored.

date_won__ltestring or nullOptional

Only return opportunities whose date_won is on or before this date, e.g. 2024-01-31. Any time part is ignored.

date_won__ltstring or nullOptional

Only return opportunities whose date_won is before this date, e.g. 2024-01-31. Any time part is ignored.

date_created__gtestring or nullOptional

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.

date_created__gtstring or nullOptional

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.

date_created__ltestring or nullOptional

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.

date_created__ltstring or nullOptional

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.

date_updated__gtestring or nullOptional

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.

date_updated__gtstring or nullOptional

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.

date_updated__ltestring or nullOptional

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.

date_updated__ltstring or nullOptional

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.

value_periodstring or nullOptional

Only return opportunities with this value_period: one_time, monthly or annual

value_period__instring or nullOptional

Comma-separated list of value periods, e.g. monthly,annual. Only return opportunities with any of these value periods.

querystring or nullOptional

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)

lead_querystring or nullOptional

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.

lead_saved_search_idstring or nullOptional

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.

is_stalledstring or nullOptional

true to only return stalled opportunities, or false to only return opportunities that aren’t stalled

_order_bystring or nullOptional

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_bystring or nullOptional

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.

Response

Successful response
datalist of objects
The results on this page.
has_moreboolean
Whether more results exist after this page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error