Opportunities

Opportunities represent a potential deal with a given company/lead.

Opportunities have a customizable status (which always has a status_type of either active, won, or lost), and optionally can have a monetary amount associated with them. Opportunities can be associated with one or more Opportunity Custom Fields or Shared Fields.

List or filter opportunities.

GET /opportunity/{?lead_id, user_id, status_id, status_label, status_type, date_created__{lt|gt|lte|gte}, date_updated__{lt|gt|lte|gte}, date_won__{lt|gt|lte|gte}, value_period, query, _order_by, _group_by, _fields, lead_saved_search_id}

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

Create an opportunity.

POST /opportunity/

status_id (optional)

• Post a status_id to create an opportunity with a specific status.
• If status_id is omitted, the organization's default (first) status will be used when creating new opportunities.
• You can fetch available statuses from the Opportunity Status API.

custom.FIELD_ID (optional)

• You can set custom fields by setting custom.FIELD_ID to the field value, where FIELD_ID is the ID of the custom field, e.g.:

{
    "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value",
    "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": "other value"
}

• Note that if a custom field has accepts_multiple_values: true, the entire value will be replaced. For example, given an Opportunity has a Custom Choice Field with value ["A", "B"], adding choice "C" would mean setting the value to ["A", "B", "C"].

• Note that using the custom field dict or the custom.FIELD_NAME syntax (instead of custom field IDs) is deprecated and will be removed from the API.

• See the Custom Fields paragraph for more details.

lead_id (optional)

• Opportunities belong to exactly one Lead (specified by lead_id).
• If you do not provide a lead_id then a new lead will be created, and the opportunity will be associated with that lead.
• This newly created lead will not have a name; it will appear in the Close UI as "Untitled".

Retrieve an opportunity.

GET /opportunity/{id}/

Update an opportunity.

PUT /opportunity/{id}/

status_id

• See description for status_id in POST /opportunity/ above.
• Setting the status_id to a status with a type of won will automatically set the date_won field if it is not already set or provided in the request. Reverting it from a won status to an active or lost will not automatically change date_won.

date_won (optional):

• If not set on the resource or in the request, the date_won will be set automatically to today's date when setting status_id to a status with type won. The x-tz-offset header, used to pass your timezone's UTC offset, will be taken into account.

custom.FIELD_ID (optional)

• See description for custom.FIELD_ID in POST /opportunity/ above.
• Additionally, you can unset a single field by using { "custom.FIELD_ID": null }, e.g.:

{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": null }

If you're trying to update a custom field and that custom field accepts multiple values, you can also specify .add or .remove as part of the field key to add/remove a single value to/from a list of values, e.g.:

{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }

Delete an opportunity.

DELETE /opportunity/{id}/