Importações

Use a API de importações para importar registros e atividades do CRM para sua conta da HubSpot, como contatos, empresas e observações. Depois da importação, você pode acessar e atualizar os registros e atividades por meio dos vários endpoints da API do CRM, incluindo as APIs de contato, APIs de associações e APIs de envolvimento. Você também pode importar registros e atividades usando a ferramenta de importação guiada no HubSpot.

Antes de iniciar a importação, saiba mais sobre os objetos e atividades que podem ser importados, bem como os requisitos de arquivo e propriedade.

Iniciar uma importação

Você pode iniciar uma importação fazendo uma solicitação POST para /crm/v3/imports com um corpo de solicitação que especifique como mapear as colunas do arquivo de importação para as propriedades do CRM associadas no HubSpot.

As importações de API são enviadas como solicitações de tipo de dados de formulário, com o corpo de solicitação contendo os seguintes campos:

  • importRequest: um campo de texto que contém o JSON da solicitação.
  • arquivos: um campo de arquivo que contém o arquivo de importação.

Para o cabeçalho da solicitação, adicione um cabeçalho de Content-Type com um valor de multipart/form-data.

A captura de tela a seguir mostra como a solicitação pode parecer ao usar um aplicativo como o Postman:

postman-import-request-no-response0

Formatar os dados de importRequest

No JSON da solicitação defina os detalhes do arquivo de importação, incluindo o mapeamento das colunas da planilha para os dados do HubSpot. O JSON da sua solicitação deve incluir os seguintes campos:

  • nome: o nome da importação. No HubSpot, esse é o nome exibido na ferramenta de importação, bem como o nome que você pode usar em outras ferramentas, como listas.
  • importOperations: um campo opcional usado para indicar se a importação deve apenas criar e atualizar, apenas criar ou apenas atualizar registros para um determinado objeto ou atividade. Inclua o objectTypeId do objeto/atividade e se deseja apenas UPSERT (criar e atualizar), CREATE ou UPDATE os registros. Por exemplo, o campo ficaria assim na solicitação: "importOperations": {"0-1": "CREATE"}. Se você não incluir este campo, o valor padrão usado para a importação será UPSERT.
  • dateFormat: o formato para datas incluídas no arquivo. Por padrão, isso é definido para MONTH_DAY_YEAR, mas você também pode usar DAY_MONTH_YEAR ou YEAR_MONTH_DAY.
  • marketableContactImport: o status de marketing dos contatos no arquivo de importação. Isso é usado apenas ao importar contatos para contas com acesso aos contatos de marketing. Para definir os contatos no arquivo como autorizados para marketing, use o valor true. Para definir os contatos no arquivo como não autorizados para marketing, use o valor false
  • createContactListFromImport: um campo opcional para criar uma lista estática dos contatos da sua importação. Para criar uma lista a partir do seu arquivo, use o valor true.
  • arquivos: uma matriz que contém as informações do arquivo de importação.
    • fileName: o nome do arquivo de importação.
    • fileFormat: o formato do arquivo de importação. Para arquivos CSV, use o valor CSV. Para planilhas do Excel, use o valor SPREADSHEET.
    • fileImportPage: contém a matriz columnMappings necessária para mapear os dados do seu arquivo de importação para os dados do HubSpot. Saiba mais sobre o mapeamento de colunas abaixo.

Mapear colunas de arquivo para propriedades do HubSpot

