Tag Object

Use the Tag resource to learn more about your Account Engagement tags. You can tag Account Engagement assets with keywords or key phrases. Use tags to sort, organize, report on, and search for assets. For more use cases, see Using Tags in Account Engagement.

The API to access the Tag follows the conventions described in Version 5 Overview.

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Create	`POST`	`https://pi.pardot.com/api/v5/objects/tags?<params>`	Marketing > Segmentation > Tags > Create
Read	`GET`	`https://pi.pardot.com/api/v5/objects/tags/<id>?<params>`	Marketing > Segmentation > Tags > View
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/tags/<id>`	Marketing > Segmentation > Tags > Create
Query	`GET`	`https://pi.pardot.com/api/v5/objects/tags?<params>`	Marketing > Segmentation > Tags > View
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/tags/<id>`	Marketing > Segmentation > Tags > Delete
Merge Tags	`POST`	`https://pi.pardot.com/api/v5/objects/tags/<id>/do/mergeTags`	Marketing > Segmentation > Tags > Create

Fields

Required Editable Fields

Field	Type	Description
`name`	String	The name of the tag.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of the tag.
`objectCount`	Integer	Number of objects tagged with the tag.
`createdById`	Integer	ID of the user who created this tag.
`updatedById`	Integer	ID of the user who last updated this tag.
`createdAt`	DateTime	Creation time of the tag.
`updatedAt`	DateTime	Last update time of the tag.
`createdBy`	User	User object representing the user who created this tag.
`updatedBy`	User	User object representing the user who last updated this tag.

Create

Create a tag with a specified name.

Example Request:

GET /api/v5/objects/tags?fields=id,objectCount,createdById
Host: pi.pardot.com
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

{
    "name": "Marketing Asset"
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 2000,
    "objectCount": 0,
    "createdById": 523
}

Read

Retrieve a single tag following the conventions described in the Version 5 Overview.

Example Request:

GET /api/v5/objects/tags/1005?fields=id,name,objectCount,createdById
Host: pi.pardot.com
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 1005,
    "name": "Deleteable Asset",
    "objectCount": 450,
    "createdById": 523
}

Update

Example Request:

GET /api/v5/objects/tags/:2000?fields=id,name,objectCount,createdById
Host: pi.pardot.com
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

{
    "name": "Marketing Image"
}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 2000,
    "name": "Marketing Image",
    "objectCount": 0,
    "createdById": 523
}

Delete

Deletes a tag following the conventions described in the Version 5 Overview.

Example Request

DELETE /api/v5/objects/tags/2340
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

Example Response

Returns code 204 no content.

Query

Retrieving a collection of tags follows the conventions described in Version 5 Overview.

Example Request:

GET /api/v5/objects/tags?fields=id,name,objectCount,createdById
Host: pi.pardot.com
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
"values": [
    {
        "id": 1005,
        "name": "Deleteable Asset",
        "objectCount": 450,
        "createdById": 523
    },
    {
        "id": 2000,
        "name": "Marketing Image",
        "objectCount": 58,
        "createdById": 523
    }
]

Sortable Fields

When you execute a query, you can include the orderBy parameter. This table lists possible values for the orderBy parameter. See the conventions for query described in the Version 5 Overview.

Parameter	Description
`id`	The ID of the tag.
`createdAt`	The date and time when the tag was created. The time zone for this property is based on the time zone of the API user.
`updatedAt`	The date and time when the tag was last modified. The time zone for this property is based on the time zone of the API user.

Filtering Results

When you execute a query, you can use the parameters in this table to filter the results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. If you specify more than one parameter, the response includes only the records that match all of the parameters.

Parameter	Description
`id`	Returns any tags where ID is equal to the given integer value.
`idList`	Returns any tags where ID is included in the given list of values.
`idGreaterThan`	Returns any tags where ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any tags where ID is greater than or equal to the specified value.
`idLessThan`	Returns any tags where ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any tags where ID is less than or equal to the specified value.
`name`	Returns any tags where Name is equal to the given string value.
`createdAt`	Returns any tags where CreatedAt is equal to the given datetime value.
`createdAtAfter`	Returns any tags where CreatedAt is after the given datetime value, non-inclusive.
`createdAtAfterOrEqualTo`	Returns any tags where CreatedAt is after or equal to the given datetime value.
`createdAtBefore`	Returns any tags where CreatedAt is before the given datetime value, non-inclusive.
`createdAtBeforeOrEqualTo`	Returns any tags where CreatedAt is before or equal to the given datetime value.
`updatedAt`	Returns any tags where UpdatedAt is equal to the given datetime value.
`updatedAtAfter`	Returns any tags where UpdatedAt is after the given datetime value, non-inclusive.
`updatedAtAfterOrEqualTo`	Returns any tags where UpdatedAt is after or equal to the given datetime value.
`updatedAtBefore`	Returns any tags where UpdatedAt is before the given datetime value, non-inclusive.
`updatedAtBeforeOrEqualTo`	Returns any tags where UpdatedAt is before or equal to the given datetime value.

Example request:

GET /api/v5/objects/tags?fields=id,name,objectCount&orderBy=id desc&idGreaterThan=100&idLessThan=5000
Host: pi.pardot.com
Authorization: Bearer <access-token>

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
"values": [
    {
        "id": 2000,
        "name": "Marketing Image",
        "objectCount": 58
    }
    {
        "id": 1005,
        "name": "Deleteable Asset",
        "objectCount": 450
    }
]

Merge Tags

Merge several tags into one tag. The tags that you specify are deleted and are considered to be part of the tag listed in the path of the POST request.

Example Request

POST /api/v5/objects/tags/:1005/do/mergeTags
Host: pi.pardot.com
Pardot-Business-Unit-Id: <business-unit-id>
Authorization: Bearer <access-token>

{
    "tagIds": [100,200,300,400]
}

Example Response

{
  "id": 1005,
  "name": "Deleteable Asset",
  "objectCount": 450
}

Tag Object

Supported Operations

Fields

Required Editable Fields

Read-Only Fields

Create

Read

Update

Delete

Query

Sortable Fields

Filtering Results

Merge Tags

No Results