Blog
Token
About Us
AiDOOS Wiki
Project Cost Estimation

Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Categories
All
CRM
Salesforce
ERP
SAP
Storage and Backups
Purestorage Netapp Nutanix
Cloud
AWS
Computing
IBM
Database
MongoDB MySQL PostgreSQL
DevOps
Docker Kubernetes Jenkins GitLab
Mobile
React Native Android
Web
React Angular PHP
Programming
Python
CRM-Salesforce
Salesforce Developers

Email Template Object

Use an email template to design a reusable email layout for your engagement programs, autoresponders, one-to-one emails, and list emails. Learn about email templates in Salesforce Help.

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

Resource Name Operation Description
Email Template Read GET Request information about a single email template.
One-to-One Email Templates GET Request information about the email templates that are used in one-to-one emails.

Request information about a single email template.

URI

Replace <ID> with the Pardot ID of the email template.

Parameters to Select a Template

Use this parameter to specify the email templates to return.

Parameter Type Possible Values Description
archived boolean true , false If true , the request returns archived and unarchived templates. If false , only unarchived templates are returned. Default value is false .

Request the email templates that are enabled for one-to-one emails.

URI

Parameters to Select One-to-One Email Templates

Use this parameter to specify which one-to-one email templates to return.

Parameter Type Possible Values Description
archived boolean true , false If true , the request returns both archived and unarchived templates. If false , only unarchived templates are returned. Default is false .

Use the XML response for read requests and one-to-one requests to learn more about your email templates.

XML Response for an Email Template Read

Tag Description
<emailTemplate> Parent tag. Contains data fields for a single email template.
<error> Flag if an error occurred.
<errorCode> Code for the error which occurred.
<errorMessage> Description of the error.
<sendOptions> The associated send options object, including sender-specific data.
<replyToAddress> The email address in the email's Reply-To header.
<sendFromData> A JSON array representing the sender hierarchy tied to the email template.
<id> The Pardot ID of the email template.
<name> The name of the email template.
<htmlMessage> The HTML version of the email template body.
<textMessage> The plain text version of the email template body.
<isDripEmail> Flag if the template is available for use in engagement programs.
<isListEmail> Flag if the template is available for use in list emails.
<subject> The subject of the email message.

XML Response for One-to-One Email Templates

Tag Description
<emailTemplates> Parent tag. Contains individual email template records.
<templates> Parent tag for each template.
<id> The Pardot ID of the email template.
<name> The name of the email template.
<isOneToOneEmail> Flag if the email template is available for use in one-to-one emails (always true).
<isArchived> Flag if the email template is in the Recycle Bin in Pardot.
<isAutoResponderEmail> Flag if the email template is available for use as an auto response from a form submission.
<isDripEmail> Flag if the email template is available for use in engagement programs.
<isListEmail> Flag if the email template is available for use in list emails.
<subject> The subject of the email message.
Salesforce Developers

Email Object

Use email resources to send emails to prospects, and to learn how prospects responded to the emails. Learn more about email in Salesforce Help.

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

Resource Name Operation Description
Email List Send POST Send an email to all prospects in the specified list.
Email One-to-One Send POST Send an email to a single prospect.
Email Read GET Request information for an email, such as the email name and subject.
Email Statistics GET Request statistics for a list email, such as the number of clicks, opens, and opt-outs.

Send an email to every prospect on the specified list.

URI

Creating the Email

You can satisfy the required fields to create a list email send request in the following ways:

  1. Specify list_ids[] , campaign_id , and email_template_id .
  2. Specify list_ids[] , campaign_id , text_content , name , subject , from_email , and from_name .
  3. Specify list_ids[] , campaign_id text_content , name , subject , and from_user_id .

Parameters

The following parameters can be used in a list email send request.

