Opportunity Object

When you create a Salesforce opportunity with a contact role that’s associated with a Account Engagement prospect, we create a read-only opportunity in Account Engagement. To use Account Engagement opportunities, first set up the Account Engagement-Salesforce connector. Learn more about opportunities in Salesforce Help.

Include the authentication header with every request. For information on how to authenticate, see Authentication.

Resource NameOperationDescription
Opportunity CreatePOSTCreate an opportunity record. Available only in legacy accounts without a CRM connector.
Opportunity DeleteDELETEDelete an opportunity. Available only in legacy accounts without a CRM connector.
Opportunity ReadGETRequest information for a single opportunity.
Opportunity QueryGETRequest information for the opportunities that match the specified criteria.
Opportunity UpdatePOSTUpdate an opportunity's information. Available only in legacy accounts without a CRM connector.
Opportunity UndeleteGET and POSTRestore a deleted opportunity. Available only in legacy accounts without a CRM connector.

Create an opportunity with the specified fields. Include either the prospect's email or the prospect's ID.

Replace <prospect_email> with the prospect's email address.

Replace <prospect_id> with the prospect's Account Engagement ID.

You can use the following parameters when creating an opportunity.

ParameterTypePossible ValuesDescription
namestringAny stringThe name of the opportunity.
valueintegerAny integerThe opportunity's value.
probabilityintegerAny integer from 0 through 100The probability of winning the opportunity.
prospect_emailstringThe prospect's email address.If you’re creating the opportunity by prospect ID, you can also include the prospect's email address. If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error.
prospect_idintegerAny valid prospect ID.If you’re creating the opportunity by prospect email, you can also include the prospect's ID. If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error.

Use a prospect's email address to create an opportunity with the name "Large Customer Opportunity", a value of 100, a probability of 70%. The prospect's email address is jdoe@company.com.

Delete the specified opportunity. This request doesn’t delete the visitor activities or score changes for the prospect who is associated with the opportunity.

If this request is successful, it doesn’t return a response.

Replace <ID> with the Account Engagement ID of the opportunity.

Delete the opportunity with Account Engagement ID 1234.

Request information for a single opportunity.

Replace <ID> with the Account Engagement ID of the opportunity.

Request information for the opportunity with Account Engagement ID 1234.

Request information about the opportunities that match the specified criteria. You can specify which opportunities and which fields to request. A maximum of 200 opportunities are returned, unless you specify the output as mobile. If you specify the output as mobile, then all opportunities are returned.

Note: To request information about a specific opportunity, use Opportunity Read.

Use these parameters to specify which opportunities are returned. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

ParameterTypePossible ValuesDescription
created_afterstringtoday, yesterday, last_7_days, this_month, last_month,<custom_time>Request opportunities created after the specified date and time. Example: To request forms created in 2020, use /api/opportunities/version/3/do/query?created_after=2019-12-31 24:59:59.
created_beforestringtoday, yesterday, last_7_days, this_month, last_month, <custom_time>Request opportunities created before the specified date and time. Doesn’t include opportunities created at the specified time. <custom_time> Example: to request opportunities created before today (but not created today), use /api/opportunity/version/3/do/query?created_before=today.
id_greater_thanintegerAny positive integerRequest opportunities that have an Account Engagement ID greater than the specified number.
id_less_thanintegerAny positive integerRequest opportunities that have an Account Engagement ID less than the specified number.
probability_greater_thanintegerAny integer from 1 through 100Request opportunities that have a probability greater than the specified number.
probability_less_thanintegerAny integer from 1 through 100Request opportunities that have a probability less than the specified number.
prospect_emailstringAny valid prospect emailRequest opportunities associated with the prospect having the specified email. Note: If you specify a prospect's email and a prospect's ID, ensure the email and ID belong to the same prospect. Otherwise, the request returns an error.
prospect_idintegerAny valid prospect IDRequest opportunities associated with the prospect having the specified ID. Note: If you specify a prospect's email and a prospect's ID, ensure the email and ID belong to the same prospect. Otherwise, the request returns an error.
value_greater_thanintegerAny integerRequest opportunities that have a value greater than the specified number.
value_less_thanintegerAny integerRequest opportunities that have a value less than the specified number.

Use these parameters to specify which opportunity fields are returned, and how the opportunities are sorted.

ParameterTypePossible ValuesDescription
limitintegerAny integer from 1 through 200.The number of opportunities to return. Default value is 200.
offsetintegerAny positive integerThe number of opportunities to omit from the response (the number to "skip over"). Example: Retrieve a list of opportunities, omitting the 50 most recently updated opportunities. Sort the query by the probability field and use offset=50: /api/opportunity/version/3/do/query?offset=50&sort_by=probability
outputstringsimple, mobile, fullSpecify the level of detail in the XML response. For more information, see XML Response Format.
sort_bystringcreated_at, id, probability, valueThe field by which the results are sorted. See Sort Order.
sort_orderstringascending, descendingThe sort order. The default value depends on which sort_by value you specify. See Sort Order.

Use sort_by to specify which field Account Engagement uses to sort the results. Different fields have different default sort orders.

ValueDefault Sort OrderDescription
created_atdescendingSort the results by the opportunities' created_at timestamps.
idascendingSort the results by the opportunities' id fields.
probabilitydescendingSort the results by the opportunities' probability fields.
valuedescendingSort the results by the opportunities' value fields.

Request a list of opportunities, sorted in ascending order by probability.

Restores the specified opportunity, which has been deleted. If this request is successful, it doesn’t return a response.

Replace <ID> with the Account Engagement ID of the opportunity.

Restore the opportunity with Account Engagement ID 1234.

Update an opportunity's information. Fields that aren’t specified in the request aren’t changed. To clear a field, use a null value.

Replace <ID> with the Account Engagement ID of the opportunity.

You can use any editable opportunity field as a parameter. For a list of opportunity fields, see Object Field References.

To update an opportunity's name to "Large Opportunity", use the following command:

The XML response for a query request contains information about multiple opportunities. The XML response for a read request contains information about a single opportunity.

TagDescription
<result>Parent tag. Contains the opportunities that match the parameters specified in your query.
<total_results>The number of opportunities selected by the query. Note: The query request returns a maximum of 200 opportunities. If your query matches more than 200 opportunities, you can make several requests to retrieve all matching records.
<opportunity>The information for a single opportunity. For information about opportunity fields, see Opportunity.

For output=full:

For output=simple:

For output=mobile:

TagDescription
<opportunity>The information for a single opportunity. For information about opportunity fields, see Opportunity.
<campaign>The Account Engagement ID and name of the campaign to which this opportunity has been assigned.
<prospects>Contains all prospects associated with this opportunity.
<opportunity_activities>Contains all visitor activities associated with this opportunity.
<visitor_activity>Contains information for a visitor activity. For information about visitor activity fields, see Visitor Activity.