Tag Object Resources

Use tag object resources to learn more about the Pardot objects that are tagged. Discover the type and ID of the tagged objects, the tag ID, and the time the tag was applied. Learn more about tags in Salesforce Help.

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

Resource Name	Operation	Description
Tag Object Query	`GET`	Request information for the tag objects that matches the specified criteria.
Tag Object Read	`GET`	Request information for a single tag object.

Tag Object Query

Request information for the tag objects that match the specified criteria. You can specify the tag objects and fields to request. A maximum of 200 records are returned. To return all tag objects, specify the output as mobile.

URI

/api/tagObject/version/3/do/query?...

Parameters to Select Tag Object Records

Use these parameters to specify the tag objects to return. Parameters can be used in any combination and in any order unless otherwise specified.

Notes:

Parameters must be URL-encoded.
Dates and times must use GNU Date Input Syntax (for example, yyyy-mm-dd:hh:ss:mm).
For a full listing of tag object fields see Object Field References.

Parameter	Type	Possible Values	Description
`created_after`	`string`	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`,`<custom_time>`	Request tag objects created after the specified time. Example: To request forms created in 2020, use `/api/tagObject/version/3/do/query?created_after=2019-12-31 24:59:59`.
`created_before`	`string`	`today`, `yesterday`, `last_7_days`, `this_month`, `last_month`, `<custom_time>`	Request tag objects created before the specified time. Doesn’t include tag objects created at the specified time. Example: To request tag objects created before today (but not created today), use `/api/tagObject/version/3/do/query?created_before=today`.
`id_greater_than`	`integer`	Any positive integer	Request tag objects that have an ID greater than the specified number.
`id_less_than`	`integer`	Any positive integer	Request tag objects that have an ID less than the specified number.
`tag_id`	`integer`	Any positive integer	Request tag objects with the specified tag id.
`type`	`Automation`, `Block`, `Campaign`, `Competitor`, `Prospect Custom Field`, `Custom URL`, `Drip Program`, `Email`, `Email Draft`, `Email Template`, `Email Template Draft`, `File`, `Form`, `Form Field`, `Form Handler`, `Group`, `Keyword`, `Landing Page`, `Layout Template`, `List`, `Opportunity`, `Paid Search Campaign`, `Personalization`, `Profile`, `Prospect`, `Prospect Default Field`, `Segmentation Rule`, `Site`, `Site Search`, `Social Message`, `User`, `Dynamic Content`	Any positive integer	Request tag objects with the specified type.
`object_id`	`integer`	Any positive integer	Request tag objects with the specified object id. Must be used together with the `type` parameter.

Parameters to Specify Which Results Are Returned

Use these parameters to specify the tag object fields to return, and how the tag objects are sorted.

Parameter	Type	Possible Values	Description
`limit`	`integer`	Any integer from 1 through 200.	The number of tag objects to return. Default value is 200.
`offset`	`integer`	Any positive integer	The number of tag objects to omit from the response (the number to "skip over"). Example: Retrieve a list of tag objects, omitting the 50 most recently updated records. Sort the query by the `id` field and use offset=50: `/api/tagObject/version/3/do/query?sort_by=id&offset=50`
`sort_by`	`string`	`created_at`, `updated_at`	The field by which the results are sorted. See Sort Order.
`sort_order`	`string`	`ascending, descending`	The sort order. The default value depends on which `sort_by` parameter you specify. See Sort Order.

Sort Order

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

Value	Default Sort Order	Description
`created_at`	descending	Sort the results by the tag objects' `created_at` timestamps.
`id`	ascending	Sort the results by the tag objects' `id` fields.

Tag Object Read

Request information for a single tag object.

URI

/api/tagObject/version/3/do/read/id/<ID>

Replace <ID> with the Pardot ID of the tag object.

Example

Request information about the tag object with ID 1234.

/api/tagObject/version/3/do/read/id/1234

XML Response

The XML response for a query request contains information for multiple tag objects. The XML response for a read request contains information for a single tag object.

XML Response for a Tag Object Query

<rsp stat="ok" version="1.0">
    <result>
        <total_results>...</total_results>
        <tagObject>...</tagObject>
        <tagObject>...</tagObject>
        <tagObject>...</tagObject>
    </result>
</rsp>

Tag	Description
`<result>`	Parent tag. Contains information about the tag objects that match the parameters specified in your query.
`<total_results>`	Contains the number of tag objects selected by the query. Note The query request returns a maximum of 200 tag objects. If your query matches more than 200 records, you can make several requests to retrieve all matching records.
`<tagObject>`	The information about a single tag object. See Tag Object in Object Field References for a complete description of fields.

XML Response for a Tag Object Read

<?xml version="1.0" encoding="UTF-8"?>
<rsp stat="ok" version="1.0">
    <tagObject>
        <id>1234</id>
        <tag_id>4567</tag_id>
        <type>Prospect</type>
        <object_id>1000</object_id>
        <created_at>2020-10-15 10:09:22</created_at>
    </tagObject>
</rsp>

Tag	Description
`<tagObject>`	The information about a single tag object. See Tag Object in Object Field References for a description of fields.