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