Última modificação: 22 de agosto de 2025

Run in Postman
Para obter a versão anterior, consulte a documentação da API de Associações v3.
As associações representam as relações entre objetos e atividades no CRM da HubSpot. Podem existir associações entre registros de diferentes objetos (por exemplo, contato para empresa), bem como dentro do mesmo objeto (por exemplo, empresa para empresa). Você pode usar os pontos de extremidade de associações para criar, recuperar, atualizar ou excluir associações entre registros ou entre registros e atividades. Os pontos de extremidade do esquema de associação permitem que você exiba os tipos suportados de associações em sua conta, bem como crie seus próprios tipos de associação e atribua rótulos às suas relações de registros. Os rótulos de associação são aceitos entre contatos, empresas, negócios, tickets e objetos personalizados, e podem ser usados nas ferramentas do HubSpot, como listas e fluxos de trabalho. Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia Noções básicas do CRM.
Observação: a API de associações v4 é compatível com a versão 9.0.0 ou posterior do NodeJS HubSpot Client.

​
Tipos de associação definidos pelo HubSpot

O HubSpot fornece um conjunto de tipos de associação predefinidos (por exemplo, contato sem rótulo com empresa), mas os administradores da conta podem definir seus próprios rótulos de associação para fornecer contexto adicional para relacionamentos de registros (por exemplo, gerente e funcionário). Há dois tipos de associação definidos pelo HubSpot:
  • Principal: a empresa principal à qual o outro registro está associado. Associações principais podem ser usadas nas ferramentas da HubSpot, como listas e fluxos de trabalho. Para registros com várias empresas associadas, esta API aceita alterar qual empresa é considerada a principal.
  • Sem rótulo: um tipo de associação adicionado quando um registro de contato, empresa, negociação, ticket ou objeto personalizado é associado. Este tipo indica que existe uma associação e sempre será retornado em respostas com um valor de rótulo null. Quando um registro tem uma associação principal ou um rótulo de associação personalizado, esses tipos serão listados ao lado do tipo de associação sem rótulo.
Você pode exibir todos os tipos de associação definidos pelo HubSpot nesta seção.

​
Rótulos únicos versus pares de rótulos

Há dois tipos de rótulos de associação que você pode usar para descrever os relacionamentos entre os registros:
  • Único: um rótulo que se aplica a ambos os registros no relacionamento. Por exemplo, Amigo ou Colega.
  • Emparelhados: um par de rótulos para quando palavras diferentes são usadas para descrever cada lado do relacionamento dos registros associados. Por exemplo, Principal e Secundário ou Empregador e Funcionário. Para criar rótulos emparelhados, você deve incluir o campo inverseLabel na sua solicitação para nomear o segundo rótulo no par.

​
Criar tipos de associação

Você pode criar tipos de associação personalizados no HubSpot ou por meio do ponto de extremidade da API do esquema de associação. Você pode criar até 10 tipos de associação entre cada par de objetos (por exemplo, contatos e empresas, contatos e contatos). Para criar um tipo de associação por meio da API, faça uma solicitação POST para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels e inclua o seguinte em sua solicitação:
  • nome: o nome interno do tipo de associação. Esse valor não pode incluir hifens ou começar com um caractere numérico.
  • rótulo: o nome do rótulo de associação conforme mostrado no HubSpot.
  • inverseLabel (somente rótulos emparelhados): o nome do segundo rótulo no par de rótulos.
Por exemplo, sua solicitação pode ser semelhante a esta:

​
Recuperar tipos de associação

Para exibir os tipos de associação entre objetos específicos, faça uma solicitação GET para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Você receberá uma matriz, sendo que cada item conterá:
  • categoria: se o tipo de associação foi criado pelo HubSpot (HUBSPOT_DEFINED) ou por um usuário (USER_DEFINED).
  • typeId: o ID numérico para esse tipo de associação. Isso é usado para definir um rótulo ao associar registros. Consulte esta lista para ver todos os valores typeId definidos pelo HubSpot.
  • rótulo: o rótulo alfanumérico. Isso será null para o tipo de associação sem rótulo.