Parameter Type Description
campaign_id integer The Pardot ID of the campaign to which the email send is assigned.
from_name string The name of the user sending the email.
from_email string The email address of user sending the email.
from_user_id string The Pardot ID of the user sending the email.
from_assigned_user boolean If the prospect has an assigned user, send the email from that user.
from_account_owner boolean If the prospect has an account owner, send the email from that user.
replyto_email string The email address to use for the reply emails.
list_ids[] array The Pardot ID of the email lists. The email is sent to all users on the specified lists. You can post multiple list IDs for multiple lists.
suppression_list_ids[] integer The Pardot ID of the suppression list. The email isn’t sent to any user on the suppression lists. You can post multiple suppression list IDs for multiple lists.
tags[] string The name of the tags to create or associate with the email. You can post multiple tags.
operational_email boolean When true , the email is sent to the prospect regardless of opt-out status. Your account must have this feature enabled to use this setting.
name string The email record's name.
subject string The email's subject.
text_content string The email's text body. Must contain either %%unsubscribe%% or %%email_preference_center%% .
html_content string The email's html body. Must contain either %%unsubscribe%% or %%email_preference_center%% .
email_template_id integer The Pardot ID of the email template.
scheduled_time ISO8601 string The ISO8601 date and time to send the email.
format (xml or json) The format in which the response is sent. The default is xml .

Example

Schedule an email for October 31 at 5pm GMT-4. Use a template with ID 6789. Send the email to four prospect lists and specify two suppression lists. The email is sent from the assigned user (if one is assigned). Three tags are assigned to the email.

This example uses cURL.

XML Response for an Email List Send

Tag Description
<email> Parent tag. Contains information about the email. For more information about email fields, see Email.

Send an email to a single prospect. You can specify the prospect by Pardot ID or email address.

URIs

Replace <ID> with the Pardot ID of the email.

Replace <prospect_email> with the prospect's email address.

Creating the Email

You can satisfy the required fields to send an email in the following ways:

  1. Specify campaign_id and email_template_id .
  2. Specify campaign_id , text_content , name , subject , from_email and from_name .
  3. Specify campaign_id text_content , name , subject , and from_user_id .

Parameters

The following parameters can be used in a one-to-one email send request.

Parameter Type Description
campaign_id integer The ID of the Pardot campaign to associate the email with.
prospect_id integer The Pardot ID of the prospect you're sending the email to.
prospect_email string The email address of the prospect you're sending the email to.
from_name string The name of the user sending the email.
from_email string The email address of user sending the email.
from_user_id string The Pardot ID of the user sending the email.
replyto_email string The email address to use for the reply emails.
tags[] string The name of the tags to create or associate with the email. You can post multiple tags.
operational_email boolean When true , the email is sent to the prospect regardless of opt-out status. Your account must have this feature enabled to use this setting.
name string The email record's name.
subject string The email's subject.
text_content string The email's text body. Must contain either %%unsubscribe%% or %%email_preference_center%% .
html_content string The email's html body. Must contain either %%unsubscribe%% or %%email_preference_center%% .
email_template_id integer The Pardot ID of the email template.
format xml or json The format in which the response is sent. The default is xml .

Example

Send an email to the prospect with Pardot ID 1234.

XML Response for Email One-to-One Send

When an email send is successful, the response contains a copy of the email.

Tag Description
<email> Parent tag. Contains information about the email. For more information about email fields, see Email.

Request information for an email, such as the Pardot ID, Pardot name, and message body. For information about fields in an email record, see Email.

URI

Replace <ID> with the Pardot ID of the email.

Parameters

The request can include this parameter.

Parameter Type Description
include_message boolean If false , the response doesn’t include the html or text body of the email message. Default value is true .

Example

Request information for the email with ID 12345.

Request statistical information for a list email, such as the number of clicks, opens, and opt-outs.

URI

Replace <ID> with the Pardot ID of the email.

Example

Request statistics for the email with ID 12345.

XML Response for Email Statistics Request

Tag Description
<stats> The statistics for a single list email.
<sent> The number of emails sent.
<delivered> The number of emails delivered.
<total_clicks> The total number of clicks for the email.
<unique_clicks> The number of unique clicks for the email.
<soft_bounced> The number of soft bounces for the email.
<hard_bounced> The number of hard bounces for the email.
<opt_outs> The number of opt outs for the email
<spam_complaints> The number of spam complaints for the email.
<opens> The number of opens for the email.
<unique_opens> The number of unique opens for the email.
<delivery_rate> The delivery rate based on the number of emails sent.
<opens_rate> The open rate based on the number of emails delivered.
<click_through_rate> The click-through rate based on the number of emails delivered.
<unique_click_through_rate> The unique click-through rate based on the number of emails delivered.
<click_open_ratio> The ratio between email clicks and opens.
<opt_out_rate> The opt-out rate based on the number of emails delivered.
<spam_complaint_rate> The spam complaint rate based on the number of emails delivered.
Read article
Salesforce Developers

Export API Overview

