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.
| 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 |
None.
| 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. |
| 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. |
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:
Example response:
This example doesn't show all the headers. Whitespace has been added to make it easier to read.
The fields in the response body and Location header are the same as the fields specified on the example request.
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.
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.
Retrieving a collection of files follows the conventions described in Version 5 Overview.
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:
Example response:
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:
Example response:
Adds a Tag to the File object, which creates a TaggedObject.
Example Request
Example Response
Remove a tag from a File object. When you remove a tag, the associated TaggedObject record is deleted.
Example Request
Example Response
Returns code 204 no content.
Copy a file to your Salesforce CMS Marketing workspace.
Example Request
Example Response