Última modificación: 22 de agosto de 2025

Run in Postman

 Utiliza la API de importaciones para importar registros y actividades del CRM, como los contactos, las empresas y las notas en tu cuenta de HubSpot. Una vez los datos hayan sido importados, puedes acceder y actualizar los registros y actividades con los diversos endpoints de la API del CRM, incluida la API de contactos, la API de asociaciones y las API de interacciones. También puedes importar registros y actividades usando la herramienta de importación guiada en HubSpot. Antes de comenzar la importación encuentra más información sobre:

​
Nota:

Para crear eventos personalizados o asociarlos a registros, usa la API de eventos personalizados en lugar de importar.

​
Iniciar una importación

Puedes iniciar una importación realizando una solicitud POST a /crm/v3/imports con un cuerpo que especifique cómo asignar las columnas del archivo de importación a las propiedades correspondientes en HubSpot. Las importaciones a través de la API se envían como solicitudes con formato de tipo de datos de formulario, y el cuerpo de la solicitud incluye los siguientes campos:
  • importRequest: es un campo de texto que contiene la solicitud JSON.
  • files: es un campo de archivo que contiene el archivo de importación.
Para el encabezado de la solicitud, agrega un encabezado Content-Type con el valor multipart/form-data. La siguiente captura de pantalla muestra cómo se vería la solicitud cuando usas una aplicación como Postman:
postman-import-request-no-response0

​
Formato de los datos de importRequest

En la solicitud, define los detalles del archivo de importación, incluida la asignación de las columnas de la hoja de cálculo a los datos de HubSpot. La solicitud debe incluir los siguientes campos:
  • name: el nombre de la importación. En HubSpot, este es el nombre que aparece en la herramienta de importaciones, así como el nombre al que puedes hacer referencia en otras herramientas, como las listas.
  • importOperations: es un campo opcional utilizado para indicar si la importación debe crear y actualizar, solo crear o solo actualizar registros para un determinado objeto o actividad. Incluye objectTypeId para el objeto o actividad y si quieres UPSERT (crear y actualizar), CREATE o UPDATE registros. Por ejemplo, el campo se vería así en la solicitud: "importOperations": {"0-1": "CREATE"}. Si no incluyes este campo, el valor predeterminado para la importación es UPSERT.
  • dateFormat: es el formato para las fechas incluidas en el archivo. De forma predeterminada, esto se estructura por MONTH_DAY_YEAR, pero también puedes usar DAY_MONTH_YEAR o YEAR_MONTH_DAY.
  • marketableContactImport: es un campo opcional para indicar el estado de marketing de los contactos en tu archivo de importación. Este campo solo se usa cuando se importan contactos a cuentas que tienen acceso a los contactos de marketing. Para establecer los contactos como de marketing en el archivo, usa el valor true. Para establecer los contactos como no de marketing en el archivo, usa el valor false.
  • createContactListFromImport: es un campo opcional para crear una lista estática de los contactos en la importación. Para crear una lista a partir del archivo, usa el valor true.
  • files: es una matriz que contiene la información del archivo de importación.
    • fileName: el nombre del archivo de importación.
    • fileFormat: el formato del archivo de importación. Para los archivos CSV, usa el valor CSV. Para los archivos de Excel, usa el valor SPREADSHEET.
    • fileImportPage: contiene la matriz columnMappings que es necesaria para asignar los datos de tu archivo de importación a los datos de HubSpot. Más información sobre la asignación de columnas a continuación.

​
Asignar las columnas del archivo a las propiedades de HubSpot

Dentro de la matriz columnMappings, incluye una entrada para cada título en la columna del archivo de importación, que coincida con el orden en la hoja de cálculo. Para cada columna, incluye los siguientes campos:
  • columnObjectTypeId: el nombre o el valor objectTypeId del objeto o la actividad a la que pertenecen los datos. Consulta este artículo para obtener una lista completa de los valores objectTypeId.
  • columnName: el nombre del título de la columna. Debe coincidir exactamente con el nombre del título de la columna en el archivo.
  • propertyName: el nombre interno de la propiedad de HubSpot a la que se le asignarán los datos. Para la columna común en las importaciones de varios archivos, propertyName debe ser null cuando se utilice el campo toColumnObjectTypeId.
  • columnType: se utiliza para especificar que una columna contiene una propiedad de identificador única. Dependiendo de la propiedad y el propósito de la importación, puedes utilizar uno de los siguientes valores:
    • HUBSPOT_OBJECT_ID: el ID de un registro. Por ejemplo, el archivo de importación de contactos puede contener una columna ID de registro que tenga el ID de la empresa con la que deseas asociar los contactos.
    • HUBSPOT_ALTERNATE_ID: un identificador único distinto del ID de registro. Por ejemplo, el archivo de importación de contactos puede contener una columna de Correo electrónico que tenga las direcciones de correo electrónico de los contactos.
    • FLEXIBLE_ASSOCIATION_LABEL: incluye este tipo de columna para indicar que la columna contiene etiquetas de asociación.
    • ASSOCIATION_KEYS: utiliza este tipo de columna únicamente para las importaciones que asocien el mismo objeto, e inclúyelo para especificar el identificador único de los registros de objeto que quieres asociar. Por ejemplo, en tu solicitud de importación de una asociación de contactos, la columna Contacto asociado [correo electrónico o ID de registro] debe tener un columnType de ASSOCIATION_KEYS. Más información sobre cómo configurar el archivo de importación para una misma importación de asociación de objetos.
  • toColumnObjectTypeId: se utiliza para importaciones que incluyan varios archivos o varios objetos, este campo indica el nombre o objectTypeId del objeto al que pertenece la propiedad de la columna común o la etiqueta de asociación. Debes incluir este campo para la propiedad de columna común en el archivo del objeto al que no pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos usando la propiedad de contacto Correo electrónico como columna común, incluye el toColumnObjectTypeId para la columna Correo electrónico en el archivo de empresas.
  • foreignKeyType: se utiliza solo para importaciones de varios archivos, es el tipo de asociación que debe usar la columna común, especificado por associationTypeId y associationCategory. Debes incluir este campo para la propiedad de columna común en el archivo del objeto al que no pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos con la propiedad de contacto Correo electrónico como columna común, incluye el foreignKeyType para la columna Correo electrónico en el archivo de empresas.
  • associationIdentifierColumn: se utiliza solo para importaciones de varios archivos, este campo indica la propiedad utilizada en la columna común para asociar a los registros. Incluye este campo para la propiedad de columna común en el archivo del objeto al que pertenece la propiedad. Por ejemplo, si estás asociando contactos y empresas en dos archivos con la propiedad de contacto Correo electrónico como columna común, establece la associationIdentifierColumn en true para la columna Correo electrónico en el archivo de contactos.

