List or filter opportunities

• 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,

• query is an optional search query filter. Only opportunity properties may be used in the filter. For example, note:important will only show opportunities which contain the text important in their note. Or, status_change(old_status:active new_status:won date:yesterday) will only show opportunities that transitioned from status active to status won on the previous day.

• _order_by allows: date_won, date_updated, date_created, confidence, user_name, value, annualized_value, annualized_expected_value (each of them allows descending order by prepending a minus, e.g. _order_by=-date_won).

• value_period allows: one_time, monthly, annual.

• Multiple values for user_id, status_id, status_label, status_type and value_period can be specified using the in operator, e.g. status_type__in=active,won.

• _group_by allows: user_id, date_won__week, date_won__month, date_won__quarter date_won__year to group results by the given criteria.

  When grouping results, 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. Group order can be reversed by prepending a minus. For example, _group_by=-date_won__week will show the most recent weeks first. When grouping by user_id, results are ordered by the user's full name.

• lead_saved_search_id is an optional lead Smart View filter.

• (deprecated) lead_query is an optional lead search text-based query filter. This parameter is now deprecated in favor of using the lead_saved_search_id Smart View ID parameter.