Ignorar e ir ao conteúdo principal

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.

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.

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.

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:

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.

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.

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.

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:

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.

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:

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

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:

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

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.

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.

ID DE TIPOTipo de associação
449Contato para contato
279Contato para empresa
1Contato para empresa (Principal)
4Contato para negócio
15Contato para ticket
193Contato para chamada
197Contato para e-mail
199Contato para reunião
201Contato para observação
203Contato para tarefa
82Contato para comunicação (SMS, WhatsApp ou mensagem do LinkedIn)
454Contato para correio postal
587Contato para carrinho
508Contato para pedido
178Contato para fatura
388Contato para pagamento
296Contato para assinatura
ID DE TIPOTipo de associação
450Empresa para empresa
14Empresa afiliada para empresa matriz
13Empresa matriz para afiliada
280Empresa para contato
2Empresa para contato (Principal)
342Empresa para negócio
6Empresa para negócio (Principal)
340Empresa para ticket
25Empresa para ticket (Principal)
181Empresa para chamada
185Empresa para e-mail
187Empresa para reunião
189Empresa para observação
191Empresa para tarefa
88Empresa para comunicação (SMS, WhatsApp ou mensagem do LinkedIn)
460Empresa para correio postal
180Empresa para fatura
510Empresa para pedido
390Empresa para pagamento
298Empresa para assinatura
ID DE TIPOTipo de associação
451Negócio para negócio
3Negócio para contato
341Negócio para empresa
5Negócio para empresa (Principal)
27Negócios para ticket
205Negócio para chamada
209Negócio para e-mail
211Negócio para reunião
213Negócio para observação
215Negócio para tarefa
86Negócio para comunicação (SMS, WhatsApp ou mensagem do LinkedIn)
458Negócio para correio postal
313Negócio para divisão de negócio
19Negócio para item de linha
176Negócio para fatura
511Negócio para pedido
392Negócio para pagamento
630Negócio para produto
63Negócio para orçamento
300Negócio para assinatura
ID DE TIPOTipo de associação
452Ticket para ticket
16Ticket para contato
339Empresa para ticket
26Ticket para empresa (Principal)
28Ticket para negócio
219Ticket para chamada
223Ticket para e-mail
225Ticket para reunião
227Ticket para observação
229Ticket para tarefa
84Ticket para comunicação (SMS, WhatsApp ou mensagem do LinkedIn)
456Ticket para correio postal
32Ticket para thread
278Ticket para conversa
526Ticket para pedido
ID DE TIPOTipo de associação
578Lead para contato principal
596Lead para chamada
598Lead para e-mail
600Lead para reunião
602Lead para comunicação
608Lead para contato
610Lead para empresa
646Lead para tarefa
ID DE TIPOTipo de associação
194Chamada para contato
182Chamada para empresa
206Chamada para negócio
220Chamada para ticket
ID DE TIPOTipo de associação
198E-mail para contato
186E-mail para empresa
210E-mail para negócio
224E-mail para ticket
ID DE TIPOTipo de associação
200Reunião para contato
188Reunião para empresa
212Reunião para negócio
226Reunião para ticket
ID DE TIPOTipo de associação
202Observação para contato
190Observação para empresa
214Observação para negócio
228Observação para ticket
ID DE TIPOTipo de associação
453Correio postal para contato
459Correio postal para empresa
457Correio postal para negócio
455Correio postal para ticket
ID DE TIPOTipo de associação
69Orçamento para contato
71Orçamento para empresa
64Orçamento para negócio
67Orçamento para item de linha
286Orçamento para modelo de orçamento
362Orçamento para desconto
364Orçamento para taxa
366Orçamento para imposto
702Signatário do contato (para assinaturas eletrônicas)
733Orçamento para carrinho
408Orçamento para fatura
731Orçamento para pedido
398Orçamento para pagamento
304Orçamento para assinatura
ID DE TIPOTipo de associação
204Tarefa para contato
192Tarefa para empresa
216Tarefa para negócio
230Tarefa para ticket
ID DE TIPOTipo de associação
81Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para contato
87Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para empresa
85Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para negócio
83Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para ticket
ID DE TIPOTipo de associação
593Pedido para carrinho
507Pedido para contato
509Pedido para empresa
512Pedido para negócio
519Pedido para desconto
521Pedido para código de desconto
518Pedido para fatura
513Pedido para item de linha
523Pedido para pagamento
730Pedido para orçamento
516Pedido para assinatura
726Pedido para tarefa
525Pedido para ticket
ID DE TIPOTipo de associação
586Carrinho para contato
588Carrinho para desconto
590Carrinho para item de linha
592Carrinho para objeto
732Carrinho para orçamento
728Carrinho para tarefa
594Carrinho para ticket

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