Última modificación: 22 de agosto de 2025

Run in Postman
Para la versión anterior, consulta la documentación de la API de asociaciones v3.
Las asociaciones representan las relaciones entre objetos y actividades en el CRM. Pueden existir asociaciones de registros entre registros de diferentes objetos (por ejemplo, contacto con empresa), así como de un mismo objeto (por ejemplo, empresa con empresa). Puedes usar los puntos de terminación de asociaciones para crear, obtener, actualizar o eliminar asociaciones entre registros o entre registros y actividades. Los puntos de terminación del esquema de asociaciones te permiten ver los tipos de asociaciones admitidos en tu cuenta, así como crear tus propios tipos de asociaciones y asignar etiquetas a las relaciones de los registros. Se admiten etiquetas de asociación entre contactos, empresas, negocios, tickets y objetos personalizados, y se pueden usar en herramientas de HubSpot, como listas y workflows. Obtén más información sobre las API de objetos, registros, propiedades y asociaciones en la guía Comprender el CRM.
Nota: La API de asociaciones v4 es compatible con la versión 9.0.0 o posterior del cliente NodeJS HubSpot.

​
Tipos de asociaciones definidos por HubSpot

HubSpot proporciona un conjunto de tipos de asociaciones predefinidos (por ejemplo, contacto con empresa sin etiqueta), pero los administradores de cuentas pueden definir sus propias etiquetas de asociación para proporcionar información adicional de las relaciones entre los registros (por ejemplo, mánager y empleado). Existen dos tipos de asociaciones definidas por HubSpot:
  • Principal: la empresa principal con la que está asociado el otro registro. Las asociaciones principales se pueden utilizar en herramientas de HubSpot, como listas y workflows. En los registros con varias empresas asociadas, esta API permite cambiar cuál empresa se considera la principal.
  • Sin etiqueta: un tipo de asociación agregado cuando se asocia cualquier contacto, empresa, negocio, ticket o registro de objeto personalizado. Este tipo indica que existe una asociación y siempre se devolverá en las respuestas con un valor de etiqueta de null. Cuando un registro tiene una asociación principal o una etiqueta de asociación personalizada, esos tipos se enumerarán junto con el tipo de asociación sin etiqueta.
Puedes ver todos los tipos de asociaciones definidos por HubSpot en esta sección.

​
Etiquetas individuales vs. emparejadas

Hay dos tipos de etiquetas de asociación que puedes usar para describir las relaciones entre registros:
  • Individual: una etiqueta que se aplica a ambos registros en la relación. Por ejemplo, Amigo o Colega.
  • Emparejadas: un par de etiquetas para cuando se utilizan diferentes palabras para describir cada lado de la relación de los registros asociados. Por ejemplo, Padre e Hijo o Empleador y Empleado. Para crear etiquetas emparejadas, debes incluir el campo inverseLabel en la solicitud para darle un nombre a la segunda etiqueta en el par.

​
Crear tipos de asociaciones

Puedes crear tipos de asociaciones personalizadas en HubSpot o a través del punto de terminación de la API del esquema de asociaciones. Puedes crear hasta 10 tipos de asociaciones entre cada par de objetos (por ejemplo, contactos y empresas, contactos y contactos). Para crear un tipo de asociación a través de la API, haz una solicitud POST a /crm/v4/associations/{fromObjectType}/{toObjectType}/labels e incluye lo siguiente:
  • nombre: el nombre interno del tipo de asociación. Este valor no puede incluir guiones ni comenzar con un carácter numérico.
  • etiqueta: el nombre de la etiqueta de asociación tal como se muestra en HubSpot.
  • inverseLabel (solo etiquetas emparejadas): el nombre de la segunda etiqueta del par de etiquetas.
Por ejemplo, tu solicitud podría tener un aspecto similar al siguiente:

​
Obtener tipos de asociaciones

Para ver los tipos de asociaciones entre objetos específicos, haz una solicitud GET a /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Recibirás una matriz en la que cada elemento contiene:
  • categoría: si el tipo de asociación fue creado por HubSpot (HUBSPOT_DEFINED) o por un usuario (USER_DEFINED).
  • typeId: el ID numérico de ese tipo de asociación. Se utiliza para definir una etiqueta al asociar registros. Consulta esta lista para ver todos los valores typeId definidos por HubSpot.
  • etiqueta: la etiqueta alfanumérica. Será null para el tipo de asociación sin etiqueta.