The Export API provides a way to retrieve large volumes of data from Pardot. It uses Pardot's existing API structures, patterns, and terminology.

Use the Export API to retrieve large sets of data when you don't need synchronous completion responses or when query limitations are too restrictive.

An export is associated with a query and a data set in Pardot. When you create an export, the query is split into smaller queries, which return smaller sets of data. These smaller queries are processed in parallel, and the retrieved data is saved in CSV files. When the export is complete, the CSV files are available to download.

The order of the records returned in the CSV files isn’t guaranteed. The number of records in each CSV file varies, and all of the files associated with an export make up the full data set for the query.

The Export resource is used to create an export and get the status of an export. When the export is complete, the links to the CSV files containing the data are available in the resource.

  • The Export API is subject to the daily Pardot API call limit and the concurrent Pardot API call limit for your account.
  • Export API calls are executed sequentially for each account, with older exports being processed before newer exports.
  • The number of fields specified in the Export API calls can't exceed 150.

The data associated with an export expires after 7 days. When data expires, the Export resource removes links to the CSV files and shows that the export has expired. Attempts to retrieve the data after an export expires fail.

To prevent errors with automations, files generated by the export API don't include a BOM (Byte Order Mark) in the beginning of the file. Exports created from the Pardot UI produce files with a BOM header.

  • The first row contains the name of the field.
  • The second row and beyond contain the record data.
  • Dates are returned in the user’s timezone at the time they created the export.
    • For example, if a user is in “PST” timezone and creates an export, the dates in the export are in “PST”. If a second user is in “EST” timezone and downloads the exported files, the dates in the export are in “PST”.
    • If a user’s timezone changes, previous exports created by the user have dates formatted in the previous timezone. Dates in new exports use the new timezone.
  • Dates are returned in the standard Pardot API date format of YYYY-MM-DD HH:mm:SS .
  • Fields with null values are represented as an empty value in CSV.

A procedure is a query and execution plan used to retrieve the data. Each object has a different set of procedures.

External Activity

See External Activity for more information.

Fields

Select the external activity fields you want to export.

Field Type Nullable Description
id Integer No The External Activity ID.
extension String No The extension for the type. This value must be less than or equal to 255 characters.
extensionSalesforceId String No The extension's Salesforce ID.
type String No The type of external activity that this record corresponds to. This must be a value from one of the registered types in the account. This value must be less than or equal to 255 characters.
typeSalesforceId String No The type's Salesforce ID.
prospectId Integer No The prospect ID the activity was linked to based on the email.
value String Yes Any string value associated to this event. This value is not checked and can be any value. The value must be less than or equal to 100 characters.
value String Yes Any string value associated to this event. This value is not checked and can be any value. The value must be less than or equal to 100 characters.
activityDate DateTime No The date the external activity happened. This value can be used by the user to back date or forward date the activity. If not specified, then the current date is used. This must be in "YYYY-MM-DD" format.
createdAt DateTime No The time the record was created in Pardot. This field is the standard system field and the value is equal to the time the record is created in the data store.
createdById Integer Yes The ID of the user that sent the request to Pardot (the authenticated user of the request).

Abilities

Action Requirements
Create export Prospect > External Activity > View ability
View export Prospect > External Activity > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

filter_by_created_at

Retrieves all external activity records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

  • created_after Required. Selects external activities that were created after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • created_before : Optional. Selects external activities that were created before the specified time. This value must be after the value in created_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.

The range between created_after and created_before cannot exceed 1 year. When prospect_updated_before is not specified, the current date is used to gauge the interval.

filter_by_activity_date

Retrieves all visitor activity records with an activityDate value that is greater than the activity_after argument and less than the activity_before argument.

Arguments

  • activity_after : Required. Selects external activities that occurred after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • activity_before : Optional. Selects visitor activities that occurred before the specified time. This value must be after the value in updated_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.

The range between activity_after and activity_before can’t exceed 1 year. When updated_before isn’t specified, the current date is used to gauge the interval.

Visitor Activity

Fields

Select the visitor activity fields you want to export. See the visitor activity fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability

To view an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability AND
  • The user must be the same as the user that created the export

OR

  • “Admin > Exports > View”

filter_by_created_at

