Compreendendo as APIs de CRM
O CRM da HubSpot é um sistema para gerenciar relacionamentos e dados do cliente. Saiba mais sobre objetos de CRM e as APIs de CRM relacionadas.
Última modificação: 22 de agosto de 2025
A base da sua conta da HubSpot é um banco de dados dos seus relacionamentos e processos de negócios, denominado CRM (Gerenciamento de relacionamento com o cliente). Para gerenciar esses dados, as contas da HubSpot incluem objetos, que representam tipos de relacionamentos ou processos. As instâncias individuais de objetos, chamadas de registros, representam as entidades individuais sob cada tipo de objeto (por exemplo, John Smith é um contato). Para armazenar dados em cada registro, você usará propriedades (por exemplo, a propriedade de e-mail) e, para representar as relações entre entidades individuais, você poderá associar registros entre si (por exemplo, associar John Smith a uma empresa Smith & Co.) Além disso, os registros do CRM também podem armazenar informações sobre interações por meio de engajamentos/atividades associados, como e-mails, chamadas e reuniões. Abaixo, aprenda sobre objetos, registros, propriedades, associações, pipelines e pesquisas no CRM. Para saber mais sobre como gerenciar seu banco de dados de CRM no HubSpot, confira a Central de Conhecimento da HubSpot.
APIs de objetos
As APIs de objetos fornecem acesso a registros e atividades. Para objetos suportados, você pode usar pontos de extremidade de objeto e substituir{objectTypeId} na URL de solicitação com o objeto desejado. Por exemplo, para criar contatos, você faria uma POST solicitação para crm/v3/objects/0-1 e para criar cursos, a solicitação seria crm/v3/objects/0-410. Consulte este artigo para obter mais informações sobre o uso de endpoints de objeto para vários objetos.
Observação:
Alguns objetos têm funcionalidade de API limitada. Para mais detalhes, clique no link para a documentação de referência dos pontos de extremidade de um objeto na tabela abaixo. Se um objeto listado não tiver seu próprio documento, você pode consultar o objetos da API doc e substitua o{objectTypeId} em cada ponto final para o objeto desejado.IDs de tipo de objeto
Ao usar CRM e outras APIs, você precisará usar o campoobjectTypeId, que é um valor numérico exclusivo atribuído a cada objeto. Por exemplo, para recuperar registros, você faria um pedido GET para /crm/v3/objects/{objectTypeId}, ou ao criar uma propriedade para um objeto, você faria um POST pedido para /crm/v3/properties/{objectTypeId}Os valores de ID do tipo de objeto estão listados na tabela abaixo:
| Tipo de ID | Objeto | Descrição |
|---|---|---|
0-2 | Empresas | Armazena informações sobre uma empresa ou organização. Veja a API de empresas |
0-1 | Contatos | : armazenam informações sobre uma única pessoa. Veja a API de contatos |
0-3 | Negócios | Representam oportunidades de vendas e transações, rastreadas por estágios do pipeline. Veja a API de negócios |
0-5 | Tickets | Representam solicitações de ajuda ou suporte do cliente, rastreadas por meio de status de pipeline. Veja a API de tickets |
0-421 | Compromissos | Representam encontros ou serviços agendados para um indivíduo. Veja a API de objetos |
0-48 | Chamadas | Um tipo de atividade que representa interações telefônicas associadas aos seus registros. Veja a API de chamadas |
0-18 | Comunicações | Um tipo de atividade que representa interações de mensagens SMS, LinkedIn e WhatsApp associadas aos seus registros. Veja a API de comunicações |
0-410 | Cursos | Representam programas estruturados ou séries de lições, treinamentos ou módulos educacionais. Veja a API de objetos |
2-XXX | Objetos personalizados | Armazenam dados que não se encaixam nos objetos existentes. Para encontrar o objectTypeId para um objeto personalizado, faça um pedido GET para /crm/v3/schemas. Veja a API de objetos |
0-49 | E-mails | Um tipo de atividade que representa interações de e-mail individuais associadas aos seus registros. Veja a API de e-mail |
0-19 | Envios de feedback | Armazena informações enviadas para uma pesquisa de feedback. Os envios de feedback são associados aos registros de contatos. Veja a API de envio de feedback |
0-53 | Faturas | Representam as faturas enviadas para transações de vendas. As faturas podem ser associadas a contatos, empresas, negócios, itens de linha, descontos, impostos e taxas. Veja a API de faturas |
0-136 | Leads | Representam clientes em potencial que demonstraram interesse em seus produtos ou serviços. Veja a API de leads |
0-8 | Itens de linha | : representam produtos e serviços individuais vendidos em um negócio. Os itens de linha podem ser criados de produtos existentes na sua biblioteca de produtos ou como itens independentes. Veja a API de itens de linha |
0-420 | Listagens | Representam propriedades ou unidades a serem compradas, vendidas ou alugadas. Veja a API de objetos |
0-54 | Eventos de marketing | Representam eventos relacionados aos seus esforços de marketing, incluindo especificamente eventos de integrações conectadas. Você pode especificar se um contato compareceu, se registrou ou cancelou a participação em um evento de marketing. Veja a API de eventos de marketing |
0-47 | Reuniões | Um tipo de atividade que representa interações de reunião associadas aos seus registros. Veja a API de reuniões |
0-46 | Notas | Um tipo de atividade que representa notas associadas aos seus registros. Veja a API de notas |
0-123 | Pedidos | Representam compras de comércio eletrônico na HubSpot. Veja a API de pedidos |
0-101 | Pagamentos | Os pagamentos feitos pelos compradores por meio de faturas, links de pagamento e orçamentos. Os pagamentos podem ser associados a contatos, empresas, negócios, faturas, orçamentos, itens de linha, assinaturas, descontos, impostos e taxas. Veja a API de pagamentos |
0-116 | Caixa de e-mails | Um tipo de atividade que representa interações de correio físico associadas aos seus registros. Veja a API de caixa de e-mails |
0-7 | Produtos | Representam mercadorias ou serviços para venda. Os produtos não podem ser associados a outros objetos, mas você pode criar itens de linha com base em produtos e associá-los a negócios e orçamentos. Veja a API de produtos |
0-14 | Orçamentos | Representam as informações de preços compartilhadas com potenciais compradores. As cotações devem ser associadas a um negócio, item de linha e cotação (0-64), mas também podem ser associadas a contatos, empresas, descontos, taxas e impostos. Veja a API de orçamentos |
0-162 | Serviços | Representam ofertas intangíveis fornecidas aos clientes. Exemplos incluem integração e consultoria, reparos e manutenção e cuidados pessoais. Veja a API de objetos |
0-69 | Assinaturas | Representam pagamentos recorrentes programados por meio de links de pagamento e cotações. As faturas podem ser associadas a contatos, empresas, negócios, orçamentos, itens de linha, pagamentos, descontos, impostos e taxas. Veja a API de assinaturas |
0-27 | Tarefas | Um tipo de atividade que representa tarefas associadas aos seus registros. Veja a API de tarefas |
0-115 | Usuários | Representam os usuários na sua conta da HubSpot. Os usuários não podem ser associados a outros objetos, mas podem ser recuperados e atualizados via API. Veja a API de detalhes do usuário |
- Ao iniciar uma importação com a API de importações, o
columnObjectTypeIdespecifica a qual objeto pertencem os dados em seu arquivo. Para importar dados de contatos, seu valor paracolumnObjectTypeIdpode sercontactou0-1. - Ao usar a API de associações, os valores
fromObjectTypeetoObjectTypeespecificam os objetos e a direção da associação. Para exibir os tipos de associação de contatos para empresas, seu URL de solicitaçãoGETpode sercrm/v4/associations/contact/company/labelsoucrm/v4/associations/0-1/0-2/labels.
Identificadores exclusivos e IDs de registro
Um identificador exclusivo é um valor que diferencia um registro em um CRM de outro, mesmo que eles tenham informações idênticas. Por exemplo, no banco pode haver registros de duas pessoas com o nome John Smith. Para evitar o envio acidental de dinheiro para o John Smith errado, cada registro recebe um número como seu ID do registro. Quando um registro é criado na HubSpot, seu ID do registro (hs_object_id) é gerado automaticamente e deve ser tratado como uma string. Os IDs de registro são exclusivos dentro de um objeto, portanto, pode haver um contato e uma empresa com o mesmo ID. Para contatos e empresas, há identificadores exclusivos adicionais, incluindo o email de um contato e o nome de domain de uma empresa. Você também pode criar propriedades de identificador exclusivas personalizadas.
Nas APIs de CRM, você usará valores de identificadores exclusivos para identificar e gerenciar registros específicos. Você sempre pode usar um registro hs_object_id valor, mas também pode usar propriedades de identificador exclusivo personalizadas para determinados pontos de extremidade, especificados pelo idProperty parâmetro. Por exemplo, para editar um contato, você pode fazer um PATCH pedido para /crm/v3/objects/0-1/{contactId} ou /crm/v3/objects/0-1/{contactEmail}?idProperty=email. Saiba mais sobre como o HubSpot lida com a desduplicação no Base de conhecimento.
API de associações
Na HubSpot, você pode mostrar como os objetos estão relacionados entre si associando seus registros. Por exemplo, você pode associar vários contatos a uma empresa e, em seguida, associar a empresa e os respectivos contatos a um negócio. Ao usar os endpoints de API de associações, você pode substituir objetos por{toObjectTypeId} e {fromObjectTypeId} nos URLs e corpos de solicitação. Antes de associar registros entre objetos, para entender quais objetos podem ser associados uns aos outros, você pode recuperar tipos de associação. Por exemplo, contatos podem ser associados à maioria dos objetos, enquanto faturas só podem ser associadas a contatos, empresas, negócios, itens de linha, descontos, taxas e impostos. Dependendo da sua assinatura, você pode descrever os tipos de relacionamento específicos entre registros usando rótulos de associação, e sua conta pode ter objetos personalizados adicionais, que podem ser associados a outros objetos padrão. Saiba mais sobre relações entre objetos e gerenciamento de associações usando os pontos de extremidade de associações.
Se você tiver acesso a uma conta da HubSpot, poderá revisar as relações entre objetos exclusivos da sua conta, acessando a ferramenta de modelo de dados.
API de propriedades
As informações sobre registros são armazenadas em campos chamados de propriedades, que são então organizados em grupos. O HubSpot fornece um conjunto de propriedades padrão para cada objeto. Além de cada propriedade padrão do objeto, você pode armazenar dados personalizados criando propriedades personalizadas. Ao usar a API de propriedades, você pode substituir objetos nos endpoints para criar e gerenciar as propriedades de um objeto. Por exemplo,/crm/v3/properties/0-1 para propriedades de contato ou /crm/v3/properties/0-5 para propriedades de tickets. Saiba mais sobre como usar a API de propriedades neste artigo.
API de pesquisa
Para filtrar e classificar registros e atividades com base em suas propriedades e associações, você pode usar a API de pesquisa. Ao usar os pontos de extremidade de pesquisa, substitua o valor{objectTypeId} para o objeto no qual você deseja pesquisar. Por exemplo, para pesquisar chamadas, você faria uma solicitação POST para /crm/v3/objects/0-48/search. Saiba mais sobre como usar a API de pesquisa do CRM neste artigo.