Export API Overview

The Export API provides a way to retrieve large volumes of data from Account Engagement. It uses Account Engagement'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 Account Engagement. 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 Account Engagement API call limit and the concurrent Account Engagement 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.
• On procedures where no end date is supplied, for example, created_after is specified, but created_before isn’t, the export will retrieve all data up until the creation date of the export.

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.

• 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 Account Engagement 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.

See External Activity for more information.

Fields

Select the external activity fields you want to export.

Abilities

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 all data after the created_after date up until the creation date of the Export is returned. The created_after must be within a year of the creation date of the Export. The value can be today, yesterday, last_7_days, this_month, last_month, or a custom time specified in GNU Date Input Syntax format.

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 external activities that occurred before the specified time. This value must be after the value in activity_after. If this argument isn’t specified, then all data after the activity_after date up until the creation date of the Export is returned. The activity_after must be within a year of the creation date of the Export. The value can be today, yesterday, last_7_days, this_month, last_month, or a custom time specified in GNU Date Input Syntax format.

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

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”

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 all data after the created_after date up until the creation date of the Export is returned. The created_after must be within a year of the creation date of the Export. 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.

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 all data after the updated_after date up until the creation date of the Export is returned. The updated_after must be within a year of the creation date of the Export. 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.

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

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”

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 all data after the created_after date up until the creation date of the Export is returned. The created_after must be within a year of the creation date of the Export. 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.

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 all data after the updated_after date up until the creation date of the Export is returned. The updated_after must be within a year of the creation date of the Export. 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.

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

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”

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 isn’t specified, then all data after the created_after date up until the creation date of the Export is returned. The created_after must be within a year of the creation date of the Export. 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.

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 isn’t specified, then all data after the updated_after date up until the creation date of the Export is returned. The updated_after must be within a year of the creation date of the Export. 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.

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

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”

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 isn’t specified, then all data after the prospect_updated_after date up until the creation date of the Export is returned. The prospect_updated_after must be within a year of the creation date of the Export. 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.

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 isn’t specified, then all data after the updated_after date up until the creation date of the Export is returned. The updated_after must be within a year of the creation date of the Export. 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.

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

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”

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 isn’t specified, then all data after the prospect_updated_after date up until the creation date of the Export is returned. The prospect_updated_after must be within a year of the creation date of the Export. 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.

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 isn’t specified, then all data after the updated_after date up until the creation date of the Export is returned. The updated_after must be within a year of the creation date of the Export. 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.

Use these endpoints.

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

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.

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.

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

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.

Params

{id}: The ID of the export.

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.

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

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.

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.

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.

• 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.

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

• 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.

Params

{id}: The ID of the export.

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.

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

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 isn’t already completed or failed, it is canceled.

• "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.