Na matriz columnMappings, inclua uma entrada para cada coluna no arquivo de importação, que corresponda à ordem da planilha. Para cada coluna, inclua os seguintes campos:

  • columnObjectTypeId: o nome ou valor objectTypeId do objeto ou atividade ao qual os dados pertencem. Consulte este artigo para obter uma lista completa de valores objectTypeId.
  • columnName: o nome do cabeçalho da coluna.
  • propertyName: o nome interno da propriedade do HubSpot para a qual os dados serão mapeados. Para a coluna comum em importações de vários arquivos, o propertyName deve ser null quando o campo toColumnObjectTypeId é usado.
  • columnType: usado para especificar que uma coluna contém uma propriedade de identificador exclusivo. Dependendo da propriedade e da meta da importação, use um dos seguintes valores:
    • HUBSPOT_OBJECT_ID: o ID de um registro. Por exemplo, o arquivo de importação de contatos pode conter uma coluna de ID do registro, que armazena o ID da empresa à qual você deseja associar os contatos. 
    • HUBSPOT_ALTERNATE_ID: um identificador exclusivo que não seja o ID do registro. Por exemplo, o arquivo de importação de contatos pode conter uma coluna de E-mail, que armazena os endereços de e-mail dos contatos.
    • FLEXIBLE_ASSOCIATION_LABEL: inclua este tipo de coluna para indicar que a coluna contém rótulos de associação.
    • ASSOCIATION_KEYS: apenas para as importações de uma mesma associação de objeto, inclua este tipo de coluna para o identificador exclusivo dos mesmos registros de objeto que você está associando. Por exemplo, na solicitação de importação de uma associação de contatos, a coluna Contato associado [e-mail/ID de registo] deve ter o columnType ASSOCIATION_KEYS. Saiba mais sobre como configurar o seu arquivo de importação para uma importação de mesma associação de objeto.
  • toColumnObjectTypeId: para importações de vários arquivos ou de vários objetos, o nome ou objectTypeId do objeto a que pertence a propriedade de coluna comum ou o rótulo de associação. Inclua esse campo para a propriedade de coluna comum no arquivo do objeto ao qual a propriedade não pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, inclua toColumnObjectTypeId para a coluna E-mail no arquivo da empresa.
  • foreignKeyType: apenas para importações de vários arquivos, o tipo de associação que a coluna comum deve usar, especificada pelo associationTypeId e associationCategory. Inclua esse campo para a propriedade de coluna comum no arquivo do objeto ao qual a propriedade não pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, inclua foreignKeyType para a coluna E-mail no arquivo da empresa.
  • associationIdentifierColumn: apenas para importações de vários arquivos, indica a propriedade usada na coluna comum para associar os registros. Inclua esse campo para a propriedade de coluna comum no arquivo do objeto ao qual a propriedade pertence. Por exemplo, se estiver associando contatos e empresas em dois arquivos com o E-mail da propriedade do contato como a coluna comum, defina associationIdentifierColumn como true para a coluna de E-mail no arquivo do contato.

Importar um arquivo com um objeto

Veja abaixo um exemplo do corpo de solicitação de importação de um arquivo para criar contatos:

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] }# This example a local file named 'test_import.csv' # This file contains a list of contact records to import. import requests import json import os url = "https://api.hubapi.com/crm/v3/imports" YOUR_ACCESS_TOKEN = 'xxxxxxx'; # Content-Type header will be set automatically by the requests library headers = { 'authorization': 'Bearer %s' % YOUR_ACCESS_TOKEN } data = { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "Nov-event-leads.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": True, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } datastring = json.dumps(data) payload = {"importRequest": datastring} current_dir = os.path.dirname(__file__) relative_path = "./test_import.csv" absolute_file_path = os.path.join(current_dir, relative_path) files = [ ('files', open(absolute_file_path, 'rb')) ] print(files) response = requests.request("POST", url, data=payload, files=files, headers=headers) print(response.text.encode('utf8')) print(response.status_code) # Using this endpoint requires using sending multi-part form encoded data. Here is an example curl request: # importing a file named import_file.csv # create a variable for the importRequest JSON myJSON=$(cat <<EOF { "name": "November Marketing Event Leads", "importOperations": { "0-1": "CREATE" }, "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "import_file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First Name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last Name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" } ] } } ] } EOF ) YOUR_ACCESS_TOKEN="xxx-xxx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" curl -v \ -F "files=@import_file.csv;type=text/csv" \ -F "importRequest=$myJSON;type=application/json" \ -H "Authorization: Bearer $YOUR_ACCESS_TOKEN" \ https://api.hubapi.com/crm/v3/imports

Importar um arquivo com vários objetos

