API do CRM | Importações

• Requisitos de arquivo
• Propriedades necessárias para importações de registros e atividades
• Propriedades necessárias para importações de participantes de eventos de marketing

​

Iniciar uma importação

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

​

Formatar dados de importRequest

• 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 para o objeto/atividade e, se você quiser UPSERT (criar e atualizar), CREATE ou UPDATE 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 como 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

• 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. Isso deve corresponder exatamente ao nome do cabeçalho da coluna no arquivo.
• 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, propertyName deve ser null quando toColumnObjectTypeId é usado.
• columnType: usado para especificar que uma coluna contém um propriedade de identificador exclusivo. Dependendo da propriedade e do 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, em sua solicitação para uma importação de associação de contatos, a coluna Contato Associado \[ID de e-mail/Registro] deve ter um columnType de 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

// 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"
}
]
}
}
]
}

// Example POST to https://api.hubspot.com/crm/v3/imports
// Content-Type header set to multipart/form-data

{ "name": "Marketing Events Import Example", "marketingEventObjectId": 377224141223, "importOperations": { "0-1": "UPSERT", "0-54": "CREATE" }, "dateFormat": "YEAR_MONTH_DAY", "timeZone": "America/New_York", "files": [ { "fileName": "Marketing Events Import Example.csv", "fileFormat": "CSV", "fileImportPage": { "hasHeader": true, "columnMappings": [ { "columnName": "First Name", "columnObjectTypeId": "0-1", "propertyName": "firstname", "columnType": "STANDARD" }, { "columnName": "Last Name", "columnObjectTypeId": "0-1", "propertyName": "lastname", "columnType": "STANDARD" }, { "columnName": "Email", "columnObjectTypeId": "0-1", "propertyName": "email", "columnType": "HUBSPOT_ALTERNATE_ID" }, { "columnName": "Registered", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "REGISTERED" }, { "columnName": "Attended", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "JOINED" }, { "columnName": "Left", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "LEFT" }, { "columnName": "Cancelled", "columnObjectTypeId": "0-54", "columnType": "EVENT_TIMESTAMP", "marketingEventSubmissionType": "CANCELLED" } ] } } ] }

​

Importar um arquivo com vários objetos

// 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

// 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" } } ] } } ] }

​

Obter importações anteriores

• STARTED: o HubSpot reconhece que a importação existe, mas a importação ainda não começou a ser processada.
• PROCESSING: a importação está sendo processada ativamente.
• DONE: a importação foi concluída. Todos os objetos, atividades ou associações foram atualizados ou criados.
• FAILED: ocorreu um erro que não foi detectado quando a importação foi iniciada. A importação não foi concluída.
• CANCELED: o usuário cancelou a exportação enquanto estava em qualquer um dos estados STARTED, PROCESSING ou DEFERRED.
• DEFERRED: 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.

​

Cancelar uma importação

​

Exibir e solucionar erros de importação

• Verifique se há um cabeçalho para cada coluna no arquivo e se o corpo da solicitação contém um columnMapping para cada coluna. Os seguintes critérios devem ser atendidos:
  • A ordem das colunas no corpo da solicitação e no arquivo de importação devem coincidir. Se a ordem das colunas não coincidir, o sistema tentará reclassificá-las automaticamente, mas poderá não ser bem-sucedido, resultando em um erro quando a importação for iniciada.
  • Cada coluna precisa ser mapeada. Se uma coluna não for mapeada, a solicitação de importação ainda poderá ser bem-sucedida, mas resultará no erro Número incorreto de colunas quando a importação for iniciada.
• Verifique se o nome do arquivo e o campo fileName na sua solicitação JSON coincidem e se você incluiu a extensão de arquivo no campo fileName. Por exemplo, import_name.csv.
• Verifique se o cabeçalho inclui Content-Type com um valor de multipart/form-data.

Example POST URL:
https://api.hubapi.com/crm/v3/imports?

Example importRequest JSON data:
This example contains 3 columns:
- First name, mapped to the firstname contact property
- Email, mapped to the email contact property
- Company ID, which contains a list of company record IDs
that the contact will be assocated with.
{
"name": "test_import",
"files": [
{
"fileName": "final_emails.csv",
"fileImportPage": {
"hasHeader": true,
"columnMappings": [
{
"ignored": false,
"columnName": "First Name",
"idColumnType": null,
"propertyName": "firstname",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Email",
"idColumnType": "HUBSPOT_ALTERNATE_ID",
"propertyName": "email",
"foreignKeyType": null,
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
},
{
"ignored": false,
"columnName": "Company ID",
"idColumnType": "HUBSPOT_OBJECT_ID",
"propertyName": null,
"foreignKeyType": {
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 1
},
"columnObjectType": "CONTACT",
"associationIdentifierColumn": false
}
]
}
}
]
}

​

Limites