Retrieves all visitor activity records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

  • created_after : Selects visitor activities that were created after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • created_before : (Optional) Selects visitor activities that were created before the specified time. This value must be after the value in created_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • type : (Optional) Selects visitor activities of the specified types. If this argument isn’t specified, then all of the visitor activities belonging to any type is returned. See a list of available Visitor Activity Types in Visitor Activity in Object Field References. Type Session is omitted.
  • prospect_only : (Optional) Selects only those visitor activities associated with a prospect. When this field is set to false , all visitor activities with and without a prospect are returned. The values can be true or false .

filter_by_updated_at

Retrieves all visitor activity records with an updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

  • updated_after : Selects visitor activities that were updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • updated_before : (Optional) Selects visitor activities that were updated before the specified time. This value must be after the value in updated_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • type : (Optional) Selects visitor activities of the specified types. If this argument isn’t specified, then all visitor activities belonging to any type are returned. See a list of available Visitor Activity Types in Visitor Activity in Object Field References. Type Session is omitted.
  • prospectOnly : (Optional) Selects only those visitor activities associated with a prospect. When this field is set to false , all visitor activities with and without a prospect are returned. The values can be true or false .

The range between created_ater and created_before or between updated_after and updated_before can’t exceed 1 year. When updated_before isn’t specified, the current date is used to gauge the interval.

List Membership

Fields

Select the fields that you want to export. See the fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability
View export Marketing > Segmentation > Lists > View ability and Prospects > Visitors > View ability and ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

  • “Marketing > Segmentation > Lists > View“ ability AND
  • “Prospects > Visitors > View“ ability

To view an export with this procedure, the user must have the following:

  • “Marketing > Segmentation > Lists > View“ ability AND
  • “Prospects > Visitors > View“ ability AND
  • The user must be the same as the user that created the export

OR

  • “Admin > Exports > View”

filter_by_created_at

Retrieves all list membership records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

  • created_after : Selects list membership that were created after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • created_before : (Optional) Selects list membership that were created before the specified time. This value must be after the value in created_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • deleted : (Optional) Selects list membership based on whether it’s deleted or not. The value can be true , false , or all .

filter_by_updated_at

Retrieves all list membership records with a updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

  • updated_after : Selects list membership that were created after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • updated_before : (Optional) Selects list membership that were created before the specified time. This value must be after the value in updated_after . If this argument isn’t specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • deleted : (Optional) Selects list membership based on whether it’s deleted or not. The value can be true , false , or all .

The range between created_after and created_before or between updated_after and updated_before can’t exceed 1 year. When created_before isn’t specified, the current date is used to gauge the interval.

Prospect

Fields

Select the prospect fields that you want to export. See the prospect fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability

To view an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability AND
  • The user must be the same as the user that created the export

OR

  • “Admin > Exports > View”

filter_by_updated_at

Retrieves all prospect records with a updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

  • updated_after : Selects prospects that were updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • updated_before : (Optional) Selects prospects that were updated before the specified time. This value must be after the value in updated_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.

filter_by_created_at

Retrieves all prospect records with a created_at value that is greater than the created_after argument and less than the created_before argument.

Arguments

  • created_after : Selects prospects that were created after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • created_before : (Optional) Selects prospects that were created before the specified time. This value must be after the value in created_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the created_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • deleted : (Optional) Selects prospects based on whether they're deleted or not. The value can be true , false , or all .

The range between created_after and created_before or between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.

Prospect Account

Fields

Select the prospect account fields you want to export. See the prospect account fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Prospects > Prospect Accounts > View ability
View export Prospects > Prospect Accounts > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

  • “Prospects > Prospect Accounts > View“ ability

To view an export with this procedure, the user must have the following:

  • “Prospects > Prospect Accounts > View“ ability AND
  • The user must be the same as the user that created the export

OR

  • “Admin > Exports > View”

filter_by_prospect_updated_at

Retrieves all prospect account records associated with a prospect that has an updated_at value that is greater than the prospect_updated_after argument and less than the prospect_updated_before argument.

Arguments

  • prospect_updated_after : Selects prospect accounts associated with a prospect that has been updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • prospect_updated_before : (Optional) Selects prospect accounts associated with a prospect that has been updated before the specified time. This value must be after the value in prospect_updated_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the prospect_updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • prospect_deleted : (Optional) Selects prospect account based on whether it is associated with a prospect that has been deleted. The value can be true , false , or all . Default value is false .

The range between prospect_updated_after and prospect_updated_before cannot exceed 1 year. When prospect_updated_before is not specified, the current date is used to gauge the interval.

