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.
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:
///Example request body - Single label
{
"label": "Partner",
"name": "partner"
}
xxxxxxxxxx
///Example request body - Paired labels
{
"label": "Manager",
"inverseLabel": "Employee",
"name": "manager_employee"
}
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.
Observação: o número de associações que um registro pode ter depende do objeto e da sua assinatura do HubSpot.
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:
xxxxxxxxxx
/// Example request body
[
{
"associationCategory": "USER_DEFINED",
"associationTypeId": 36
}
]
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
paracrm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create
. - Para atualizar os limites existentes, faça uma solicitação
POST
paracrm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update
.
No corpo da solicitação, inclua inputs
com o seguinte:
Descrição | Parâmetro |
---|---|
category | A categoria da associação para a qual você está definindo um limite HUBSPOT_DEFINED ou USER_DEFINED . |
typeId | O 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. |
maxToObjectIds | O 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:
xxxxxxxxxx
//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
}
]
}
- 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:
xxxxxxxxxx
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
"results": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"userEnforcedMaxToObjectIds": 5,
"label": null
}
]
}
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:
xxxxxxxxxx
//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).
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.
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.
ID DE TIPO | Tipo de associação |
---|---|
449 | Contato para contato |
279 | Contato para empresa |
1 | Contato para empresa (Principal) |
4 | Contato para negócio |
15 | Contato para ticket |
193 | Contato para chamada |
197 | Contato para e-mail |
199 | Contato para reunião |
201 | Contato para observação |
203 | Contato para tarefa |
82 | Contato para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
454 | Contato para correio postal |
587 | Contato para carrinho |
508 | Contato para pedido |
178 | Contato para fatura |
388 | Contato para pagamento |
296 | Contato para assinatura |
ID DE TIPO | Tipo de associação |
---|---|
450 | Empresa para empresa |
14 | Empresa afiliada para empresa matriz |
13 | Empresa matriz para afiliada |
280 | Empresa para contato |
2 | Empresa para contato (Principal) |
342 | Empresa para negócio |
6 | Empresa para negócio (Principal) |
340 | Empresa para ticket |
25 | Empresa para ticket (Principal) |
181 | Empresa para chamada |
185 | Empresa para e-mail |
187 | Empresa para reunião |
189 | Empresa para observação |
191 | Empresa para tarefa |
88 | Empresa para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
460 | Empresa para correio postal |
180 | Empresa para fatura |
510 | Empresa para pedido |
390 | Empresa para pagamento |
298 | Empresa para assinatura |
ID DE TIPO | Tipo de associação |
---|---|
451 | Negócio para negócio |
3 | Negócio para contato |
341 | Negócio para empresa |
5 | Negócio para empresa (Principal) |
27 | Negócios para ticket |
205 | Negócio para chamada |
209 | Negócio para e-mail |
211 | Negócio para reunião |
213 | Negócio para observação |
215 | Negócio para tarefa |
86 | Negócio para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
458 | Negócio para correio postal |
313 | Negócio para divisão de negócio |
19 | Negócio para item de linha |
176 | Negócio para fatura |
511 | Negócio para pedido |
392 | Negócio para pagamento |
630 | Negócio para produto |
63 | Negócio para orçamento |
300 | Negócio para assinatura |
ID DE TIPO | Tipo de associação |
---|---|
452 | Ticket para ticket |
16 | Ticket para contato |
339 | Empresa para ticket |
26 | Ticket para empresa (Principal) |
28 | Ticket para negócio |
219 | Ticket para chamada |
223 | Ticket para e-mail |
225 | Ticket para reunião |
227 | Ticket para observação |
229 | Ticket para tarefa |
84 | Ticket para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
456 | Ticket para correio postal |
32 | Ticket para thread |
278 | Ticket para conversa |
526 | Ticket para pedido |
ID DE TIPO | Tipo de associação |
---|---|
578 | Lead para contato principal |
596 | Lead para chamada |
598 | Lead para e-mail |
600 | Lead para reunião |
602 | Lead para comunicação |
608 | Lead para contato |
610 | Lead para empresa |
646 | Lead para tarefa |
ID DE TIPO | Tipo de associação |
---|---|
194 | Chamada para contato |
182 | Chamada para empresa |
206 | Chamada para negócio |
220 | Chamada para ticket |
ID DE TIPO | Tipo de associação |
---|---|
198 | E-mail para contato |
186 | E-mail para empresa |
210 | E-mail para negócio |
224 | E-mail para ticket |
ID DE TIPO | Tipo de associação |
---|---|
200 | Reunião para contato |
188 | Reunião para empresa |
212 | Reunião para negócio |
226 | Reunião para ticket |
ID DE TIPO | Tipo de associação |
---|---|
202 | Observação para contato |
190 | Observação para empresa |
214 | Observação para negócio |
228 | Observação para ticket |
ID DE TIPO | Tipo de associação |
---|---|
453 | Correio postal para contato |
459 | Correio postal para empresa |
457 | Correio postal para negócio |
455 | Correio postal para ticket |
ID DE TIPO | Tipo de associação |
---|---|
69 | Orçamento para contato |
71 | Orçamento para empresa |
64 | Orçamento para negócio |
67 | Orçamento para item de linha |
286 | Orçamento para modelo de orçamento |
362 | Orçamento para desconto |
364 | Orçamento para taxa |
366 | Orçamento para imposto |
702 | Signatário do contato (para assinaturas eletrônicas) |
733 | Orçamento para carrinho |
408 | Orçamento para fatura |
731 | Orçamento para pedido |
398 | Orçamento para pagamento |
304 | Orçamento para assinatura |
ID DE TIPO | Tipo de associação |
---|---|
204 | Tarefa para contato |
192 | Tarefa para empresa |
216 | Tarefa para negócio |
230 | Tarefa para ticket |
ID DE TIPO | Tipo de associação |
---|---|
81 | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para contato |
87 | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para empresa |
85 | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para negócio |
83 | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para ticket |
ID DE TIPO | Tipo de associação |
---|---|
593 | Pedido para carrinho |
507 | Pedido para contato |
509 | Pedido para empresa |
512 | Pedido para negócio |
519 | Pedido para desconto |
521 | Pedido para código de desconto |
518 | Pedido para fatura |
513 | Pedido para item de linha |
523 | Pedido para pagamento |
730 | Pedido para orçamento |
516 | Pedido para assinatura |
726 | Pedido para tarefa |
525 | Pedido para ticket |
ID DE TIPO | Tipo de associação |
---|---|
586 | Carrinho para contato |
588 | Carrinho para desconto |
590 | Carrinho para item de linha |
592 | Carrinho para objeto |
732 | Carrinho para orçamento |
728 | Carrinho para tarefa |
594 | Carrinho 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ção | ID |
---|---|
Contato para empresa | 1 |
Empresa para contato (padrão) | 2 |
Empresa para contato (todos os rótulos) | 280 |
Negócio para contato | 3 |
Contato para negócio | 4 |
Negócio para empresa | 5 |
Empresa para negócio | 6 |
Empresa para engajamento | 7 |
Engajamento para empresa | 8 |
Contato para engajamento | 9 |
Engajamento para contato | 10 |
Negócio para engajamento | 11 |
Engajamento para negócio | 12 |
Empresa matriz para empresa afiliada | 13 |
Empresa afiliada para empresa matriz | 14 |
Contato para ticket | 15 |
Ticket para contato | 16 |
Ticket para engajamento | 17 |
Engajamento para ticket | 18 |
Negócio para item de linha | 19 |
Item de linha para negócio | 20 |
Empresa para ticket | 25 |
Ticket para empresa | 26 |
Negócio para ticket | 27 |
Ticket para negócio | 28 |