​
Importar un archivo con un objeto

A continuación, incluimos un ejemplo del cuerpo de la solicitud para importar un archivo y crear contactos: 
// 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"
}
]
}
}
]
}
A continuación, se muestra otro ejemplo de importación de un archivo para crear y actualizar participantes de los eventos de marketing: 
// 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 un archivo con varios objetos

A continuación, incluimos un ejemplo del cuerpo de la solicitud de importación y la asociación de contactos y empresas en un archivo con etiquetas de asociación: 
// 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 varios archivos

A continuación, incluimos un ejemplo del cuerpo de la solicitud de importación y la asociación de contactos y empresas en dos archivos, donde la propiedad de contacto Correo electrónico es la columna común en los archivos: 
// 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" } } ] } } ] }
Si la solicitud es exitosa, la respuesta incluirá un importId que puedes usar para recuperar o cancelar la importación. Una vez completada, podrás ver la importación en HubSpot. Sin embargo, las importaciones que se completan a través de la API no estarán disponibles como opción al filtrar los registros por importación en las vistas, las listas, los informes o los workflows.

​
Obtener importaciones anteriores

Para obtener todas las importaciones de tu cuenta de HubSpot, haz una solicitud GET a /crm/v3/imports/. Para obtener información sobre una importación en específico, haz una solicitud GET a /crm/v3/imports/{importId}. Cuando obtengas las importaciones, estas incluirán información como el nombre de la importación, su origen, el formato de archivo, el idioma, el formato de fecha y las asignaciones de las columnas. También incluirá el state de la importación, que puede ser cualquiera de los siguientes:
  • STARTED: HubSpot reconoce que la importación existe, pero aún no ha comenzado a procesarse.
  • PROCESSING: La importación se está procesando.
  • DONE: La importación está completa. Todos los objetos, las actividades o asociaciones han sido actualizadas o creadas.
  • FAILED: Se produjo un error que no se detectó cuando se inició la importación. La importación no se completó.
  • CANCELED: El usuario canceló la importación mientras estaba en cualquiera de los estados STARTED, PROCESSING o DEFERRED.
  • DEFERRED: El número máximo de importaciones (tres) se están procesando al mismo tiempo. La importación comenzará una vez que una de las otras importaciones terminen de procesarse.
Obtén más información sobre la paginación y la limitación de resultados en la documentación de referencia.

​
Nota:

Al recuperar importaciones, la respuesta solo incluirá las importaciones realizadas por la misma aplicación. Las importaciones que se completen en HubSpot o a través de otra aplicación no serán devueltas.

​
Cancelar una importación

Para cancelar una importación activa, haz una solicitud POST a /crm/v3/imports/{importId}/cancel.

​
Ver y solucionar los errores de importación

Para ver los errores de una importación en específico, haz una solicitud GET a /crm/v3/imports/{importId}/errors. Obtén más información sobre los errores más comunes de importación y cómo resolverlos. Para los errores como Número incorrecto de columnas, No se puede analizar JSON o 404 texto o html no aceptado:
  • Asegúrate de que cada columna del archivo tenga un título y de que el cuerpo de la solicitud incluya una entrada columnMapping para cada columna. Deben cumplir con los siguientes criterios:
    • El orden de las columnas en el cuerpo de la solicitud y en el archivo de importación debe coincidir. Si el orden de las columnas no coincide, el sistema intentará reordenarlas automáticamente, pero puede que no lo consiga, lo que provocará un error al iniciar la importación.
    • Cada columna debe estar asignada. Si una columna no está asignada, la solicitud de importación puede seguir siendo exitosa, pero se generará el error Número incorrecto de columnas al iniciar la importación.
  • Asegúrate de que el nombre del archivo y el campo fileName del JSON de la solicitud coincidan, y de que has incluido la extensión del archivo en el campo fileName. Por ejemplo, import_name.csv.
  • Asegúrate de que el encabezado incluye Content-Type con un 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
}
]
}
}
]
}

​
Nota:

Si recibes un error, valida si hay encabezados duplicados como Content-Type. Esto puede ocurrir si estás usando Postman o si está incluido en el encabezado de tu script de Python. Elimina los duplicados antes de completar la solicitud.

​
Límites

Al usar la API de importaciones, puedes importar hasta 80.000.000 filas por día. Sin embargo, los archivos de importación individuales están limitados a 1.048.576 filas o 512 MB, lo que ocurra primero. Si tu solicitud supera el límite de filas o tamaño, HubSpot responderá con un error HTTP 429. Cuando te acerques a estos límites, se recomienda dividir tu importación en varias solicitudes.