Veja abaixo um exemplo de solicitação de importação e associação de contatos e empresas em um único arquivo com rótulos de associação:

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "Association Label Import", "dateFormat": "DAY_MONTH_YEAR", "files": [ { "fileName": "association label example.xlsx", "fileFormat": "SPREADSHEET", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email" }, { "columnObjectTypeId": "0-2", "columnName": "Domain", "propertyName": "domain" }, { "columnName": "Association Label", "columnType": "FLEXIBLE_ASSOCIATION_LABEL", "columnObjectTypeId": "0-1", "toColumnObjectTypeId": "0-2" } ] } } ] }

Importar vários arquivos

Veja abaixo um exemplo de corpo de solicitação de importação e associação de contatos e empresas em dois arquivos, onde o E-mail da propriedade do contato é a coluna comum nos arquivos:

// Example POST to https://api.hubspot.com/crm/v3/imports // Content-Type header set to multipart/form-data { "name": "Contact Company import", "dateFormat": "YEAR_MONTH_DAY", "files": [ { "fileName": "contact-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-1", "columnName": "First name", "propertyName": "firstname" }, { "columnObjectTypeId": "0-1", "columnName": "Last name", "propertyName": "lastname" }, { "columnObjectTypeId": "0-1", "columnName": "Email", "propertyName": "email", "associationIdentifierColumn": true } ] } }, { "fileName": "company-import-file.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnObjectTypeId": "0-2", "columnName": "Company name", "propertyName": "name" }, { "columnObjectTypeId": "0-2", "columnName": "Company domain name", "propertyName": "domain", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnObjectTypeId": "0-2", "toColumnObjectTypeId": "0-1", "columnName": "Email", "propertyName": null, "foreignKeyType": { "associationTypeId": 280, "associationCategory": "HUBSPOT_DEFINED" } } ] } } ] }

Em uma solicitação bem-sucedida, a resposta incluirá um importId, que poderá ser usado para recuperar ou cancelar a importação. Uma vez concluída, você poderá exibir a importação no HubSpot, mas as importações concluídas por meio da API não estarão disponíveis como uma opção ao filtrar registros por importação em exibições, listas, relatórios ou fluxos de trabalho.

Obter importações anteriores

Para recuperar todas as importações da sua conta da HubSpot, faça uma solicitação GET para /crm/v3/imports/. Para recuperar informações para uma importação específica, faça uma solicitação GET para /crm/v3/imports/{importId}.

Ao recuperar importações, as informações serão retornadas, incluindo o nome, a fonte, o formato de arquivo, o idioma, o formato de data e os mapeamentos de coluna da importação. O estado da importação também será retornado, que pode ser qualquer um dos seguintes:

  • INICIADO: o HubSpot reconhece que a importação existe, mas a importação ainda não começou a ser processada.
  • PROCESSANDO: A importação está sendo processada ativamente.
  • CONCLUÍDO: A importação está completa. Todos os objetos, atividades ou associações foram atualizados ou criados.
  • FALHOU: Ocorreu um erro que não foi detectado quando a importação foi iniciada. A importação não foi concluída.
  • CANCELADO: o usuário cancelou a exportação enquanto estava em qualquer um dos estados INICIADO, PROCESSANDO ou DIFERIDO.
  • DIFERIDO: O número máximo de importações (três) estão sendo processadas ao mesmo tempo. A importação começará assim que uma das outras importações terminar o processamento.

Saiba mais sobre a paginação e limitação de resultados na guia Endpoints, na parte superior deste artigo.

Observação: ao recuperar importações usando um token de acesso de aplicativo privado, a resposta incluirá apenas as importações realizadas por esse aplicativo privado. As importações realizadas no HubSpot ou por meio de outro aplicativo privado não serão retornadas.

Cancel an import

To cancel an active import, make a POST request to /crm/v3/imports/{importId}/cancel

View and troubleshoot import errors

To view errors for a specific import, make a GET request to /crm/v3/imports/{importId}/errors. Learn more about common import errors and how to resolve them.

For errors such as Incorrect number of columns, Unable to parse JSON or 404 text/html is not accepted:

  • Ensure that there is a column header for each column in your file, and that the request body contains a columnMapping entry for each column. The following criteria should be met:
    • The column order in the request body and import file should match. If the column order doesn't match, the system will attempt to automatically reorder but may be unsuccessful, resulting in an error when the import is started.
    • Every column needs to be mapped. If a column is not mapped, the import request may still be successful, but would result in the Incorrect number of columns error when the import is started.
  • Ensure that the file's name and the fileName field in your request JSON match, and that you've included the file extension in the fileName field. For example, import_name.csv.
  • Ensure that your header includes Content-Type with a value of multipart/form-data.

Observação: se você receber um erro, verifique se há cabeçalhos duplicados, como Content-Type. Isso pode ocorrer se você estiver usando o Postman ou se ele estiver incluído no cabeçalho do seu script Python. Remova o objeto duplicado antes de concluir a solicitação. 

Limites

Ao usar a API de importações, você pode importar até 80.000.000 linhas por dia. No entanto, os arquivos de importação individuais são limitados a 1.048.576 linhas ou 512 MB, o que ocorrer primeiro.

Se a solicitação exceder o limite de linhas ou de tamanho, o HubSpot emitirá um erro 429 HTTP. Ao se aproximar desses limites, é recomendável dividir sua importação em várias solicitações.  


Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..