Please note: this API is currently in beta and is subject to change based on testing and feedback. By using these endpoints you agree to adhere to our Developer Terms& Developer Beta Terms. You also acknowledge and understand the risk associated with testing an unstable API.

Exports

OverviewEndpoints

Use the exports API to export records and property data from your HubSpot account, retrieve a URL to download an export file, or see the status of an export. Within HubSpot, you can also export records or view a log of past exports in your account.

Start an export

To start an export, make a POST request to /crm/v3/exports/export/async. Your request body should specify information such as the file format, the object and properties you want to export, and the type of export you're completing (e.g., exporting an object view or a list). You can also filter the property data to be exported based on specific operators.

For both view and list exports, you can include the following fields in your request:

Use this table to describe parameters / fields
ParameterDescription
exportType

The type of export, either VIEW (exports a view from an object index page) or LIST (exports a list).

format

The file format. Options include XLSX, CSV, or XLS.

exportName

The name of the export.

language

The language of the export file. Options include DE, EN, ES, FI, FR, IT, JA, NL, PL, PT, or SV. Learn more about supported languages.

objectType

The name or ID of the object you're exporting. For standard objects, you can use the object's name (e.g., CONTACT), but for custom objects, you must use the objectTypeId value. You can retrieve this value by making a GET request to /crm/v3/schemas.

associatedObjectType

The names or IDs of associated objects to include in the export. If you include associated objects, the export will contain the associated record IDs of that object and the records' primary display property value (e.g., name).

objectProperties

A list of the properties you want included in your export.

Export a view

If you're exporting an index page view, your exportType value should be VIEW, and you can include the following field to filter and sort the records you're exporting:

Use this table to describe parameters / fields
ParameterDescription
publicCrmSearchRequest

Indicates which data should be exported based on certain property values and search queries. You can include the following within the object:

filters: the properties and property values to filter records by.
sorts: the sort order of a property's values, either ascending, ASC, or descending, DES.
query: a string to search the records' values for.

For example, to export a view of contacts and associated company records, filtered by the email property, your request may look like the following:

///Example request body { "exportType": "VIEW", "exportName": "All contacts", "format": "xlsx", "language": "DE", "objectType": "CONTACT", "objectProperties": [ "email, firstname, lastname" ], "associatedObjectType": "COMPANY", "publicCrmSearchRequest": { "filters": [ { "value": "hello@test.com", "propertyName": "email", "operator": "EQ" } ], "query": "hello", "sorts": [ { "propertyName": "email", "order": "ASC" } ] } }

Export a list

If you're exporting a list, your exportType value should be LIST, but you also need to specify the list you're exporting with the following field:

Use this table to describe parameters / fields
ParameterDescription
listId

The ID of the list to export. You can find the list ID via the list details in HubSpot  or for contact lists, by making a GET request to /contacts/v1/lists.

For example, to export a list with the contacts' emails, your request may look like the following:

///Example request body { "exportType": "LIST", "listId": 34, "exportName": "Marketing email contacts", "format": "xlsx", "language": "EN", "objectType": "CONTACT", "objectProperties": [ "email" ] }

Retrieve exports

When you successfully complete an export, the export's id will be returned in the response. To retrieve an export from your HubSpot account, make a GET request to /crm/v3/exports/export/async/tasks/{exportId}/status.

When retrieving exports, the status of the export will also be returned. Possible statuses include COMPLETED, PENDING, PROCESSING, or CANCELED. For exports with a COMPLETED status, a URL is returned that you can use to download the exported file. The download URL will expire five minutes after the completed request. Once expired, you can perform another GET request to generate a new unique URL.

Please note: prior to expiration, an export's download URL can be accessed without any additional authorization. To protect your data, proceed with caution when sharing a URL or integrating with HubSpot via this API.

Limits

The following limits apply to the export endpoints:

  • When setting filters for your export, you can include a maximum of three filterGroups with up to three filters in each group.
  • There will be a limit to the number of exports you can complete within 24 hours, and the number of exports you can complete simultaneously. These limits will be determined during the API's beta period.
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.