También puedes encontrar estos valores en HubSpot en la configuración de asociaciones.

​
Asociar registros

​
Asociar registros sin etiquetas

Puedes crear una asociación sin etiqueta predeterminada entre dos registros o configurar asociaciones sin etiqueta para registros en bloque. Para configurar una asociación individual predeterminada entre dos registros, haz una solicitud PUT a /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId} En la URL de la solicitud, incluye:
  • fromObjectType: el ID del objeto que estás asociando. Para encontrar los valores de ID, consulta esta lista de ID de tipos de objetos, o, para contactos, empresas, negocios, tickets y notas, puedes usar el nombre del objeto (por ejemplo, contact, company).
  • fromObjectId: el ID del registro que se asociará.
  • toObjectType: el ID del objeto con el que estás asociando el registro. Para encontrar los valores de ID, consulta esta lista de ID de tipos de objetos, o, para contactos, empresas, negocios, tickets y notas, puedes usar el nombre del objeto (por ejemplo, contact, company).
  • toObjectId: el ID del registro con el que se va a hacer la asociación
Por ejemplo, para asociar un registro de contacto cuyo ID es 12345 con un registro de empresa cuyo ID es 67891, la URL de tu solicitud sería: /crm/v4/objects/contact/12345/associations/default/company/67891. Para configurar asociaciones predeterminadas en bloque, haz una solicitud POST a crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default. En el cuerpo de la solicitud, incluye valores objectId para los registros que quieres asociar.
Nota: El número de asociaciones que puede tener un registro depende del objeto y de tu suscripción a HubSpot.

​
Asociar registros con etiquetas

Para asociar dos registros y definir una etiqueta para describir la asociación, haz una solicitud PUT a /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}. En el cuerpo de la solicitud, incluye associationCategory y associationTypeId para indicar el tipo de asociación que quieres crear. Si estás creando asociaciones sin etiqueta, puedes usar los puntos de terminación predeterminados descritos en la sección anterior que no requieren associationCategory ni associationTypeId. Si estás creando asociaciones con una etiqueta, puedes consultar esta lista de ID de tipos predeterminados o tendrás que obtener los tipos de asociaciones personalizados entre esos objetos.
Nota: En cuanto a las relaciones de etiquetas multiobjeto y emparejadas, asegúrate de usar el typeId que se refiere a la dirección correcta (por ejemplo, contacto a empresa vs. empresa a contacto, empleado a mánager vs. mánager a empleado).
Por ejemplo, para asociar un contacto con un negocio usando una etiqueta personalizada: 1. Haz una solicitud GET a /crm/v4/associations/contact/deal/labels. 2. En la respuesta, fíjate en los valores typeId y category de la etiqueta. El ID será un número (por ejemplo, 36), y la categoría siempre será USER_DEFINED para las etiquetas personalizadas. 3. Haz una solicitud PUT a /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}con el siguiente cuerpo: 
/// Example request body
[
  {
    "associationCategory": "USER_DEFINED",
    "associationTypeId": 36
  }
]

​
Definir y gestionar límites de asociaciones

Puedes definir límites para el número de registros asociados entre objetos o la frecuencia con la que se puede utilizar una etiqueta para describir asociaciones. También hay límites técnicos y límites basados en tu suscripción de HubSpot.

​
Crear o actualizar límites de asociaciones

Puedes crear límites de asociaciones nuevos o actualizar los existentes entre los objetos.
  • Para crear límites, haz una solicitud POST a crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create.
  • Para actualizar los límites existentes, haz una solicitud POST a crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update.
En el cuerpo de la solicitud, incluye inputs con lo siguiente:
ParámetroDescripción
categoryLa categoría de la asociación para la que estás fijando un límite, ya sea HUBSPOT_DEFINED o USER_DEFINED.
typeIdEl ID numérico del tipo de asociación para la que quieres fijar un límite. Consulta esta lista de valores typeId predeterminados u obtén el valor de las etiquetas personalizadas.
maxToObjectIdsEl número máximo de asociaciones permitido para el tipo de asociación.
Por ejemplo, para fijar límites para que un negocio se pueda asociar con un máximo de cinco contactos con un solo contacto con la etiqueta punto de contacto en un negocio, tu solicitud debería lucir así: 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/create
{
  "inputs": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "maxToObjectIds": 5
    },
    {
      "category": "USER_DEFINED",
      "typeId": 35,
      "maxToObjectIds": 1
    }
  ]
}

