File Object

Upload images and other files to use in your Account Engagement emails, forms, and landing pages. Learn about files in Salesforce Help.

The API to access the Files object collection follows the conventions described in Version 5 Overview.

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

Note

Supported Operations

Operation	HTTP Verb	URL Format	Ability Requirements
Read	`GET`	`https://pi.pardot.com/api/v5/objects/files/<id>?<params>`	Marketing > Content > Files > View
Create	`POST`	`https://pi.pardot.com/api/v5/objects/files?<params>`	Marketing > Content > Files > Create
Update	`PATCH`	`https://pi.pardot.com/api/v5/objects/files/<id>?<params>`	Marketing > Content > Files > Create
Delete	`DELETE`	`https://pi.pardot.com/api/v5/objects/files/<id>`	Marketing > Content > Files > Delete
Query	`GET`	`https://pi.pardot.com/api/v5/objects/files?<params>`	Marketing > Content > Files > View
Add Tag	`POST`	`https://pi.pardot.com/api/v5/objects/files/<id>/do/addTag`	Marketing > Content > Files > Create AND Marketing > Segmentation > Tags > Create
Remove Tag	`POST`	`https://pi.pardot.com/api/v5/objects/files/<id>/do/removeTag`	Marketing > Content > Files > Create AND Marketing > Segmentation > Tags > Create
Copy to CMS	`POST`	`https://pi.pardot.com/api/v5/objects/files/<id>/do/copyToCms`	Marketing > Content > Files > Copy to CMS

Fields

Required Editable Fields

None.

Optional Editable Fields

Field	Type	Description
`name`	String	Name of the object for identification in Account Engagement. Uses the name of the file being uploaded if not specified on create.
`folderId`	Integer	ID of the folder containing this object. Uses the asset type’s uncategorized folder if not specified on create.
`campaignId`	Integer	ID of the Account Engagement campaign related to this object. If the value isn’t specified when the file is created, the value is `null`.
`vanityUrlPath`	String	Vanity URL path (excluding protocol and host). The URL must be unique for each tracker domain. For example `/my-link`. The value assumes empty (`/`) if not specified on create.
`trackerDomainId`	Integer	ID of the TrackerDomain to use in the URL for this object. Uses the primary tracker domain for the account if not specified on create.

Read-Only Fields

Field	Type	Description
`id`	Integer	ID of the object.
`salesforceId`	String	Salesforce Id of the object.
`url`	String	URL where the downloadable file can be accessed.
`size`	Integer	Size (in bytes) of the downloadable file.
`bitlyIsPersonalized`	Boolean	True if the object has a bitly URL that is personalized.
`bitlyShortUrl`	String	Bitly URL if present.
`vanityUrl`	String	Vanity URL if present.
`trackerDomain`	TrackerDomain object	JSON object representing the TrackerDomain to use in the URL for this object. See documentation for TrackerDomain for fields.
`isTracked`	Boolean	True if downloads of this file are recorded as visitor activity.
`createdAt`	DateTime	Creation time of the object.
`updatedAt`	DateTime	Last update time of the object.
`createdById`	Integer	ID of the user who created this object.
`updatedById`	Integer	ID of the user who last updated this object.
`createdBy`	User	User object representing the user who created this object. See documentation for User for fields.
`updatedBy`	User	User object representing the user who last updated this object. See documentation for User for fields.
`trackerDomain`	TrackerDomain	Tracker Domain object representing the tracker domain that was set on Create. See documentation for Tracker Domain for fields. A `null` value indicates that the object uses the default tracker domain for the account.
`campaign`	Campaign	Campaign object representing the campaign that was set on Create. See documentation for Campaign for fields.
`folder`	Folder	JSON object representing the folder for this object. See documentation for Folder for fields.
`salesforceCmsId`	List Email	The ID of the copied file when using `copyToCms`. If the file isn’t successfully copied, the value is `null`.

File Creation

A file creation POST request must be a multipart request as described in Version 5 Overview.

If the name field isn’t provided in the input body during creation, the filename of the uploaded file part is used for the name. A blank or null name can’t be explicitly included in the input for File creation.

Example request:

