Querying Opportunities
Supported Operations
Operation | URL Format | Required Parameters | Description |
---|---|---|---|
query |
/api/opportunity/version/3/do/query?... |
user_key, api_key |
Returns the opportunities matching the specified criteria parameters. See Using Opportunities for complete descriptions of opportunity XML Response Formats. Also see Opportunity in Object Field References. |
Supported Search Criteria
Search criteria may be used together in any combination and/or order unless otherwise specified. Unless output=mobile
is specified, 200 opportunities will be returned with each query request. This limit is not enforced for responses formatted with output=mobile
.
Parameter | Datatype | Options | Description |
---|---|---|---|
created_after |
string |
today, yesterday, last_7_days, this_month, last_month,<custom_time> |
Selects opportunities that were created after the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax. |
created_before |
string |
today, yesterday, last_7_days, this_month, last_month, <custom_time> |
Selects opportunities that were created before the specified time. If a <custom_time> is used, ensure that the specified date is formatted using GNU Date Input Syntax. |
id_greater_than |
integer |
Selects opportunities with IDs greater than the specified integer. | |
id_less_than |
integer |
Selects opportunities with IDs less than the specified integer. | |
probability_greater_than |
integer |
Selects opportunities with probabilities greater than the specified number. | |
probability_less_than |
integer |
Selects opportunities with probabilities less than the specified number. | |
prospect_email |
string |
Selects opportunities associated with the specified prospect. prospect_email must correspond to an existing prospect. Note: If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error. |
|
prospect_id |
integer |
Selects opportunities associated with the specified prospect. prospect_id must correspond to an existing prospect. Note: If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error. |
|
value_greater_than |
integer |
Selects opportunities that have a value greater than a specified integer. | |
value_less_than |
integer |
Selects opportunities that have a value less than a specified integer. |
Manipulating the Result Set
Since query
result sets are limited to 200 results each, the returned results may not include all opportunities that were matched by the query. The following criteria can be used to navigate through the result set and retrieve the remaining results.
Parameter | Datatype | Options | Description |
---|---|---|---|
limit |
integer |
Specifies the number of results to be returned. Default value: 200 . Note: This number cannot be larger than 200. |
|
offset |
integer |
Specifies the first matching opportunity (according to the specified sorting order) to be returned in the query response. The first offset matching opportunities will be omitted from the response. Default value: 0 . Example: Specifying offset=400 will return the results starting with the 401st opportunity matched by the provided criteria. |
|
output |
simple, mobile |
Specifies the format to be used when returning the results of the query. See XML Response Formats in Using Opportunities for more details. | |
sort_by |
string |
created_at, id, probability, value |
Specifies the field that should be used to sort the results of the query. See [Supported Sorting Options (#14770-supported-sorting-options) for more details. |
sort_order |
string |
ascending, descending |
Specifies the ordering to be used when sorting the results of the query. The default sorting order varies based on the value of the sort_by parameter. See Supported Sorting Options for more details. |
Supported Sorting Options
The ordering of the results returned by a query
request can be changed by specifying sort_by
and sort_order
parameters. Any of the following values are valid when specifying the sort_by
parameter. For a complete list of fields involved in Opportunity queries, see Opportunity in Object Field References.
Value | Default Sort Order | Description |
---|---|---|
created_at |
descending |
Specifies that the query results should be sorted by the opportunities' created_at timestamps. |
id |
ascending |
Specifies that the query results should be sorted by the opportunities' id fields. |
probability |
descending |
Specifies that the query results should be sorted by the opportunities' probability fields. |
value |
descending |
Specifies that the query results should be sorted by the opportunities' value fields. |
XML Response Format
<rsp stat="ok" version="1.0">
<result>
<total_results>...</total_results>
<opportunity>...</opportunity>
...
</result>
</rsp>
Tag | Description |
---|---|
<result> |
Contains the resulting opportunities for the specified query. |
<total_results> |
Contains the number of opportunities selected by this query. If this value is higher than 200, then several query requests may be necessary to retrieve all matched opportunities. |
<opportunity> |
The data for an individual Opportunity. See Using Opportunities for complete descriptions of opportunity XML Response Formats. Also see Opportunity in Object Field References. Note: Data concerning an opportunity's activities will NOT be included in a query response. To retrieve this data, use a read request for individual opportunities of interest. |
Using Opportunities
Supported Operations
For a complete list of fields involved in Opportunities operations, see the Opportunity section of Object Field References.
Note: If a salesforce.com or SugarCRM connector is present in the API user's account, Opportunities can be read, but they cannot be modified (created, updated, deleted or undeleted).
Operation | URL Format | Required Parameters | Description |
---|---|---|---|
create |
/api/opportunity /version/3/do/create /prospect_email /<prospect_email>?... |
user_key, api_key, prospect_email, name, value, probability |
Creates a new opportunity using the specified data. prospect_email must correspond to an existing prospect. name , value , and probability must also be specified. See Opportunity in Object Field References for other field requirements. Note: If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error. |
create |
/api/opportunity /version/3/do/create /prospect_id /<prospect_id>?... |
user_key, api_key, prospect_id, name, value, probability |
Creates a new opportunity using the specified data. prospect_id must correspond to an existing prospect. name , value , and probability must also be specified. See Opportunity in Object Field References for other field requirements. Note: If both prospect_email and prospect_id are specified, both must correspond to the same prospect. Otherwise, the API will return an error. |
read |
/api/opportunity /version/3/do/read /id/<id>?... |
user_key, api_key, id |
Returns the data for the opportunity specified by id , including campaign assignment and associated visitor activities. id is the Pardot ID for the target opportunity. |
update |
/api/opportunity /version/3/do/update /id/<id>?... |
user_key, api_key, id |
Updates the provided data for the opportunity specified by id . id is the Pardot ID for the target opportunity. Fields that are not updated by the request remain unchanged. Returns an updated version of the opportunity. |
delete |
/api/opportunity /version/3/do/delete /id/<id>?... |
user_key, api_key, id |
Deletes the opportunity specified by id . id is the Pardot ID for the target opportunity. Returns no response on success. Note: Deleting an opportunity, whether via the API or within Pardot, will not delete the Visitor Activities or Score changes for the Prospect to whom the Opportunity is linked. |
undelete |
/api/opportunity /version/3/do/undelete /id/<id>?... |
user_key, api_key, id |
Undeletes the opportunity specified by id . id is the Pardot ID for the target opportunity. Returns no response on success. |
XML Response Formats
For output=full
:
<rsp stat="ok" version="1.0">
<opportunity>
...
<campaign>
...
</campaign>
<prospects>
<prospect>
...
</prospect>
</prospects>
<opportunity_activities>
<visitor_activity>
...
</visitor_activity>
</opportunity_activities>
</opportunity>
</rsp>
For output=simple
:
<rsp stat="ok" version="1.0">
<opportunity>
...
<campaign>
...
</campaign>
<prospects>
<prospect>
...
</prospect>
</prospects>
</opportunity>
</rsp>
For output=mobile
:
<rsp stat="ok" version="1.0">
<opportunity>
...
</opportunity>
</rsp>
Tag | Description |
---|---|
<opportunity> |
Parent tag. Contains data fields for target opportunity. Forcomplete field listing, see Opportunity in Object Field References. |
<campaign> |
Contains <id> and <name> of the campaign to which this opportunity has been assigned. |
<prospects> |
Contains all prospects associated with this opportunity. Contains only <prospect> tags. |
<opportunity_activities> |
Contains all visitor activities associated with this opportunity. Contains only <visitor_activity> tags. |
<visitor_activity> |
Contains data fields for a visitor activity. For complete field listing, see Visitor Activity in Object Field References. |
Updating Field Values
Modifying values of opportunity data fields is done by submitting an update
request with parameters for each field to be updated. Each parameter is formatted as <field_name>=<value>
.
Example: Updating the value of a opportunity (whose Pardot ID is 27):
POST: /api/opportunity/version/3/do/update/id/27 message body: value=50000
GET: /api/opportunity/version/3/do/update/id/27?value=50000
Only values that are specifically named in the request are updated. All others are left unchanged. To clear a value, submit an update
request containing a parameter with no specified value, such as status=
.