Última modificação: 22 de agosto de 2025
Use a API de exportações para exportar registros e dados de propriedades da sua conta da HubSpot, recuperar um URL para baixar um arquivo de exportação ou ver o status de uma exportação. No HubSpot, você também pode exportar registros ou ver um registro das exportações anteriores em sua conta.

​
Comece uma exportação

Para iniciar uma exportação, faça uma solicitação POST para/crm/v3/exports/export/async. O corpo da solicitação deve especificar informações como o formato do arquivo, o objeto e as propriedades que você deseja exportar e o tipo de exportação que está sendo concluído (por exemplo, exportar uma exibição de objeto ou uma lista). Você também pode filtrar os dados da propriedade a serem exportados com base em operadores específicos. Para as exportações de exibição e de lista, você pode incluir os seguintes campos em sua solicitação:
ParâmetroDescrição
exportTypeO tipo de exportação, VIEW (exporta uma exibição de uma página de índice de objeto) ou LIST (exporta uma lista).
formatO formato do arquivo. As opções incluem: XLSX, CSV ou XLS.
exportNameO nome da exportação.
languageO idioma do arquivo de exportação. As opções incluem: DE, EN, ES, FI, FR, IT, JA, NL, PL, PT ou SV. Saiba mais sobre os idiomas compatíveis.
objectTypeO nome ou o ID do objeto que você está exportando. Para objetos padrão, você pode usar o nome do objeto (por exemplo, CONTACT), mas para objetos personalizados, você deve usar o valor objectTypeId. Você pode recuperar esse valor fazendo uma solicitação GET para /crm/v3/schemas.
associatedObjectTypeOs nomes ou IDs de objetos associados a serem incluídos na exportação. Você pode exportar até quatro objetos associados por solicitação. Para objetos associados, a exportação conterá os IDs de registro associados a esse objeto. Se você exportar apenas um objeto associado ou definir o includePrimaryDisplayPropertyForAssociatedObjects campo para true, os valores das propriedades de exibição primária dos registros também serão exportados (por exemplo, name para empresas).
objectPropertiesUma lista das propriedades que você deseja incluir na exportação. Por padrão, os nomes e valores das propriedades são exibidos como rótulos legíveis por humanos, mas você pode solicitar nomes e valores internos usando o parâmetro exportInternalValuesOptions.
includePrimaryDisplayPropertyForAssociatedObjectsIncluir este campo com o valor true para exportar os valores de propriedade de exibição primária para todos os registros associados (por exemplo, name para empresas). Se você estiver exportando apenas um objeto associado (indicado pelo campo associatedObjectType), isso é definido como true por padrão. Se você estiver exportando mais de um objeto associado, o valor será definido como false por padrão.
includeLabeledAssociationsIncluir este campo com o valor true para exportar rótulos de associação para descrever o relacionamento entre registros associados.
exportInternalValuesOptionsInclua esta matriz para exportar os valores internos para nomes de propriedades e/ou valores de propriedades. Na matriz, inclua NAMES para exportar nomes internos de propriedades (mostrados como cabeçalhos de coluna) e/ou VALUES para exportar valores de propriedade interna (por exemplo, valores numéricos para estágios de pipeline personalizados ou registros de data e hora em vez de datas legíveis por humanos).
overrideAssociatedObjectsPerDefinitionPerRowLimitInclua este campo com o valor true para substituir as 1.000 associações padrão por limite de linha.

​
Exportar uma exibição

Se você estiver exportando uma exibição de página de índice, seu valor exportType deve ser VIEW, e você pode incluir o seguinte campo para filtrar e classificar os registros que está exportando:
ParâmetroDescrição
publicCrmSearchRequestIndica quais dados devem ser exportados com base em determinados valores de propriedade e consultas de pesquisa. Você pode incluir o seguinte no objeto:
filters: as propriedades e os valores de propriedade pelos quais filtrar os registros.
sorts: a ordem de classificação dos valores de uma propriedade, seja crescente, ASC, ou descendente, DES.
query: uma string para pesquisar os valores dos registros.
Por exemplo, para exportar uma visão de contatos e registros de empresas associadas, filtrados pela propriedade email e com os valores internos dos nomes e valores da propriedade, sua solicitação ficaria assim: 
///Example request body
{
"exportType": "VIEW",
"exportName": "All contacts",
"format": "xlsx",
"language": "DE",
"objectType": "CONTACT",
"exportInternalValuesOptions": ["NAMES", "VALUES"],
"objectProperties": ["email", "firstname", "lastname"],
"associatedObjectType": "COMPANY",
"publicCrmSearchRequest": {
"filters": [
{
"value": "hello@test.com",
"propertyName": "email",
"operator": "EQ"
}
],
"query": "hello",
"sorts": [
{
"propertyName": "email",
"order": "ASC"
}
]
}
}

​
Exportar uma lista

Se você estiver exportando uma lista, seu valor exportType deve ser LIST, mas você também precisa especificar a lista que está exportando com o seguinte campo:
ParâmetroDescrição
listIdO ID de lista ILS da lista para exportar. Você pode encontrar o valor de ID da lista ILS através dos detalhes da lista em HubSpot. Navegue para ** Contatos** > Listas, passe o mouse sobre a lista na tabela, depois clique em Detalhes. No painel direito, clique em Copiar ID da lista ao lado do valor de ID da lista ILS. As listas de contatos têm dois valores de IDs diferentes, mas você deve use o valor de ID da lista ILS em sua solicitação.
Por exemplo, para exportar uma lista com os e-mails dos contatos, sua solicitação pode ter a seguinte aparência: 
///Example request body
{
"exportType": "LIST",
"listId": 1234567,
"exportName": "Marketing email contacts",
"format": "xlsx",
"language": "EN",
"objectType": "CONTACT",
"objectProperties": ["email"]
}

​
Recuperar exportações

Quando você concluir uma exportação com êxito, o id da exportação será retornado na resposta. Para recuperar uma exportação da sua conta da HubSpot, faça uma solicitação GET para /crm/v3/exports/export/async/tasks/{exportId}/status. Ao recuperar as exportações, o status da exportação também será retornado. Os status possíveis incluem: COMPLETE, PENDING, PROCESSING ou CANCELED. Para as exportações com status COMPLETE, é retornado um URL que pode ser usado para fazer download do arquivo exportado. O URL de download expirará cinco minutos após a solicitação ser concluída. Depois de expirado, você pode executar outra solicitação GET para gerar um novo URL exclusivo.

​
Observação:

Antes da expiração, o URL de download de uma exportação pode ser acessado sem nenhuma autorização adicional. Para proteger seus dados, prossiga com cuidado ao compartilhar um URL ou ao integrar com o HubSpot por meio desta API.

​
Limites

Os limites a seguir se aplicam:
  • Você pode realizar até trinta exportações em um período de 24 horas e uma exportação por vez. As exportações adicionais serão enfileiradas até que a exportação anterior seja concluída.
  • Se você estiver concluindo uma exportação grande, poderá receber vários arquivos entregues em um arquivo zip. Isso ocorrerá para arquivos CSV ou XLSX com mais de 1.000.000 de linhas e arquivos XLS com mais de 65.535 linhas. Os arquivos CSV também são compactados automaticamente se o arquivo tiver mais de 2 MB, mesmo se o arquivo tiver menos de 1.000.000 linhas.
  • Por padrão, o número de associações por linha é limitado a 1.000 associações. Se quiser substituir esse limite, inclua o campo overrideAssociatedObjectsPerDefinitionPerRowLimit com o valor true.