1POST /api/v5/objects/files?fields=id,name,url,createdBy.id,createdBy.username
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: multipart/form-data; boundary=----boundary-marker
5
6----boundary-marker
7Content-Disposition: form-data; name="file"; filename="conference_venues.pdf"
8
9<file-data>
10----boundary-marker
11Content-Disposition: form-data; name="input"
12
13{
14    "name": "Conference Venues",
15    "campaignId": 72836
16}
17----boundary-marker

Example response:

This example doesn’t show all the headers. Whitespace has been added to make it easier to read.

1HTTP/1.1 201 Created
2Content-Type: application/json
3Location: https://pi.pardot.com/api/v5/objects/files/8736?fields=id,name,url,createdBy.id,createdBy.username
4
5{
6    "id": 8736,
7    "name": "Conference Venues",
8    "url": "https://go.pardot.com/<generated-path-components>/conference_venues.pdf",
9    "createdBy": {
10        "id": 457,
11        "username": "jsmith@mycompany.com"
12    }
13}

The fields in the response body and Location header are the same as the fields specified on the example request.

File Update

A file update PATCH request can be a multipart request as described in Version 5 Overview. It can also be a simple request that has a JSON body with fields to update.

If you don’t specify name, the name of the File isn’t changed. This request is different from a File create POST request, which uses the filename of the uploaded file part as the default for name.

File Deletion

Deleting a file follows the conventions described in the Version 5 Overview. You can’t delete a file that’s referenced by certain Account Engagement objects. For example, if you try to delete a file that is referenced by a dynamic list, a 204 Method Not Allowed status is returned and the file isn’t deleted.

File Query

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

Sortable Fields

When you execute a query, you can optionally specify these fields in the orderBy parameter. See the conventions for query described in the Version 5 Overview.

id

Example request:

1GET /api/v5/objects/files?fields=id,name,url,createdBy.id,createdBy.username&orderBy=id
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 8736,
7            "name": "Conference Venues",
8            "url": "https://go.pardot.com/<generated-path-components>/conference_venues.pdf",
9            "createdBy": {
10                "id": 457,
11                "username": "jsmith@mycompany.com"
12            }
13        }
14    ]
15}

Filtering Results

When executing a query, the following parameters can be used to filter the returned results. These parameters can be specified in the request along with any shared parameters defined in Version 5 Overview. When specifying more than one parameter, all parameters must match the record in order for it to be returned in the results.

Parameter	Description
`id`	Returns any files where the ID is equal to the given integer value.
`idList`	Returns any files where the ID is included in the given list of values.
`idGreaterThan`	Returns any files where the ID is greater than the specified value, non-inclusive.
`idGreaterThanOrEqualTo`	Returns any files where the ID is greater than or equal to the specified value.
`idLessThan`	Returns any files where the ID is less than the specified value, non-inclusive.
`idLessThanOrEqualTo`	Returns any files where the ID is less than or equal to the specified value.

Example request:

1GET /api/v5/objects/files?fields=id,name&orderBy=id desc&idGreaterThan=150&idLessThan=200
2Host: pi.pardot.com
3Authorization: Bearer <access-token>

Example response:

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "values": [
5        {
6            "id": 168,
7            "name": "Spring Flyer PDF"
8        },
9        {
10            "id": 151,
11            "name": "Winter Flyer PDF"
12        }
13    ]
14}

Add Tag

Adds a Tag to the File object, which creates a TaggedObject.

Example Request

1POST https://pi.pardot.com/api/v5/objects/files/1000/do/addTag
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "id": 610,
5    "createdAt": "2024-09-23T18:26:49-04:00",
6    "createdById": 250,
7    "objectId": 1000,
8    "objectType": "file",
9    "tagId": 100
10}

Remove Tag

Remove a tag from a File object. When you remove a tag, the associated TaggedObject record is deleted.

Example Request

1POST `https://pi.pardot.com/api/v5/objects/files/1000/do/removeTag`
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "tagId": 100
8}

Example Response

Returns code 204 no content.

Copy to CMS

Copy a file to your Salesforce CMS Marketing workspace.

Example Request

1POST https://pi.pardot.com/api/v5/objects/files/1000/do/copyToCms
2Host: pi.pardot.com
3Authorization: Bearer <access-token>
4Content-Type: application/json
5
6{
7    "ids": [1, 2]
8}

Example Response

1HTTP/1.1 200 OK
2Content-Type: application/json
3{
4    "numRecordsQueued": 2
5}