​
Obtener límites de asociaciones

  • Para leer todos los límites de asociaciones definidos, haz una solicitud GET a /crm/v4/associations/definitions/configurations/all. Se devolverán los límites de asociaciones definidos en todos los objetos.
  • Para leer límites de asociaciones entre dos objetos específicos, haz una solicitud GET a /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}.
En ambas solicitudes, la respuesta devolverá los valores de las asociaciones para category, typeId, maxToObjectIds y label. Por ejemplo, si se obtienen los límites entre negocios y contactos, la respuesta sería similar a: 
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
  "results": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "userEnforcedMaxToObjectIds": 5,
      "label": null
    }
  ]
}

​
Eliminar límites de asociaciones

Para eliminar límites de asociaciones específicos, haz una solicitud POST a /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge. En el cuerpo de la solicitud, incluye los valores category y typeId de los tipos de asociaciones para los cuáles quieres eliminar los límites. Por ejemplo, para eliminar el límite Punto de contacto entre negocios y contactos, la solicitud luciría de esta forma: 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
  "inputs": [
    {
      "category": "USER_DEFINED",
      "typeId": 35
    }
  ]
}
Si se hace correctamente, recibirás una respuesta 204 y el límite incluido volverá al valor predeterminado del sistema (es decir, Muchos contactos pueden tener la etiqueta Punto de contact).

​
Informes sobre alto uso de asociaciones

Existen límites técnicos en cuanto al número de asociaciones que puede tener un registro. Puedes usar la API de asociaciones para obtener un informe de los registros que se están aproximando al máximo límite de asociaciones o que ya lo alcanzaron. Para obtener el informe, haz una solicitud POST a crm/v4/associations/usage/high-usage-report/{userID}. El archivo incluye registros que usan el 80% o más de su límite de asociaciones. Por ejemplo, si se puede asociar una empresa con hasta 50.000 contactos, la empresa se incluirá en el archivo si tiene 40.000 o más registros asociados. El archivo se enviará al correo del usuario cuyo ID se incluyó en la URL de la solicitud. Descubre cómo obtener ID de usuario con la API de usuarios.

​
Valores de ID de tipos de asociaciones

Las siguientes tablas incluyen los valores associationTypeId definidos por HubSpot que especifican el tipo de asociación. Los tipos de asociaciones varían dependiendo de los objetos incluidos y de la dirección de la asociación (por ejemplo, contacto a empresa es diferente de empresa a contacto). Si creas objetos personalizados o etiquetas de asociaciones personalizadas, los tipos de asociaciones relacionados tendrán valores typeId únicos que deberás obtener o localizar en la configuración de asociaciones de HubSpot.
Nota: Los tipos de asociaciones de empresas predeterminadas incluyen un tipo de asociación sin etiqueta y un tipo de asociación principal. Si un registro tiene más de una empresa asociada, solo una puede ser la empresa principal. Las otras asociaciones pueden ser sin etiqueta o tener etiquetas de asociación personalizadas.

​
Asociaciones v1 (anterior)

Si estás usando la API de asociaciones v1, consulta la tabla que aparece abajo para obtener más información sobre qué ID usar al asociar registros.
Tipo de asociaciónID
Contacto a empresa1
Empresa a contacto (predeterminado)2
Empresa a contacto (todas las etiquetas)280
Negocio a contacto3
Contacto a negocio4
Negocio a empresa5
Empresa a negocio6
Empresa a interacción7
Interacción a empresa8
Contacto a interacción9
Interacción a contacto10
Negocio a interacción11
Interacción a negocio12
Empresa principal a empresa secundaria13
Empresa secundaria a empresa principal14
Contacto a ticket15
Ticket a contacto16
Ticket a interacción17
Interacción a ticket18
Negocio a elemento de pedido19
Elemento de pedido a negocio20
Empresa a ticket25
Ticket a empresa26
Negocio a ticket27
Ticket a negocio28