filter_by_updated_at

Retrieves all prospect account records with an updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

  • updated_after : Selects prospect accounts that have been updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • updated_before : (Optional) Selects prospect accounts that have been updated before the specified time. This value must be after the value in updated_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • deleted : (Optional) Selects prospect accounts based on whether they have been deleted. The value can be true , false , or all . Default value is false .

The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.

Visitor

Fields

Select the visitor fields you want to export. See the visitor fields that are available. The value for fields must be an array of strings of the available fields.

Abilities

Action Requirements
Create export Prospects > Visitors > View ability
View export Prospects > Visitors > View ability and be the same user that created the export
View all exports Admin > Exports > View ability
Query exports Admin > Exports > View ability

To create an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability

To view an export with this procedure, the user must have the following:

  • “Prospects > Visitors > View“ ability AND
  • The user must be the same as the user that created the export

OR

  • “Admin > Exports > View”

filter_by_prospect_updated_at

Retrieves all visitor records associated with a prospect that has an updated_at value that is greater than the prospect_updated_after argument and less than the prospect_updated_before argument.

Arguments

  • prospect_updated_after : Selects visitors associated with a prospect that has been updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • prospect_updated_before : (Optional) Selects visitors associated with a prospect that has been updated before the specified time. This value must be after the value in prospect_updated_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the prospect_updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • prospect_deleted : (Optional) Selects visitor based on whether it is associated with a prospect that has been deleted. The value can be true , false , or all . Default value is false .

The range between prospect_updated_after and prospect_updated_before cannot exceed 1 year. When prospect_updated_before is not specified, the current date is used to gauge the interval.

filter_by_updated_at

Retrieves all visitor records with an updated_at value that is greater than the updated_after argument and less than the updated_before argument.

Arguments

  • updated_after : Selects visitors that have been updated after the specified time. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • updated_before : (Optional) Selects visitors that have been updated before the specified time. This value must be after the value in updated_after . If this argument is not specified, then no upper boundary is used in the query, and all data after the updated_after is returned. The value can be today , yesterday , last_7_days , this_month , last_month , or a custom time specified in GNU Date Input Syntax format.
  • deleted : (Optional) Selects visitors based on whether they have been deleted. The value can be true , false , or all . Default value is false .

The range between updated_after and updated_before cannot exceed 1 year. When updated_before is not specified, the current date is used to gauge the interval.

Use these endpoints.

Used to initiate the export of an object through a defined procedure.

POST

Request Body

Content-Type must be application/json .

Input Representation

  • object : Specifies which object to export.
  • fields : Specifies the fields that will be exported. If no fields value is given, all available fields are exported.
  • procedure : The procedure to execute. A procedure is a query and execution plan used to retrieve data. Each object has a different set of procedures. See the Procedures section for available procedures.
    • name : The name of the procedure.
    • arguments : Arguments used to manipulate the behavior of the procedure. These arguments are specific to the procedure. See the documentation for the procedure to see which arguments apply. If duplicate argument names are provided the latter value is used.

Success

Status Code: 200

Output Representation

  • id : The ID of the export. ID is used to check the status of the export.
  • state : The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export has completed. See Export State.
  • isExpired : Indicates that the export has expired. When an export has expired, this returns true and no data related to the export can be downloaded.
  • resultRefs : (Optional) This property appears when an export is complete, and it contains a list of URLS to CSV files available for download. If there’s no data associated with the export, this property is absent. If there’s only a single CSV file available for download, this property is a string containing the URL to download the file. If there are multiple CSV files, resultRefs is an array of URLs.
  • createdAt : The date and time the export was created in the timezone of the user making the request.
  • updatedAt : The date and time the export was updated in the timezone of the user making the request.

Errors

  • Status Code: 4xx
  • Error codes: See Error Codes

Example

Here’s a request to execute the visitor activity procedure named filter_by_created_at , which retrieves all visitor activity data where the created_at value is between two dates. In this example, the data is retrieved from December 25, 2019 to December 25, 2020.

After sending the request as a POST , the response is as follows. From this response we know the export is queued for execution but hasn't started or completed. We suggest waiting a few minutes before checking the Read endpoint for the new status.

Used to retrieve the status of the export. When an export is complete, the links to download the results are available in the result body.

GET

Params

{id} : The ID of the export.

Success