Você também pode encontrar esses valores no HubSpot em suas configurações de associação.

​
Associar registros

​
Associar registros sem um rótulo

Você pode criar uma associação padrão sem rótulo entre dois registros ou configurar associações sem rótulo para registros em massa. Para configurar uma associação padrão individual entre dois registros, faça uma solicitação PUT para /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId} No URL da solicitação, inclua:
  • fromObjectType: o ID do objeto que você está associando. Para localizar os valores de ID, consulte esta lista de IDs de tipo de objeto, ou, para contatos, empresas, negócios, tickets e observações, você pode usar o nome do objeto (por exemplo, contact, company).
  • fromObjectId: o ID do registro a associar.
  • toObjectType: o ID do objeto ao qual você está associando o registro. Para localizar os valores de ID, consulte esta lista de IDs de tipo de objeto, ou, para contatos, empresas, negócios, tickets e observações, você pode usar o nome do objeto (por exemplo, contact, company).
  • toObjectId: o ID do registro ao qual associar.
Por exemplo, para associar um registro de contato cuja ID é 12345 a um registro de empresa cuja ID é 67891, o URL da solicitação seria: /crm/v4/objects/contact/12345/associations/default/company/67891. Para configurar associações padrão em massa, faça uma solicitação POST para crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default. No corpo da solicitação, inclua valores de objectId para os registros que você deseja associar.
Observação: o número de associações que um registro pode ter depende do objeto e da sua assinatura do HubSpot.

​
Associar registros com um rótulo

Para associar dois registros e definir um rótulo para descrever a associação, faça uma solicitação PUT para /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}. No corpo da solicitação, inclua associationCategory e associationTypeId para indicar o tipo de associação que você deseja criar. Se você estiver criando associações sem rótulo, poderá usar os pontos de extremidade padrão descritos na seção acima que não exijam associationCategory ou associationTypeId. Se você estiver criando associações com um rótulo, poderá consultar esta lista de IDs de tipo padrão, ou precisará recuperar os tipos de associação personalizados entre esses objetos.
Observação: para relações entre objetos e rótulos emparelhados, certifique-se de usar o typeId que se refere à direção correta (por exemplo, Contato para Empresa vs. Empresa para Contato, Funcionário para Gerente vs. Gerente para Funcionário).
Por exemplo, para associar um contato a um negócio usando um rótulo personalizado: 1. Faça uma solicitação GET para /crm/v4/associations/contact/deal/labels. 2. Na resposta, observe os valores typeId e category para o rótulo. O ID será um número (por exemplo, 36) e a categoria será sempre USER_DEFINED para rótulos personalizados. 3. Envie uma solicitação PUT para /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId} com o seguinte corpo de solicitação: 
/// Example request body
[
  {
    "associationCategory": "USER_DEFINED",
    "associationTypeId": 36
  }
]

​
Definir e gerenciar limites de associação

Você pode configurar limites para o número de registros associados entre objetos ou a frequência com que um rótulo pode ser usado para descrever associações. Há também limites técnicos e limites baseados na sua assinatura do HubSpot.

​
Criar ou atualizar limites de associação

Você pode criar limites de associação novos ou atualizar os limites de associação existentes entre objetos.
  • Para criar limites, faça uma solicitação POST para crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create.
  • Para atualizar os limites existentes, faça uma solicitação POST para crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update.
No corpo da solicitação, inclua inputs com o seguinte:
DescriçãoParâmetro
categoryA categoria da associação para a qual você está definindo um limite HUBSPOT_DEFINED ou USER_DEFINED.
typeIdO ID numérico do tipo de associação para o qual você deseja definir um limite. Consulte esta lista de valores typeId padrão ou recupere o valor para rótulos personalizados.
maxToObjectIdsO número máximo de associações permitidas para o tipo de associação.
Por exemplo, para definir limites em que um negócio pode ser associado a um máximo de cinco contatos com apenas um contato rotulado como Ponto de contato, sua solicitação se pareceria com a seguinte: 
//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
    }
  ]
}