Status Code: 200

Output Representation

  • id : The ID of the export. This ID is used to check the status of the export.
  • state : The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export is completed. See Export State.
  • isExpired : Indicates that the export has expired. After an export has expired, this property returns true and no data associated with the export can be downloaded.
  • resultRefs : (Optional) This property appears only when the export has completed and contains a list of URLS to CSV files available for download. If there’s no data associated with the export, this property is absent. If there’s only a single CSV file available for download, resultRefs is a string containing the URL to download the file. If there are multiple CSV files, resultRefs is an array of URLs. The order of the URLs in the array isn’t significant.
  • createdAt : The date and time the export was created in the timezone of the user making the request.
  • updatedAt : The date and time the export was updated in the timezone of the user making the request.

Errors

  • Status Code: 4xx
  • Error codes: See Error Codes

Example

After calling the Create endpoint, the ID of the export is given in the response. This ID is used in the URL to call the Read endpoint.

If the export is waiting to be processed, state is "Waiting", as in the following example.

If the export is finished, state is "Complete" and resultRefs contains URLs to download the CSV files.

Used by administrators to retrieve a list of exports and their status. A user must have the “Admin > Exports > View” ability to execute this endpoint.

GET

Params

  • created_after : (Optional) Filters the results to return only exports that were created after the specified time.
  • created_before : (Optional) Filters the results to return only exports that were created before the specified time.
  • updated_after : (Optional) Filters the results to return only exports that were updated after the specified time.
  • updated_before : (Optional) Filters the results to return only exports that were updated before the specified time.
  • status : (Optional) Filters the results to return exports in the given state. Allowed values are "Complete", "Failed", "Processing", or "Waiting".
  • object : (Optional) Filters the results to return exports for the specified object.
  • sort_by : (Optional) Sorts the results by the specified property value. Allowed values are "id", "created_at", or "updated_at". If not specified, the results are returned by "id" in "descending" order.
  • sort_order : (Optional) Used with sort_by . Adjusts the direction of the sort using the values "ascending" or "descending". If not specified, the results are in "descending" order.

Success

Status Code: 200

Output Representation

  • result : A collection of exports
    • total_results : The total number of results matching the filter.
    • export : A collection of exports. If there are no results, this property is omitted. If there's a single result, it's an object. If there are multiple results, it's an array of results.
      • id : The ID of the export. This ID is used to check the status of the export.
      • state : The state of the export. Displays "Waiting" when the export has been queued for processing, "Processing" when the server is working on the export and "Complete" when the export has completed. See Export State.
      • isExpired : Indicates that the export has expired. After an export has expired, this property returns true and no data associated with the export can be downloaded.
      • createdAt : The date and time the export was created in the timezone of the user making the request.
      • updatedAt : The date and time the export was updated in the timezone of the user making the request.

The export representation returned in query doesn’t contain resultRefs . Use the read endpoint for the export to get the full export representation.

Errors

  • Status Code: 4xx
  • Error codes: See Error Codes

The URLs retrieved from the Read endpoint can be used to download the results of the export. A failure occurs when attempting to download any results from an expired export. See Expiration for more information.

GET

Success

The data represented in CSV format. See the CSV Format section for more information.

Errors

  • Status code: 4xx
  • Error codes: See Error Codes

Used to cancel the export. If the export is already completed or failed, it can't be canceled.

POST

Params

{id} : The ID of the export.

Success

Status Code: 200

Output Representation

  • id : The ID of the export. This ID is used to check the status of the export.
  • state : The state of the export. See Export State.
  • isExpired : Indicates that the export has expired. After an export has expired, this property returns true and no data associated with the export can be downloaded.
  • createdAt : The date and time the export was created in the timezone of the user making the request.
  • updatedAt : The date and time the export was updated in the timezone of the user making the request.

Errors

  • Status Code: 4xx
  • Error codes: See Error Codes & Messages

Example

After calling the Create endpoint, the ID of the export is given in the response. This ID is used in the URL to call the Cancel endpoint.

If the export is not already completed or failed, it is canceled.

Export State

  • "Waiting": The export is waiting to be processed.
  • "Processing": A server has started processing the export.
  • "Complete": The export is complete and the results are available for download.
  • "Failed": A fatal error has occurred and the data can’t be retrieved. Try executing the export again. If the error occurs again, contact support.
  • "Canceled": The export is canceled and can't be restarted.
Read article