​
Recuperar limites de associação

  • Para ler todos os limites de associação definidos, faça uma solicitação GET para /crm/v4/associations/definitions/configurations/all. Isso retornará limites de associação personalizados definidos em todos os objetos.
  • Para ler os limites de associação entre dois objetos específicos, faça uma solicitação GET para /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}.
Para ambas as solicitações, a resposta retornará os valores das associações para category, typeId, maxToObjectIds e label. Por exemplo, ao recuperar limites entre negócios e contatos, a resposta seria semelhante à seguinte: 
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
  "results": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "userEnforcedMaxToObjectIds": 5,
      "label": null
    }
  ]
}

​
Excluir limites de associação

Para excluir limites de associação específicos, faça uma solicitação POST para /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge. No corpo da solicitação, inclua os valores de category e typeId dos tipos de associação para os quais você deseja remover os limites. Por exemplo, para remover o limite de Pontos de contato entre negócios e contatos, a solicitação seria semelhante à seguinte: 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
  "inputs": [
    {
      "category": "USER_DEFINED",
      "typeId": 35
    }
  ]
}
Se for bem-sucedido, você receberá uma resposta 204 e o limite incluído retornará ao padrão do sistema (ou seja, muitos contatos podem ter o rótulo Ponto de contact).

​
Gerar relatório sobre alto uso de associações

Há limites técnicos para o número de associações que um registro pode ter. Você pode usar a API de associações para recuperar um relatório de registros que estão se aproximando ou atingiram o limite máximo de associações. Para recuperar o relatório, faça uma solicitação POST para crm/v4/associations/usage/high-usage-report/{userID}. O arquivo inclui registros que usam 80% ou mais de seu limite de associação. Por exemplo, se uma empresa puder ser associada a até 50.000 contatos, ela será incluída no arquivo se tiver 40.000 contatos associados ou mais. O arquivo será enviado para o e-mail do usuário cujo ID foi incluído no URL da solicitação. Saiba como recuperar IDs de usuário com a API de usuários.

​
Valores de ID de tipo de associação

As tabelas a seguir incluem os valores associationTypeId definidos pelo HubSpot que especificam o tipo de associação. Os tipos de associação variam dependendo dos objetos incluídos e da direção da associação (por exemplo, Contato para Empresa é diferente de Empresa para Contato). Se você criar objetos personalizados ou rótulos de associação personalizados, os tipos de associação relacionados terão valores typeId que precisarão ser recuperados ou localizados nas configurações de associação no HubSpot.
Observação: os tipos de associação de empresa padrão incluem um tipo de associação sem rótulo e um tipo de associação principal. Se um registro tiver mais de uma empresa associada, somente uma poderá ser a empresa principal. As outras associações podem não ter rótulo ou ter rótulos de associação personalizados.

​
Associações v1 (antigas)

Se você estiver usando a API de associações v1, exiba a tabela abaixo para obter informações sobre IDs a serem usadas ao associar registros.
Tipo de associaçãoID
Contato para empresa1
Empresa para contato (padrão)2
Empresa para contato (todos os rótulos)280
Negócio para contato3
Contato para negócio4
Negócio para empresa5
Empresa para negócio6
Empresa para engajamento7
Engajamento para empresa8
Contato para engajamento9
Engajamento para contato10
Negócio para engajamento11
Engajamento para negócio12
Empresa matriz para empresa afiliada13
Empresa afiliada para empresa matriz14
Contato para ticket15
Ticket para contato16
Ticket para engajamento17
Engajamento para ticket18
Negócio para item de linha19
Item de linha para negócio20
Empresa para ticket25
Ticket para empresa26
Negócio para ticket27
Ticket para negócio28