No HubSpot, os contatos armazenam informações sobre as pessoas que interagem com os seus negócios. Os pontos de extremidade de contatos permitem controlar a criação e o gerenciamento de registros de contatos, bem como sincronizar os dados de contatos entre o HubSpot e outros sistemas.
Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia Noções básicas do CRM. Para obter informações mais gerais sobre objetos e registros no HubSpot, saiba como gerenciar seu banco de dados do CRM.
Para criar novos contatos, faça uma solicitação POST
para /crm/v3/objects/contacts
.
Na solicitação, inclua os dados do contato em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar seu novo contato a registros (por exemplo, empresas, negócios) ou atividades (por exemplo, reuniões, observações) existentes.
Os detalhes do contato são armazenados nas propriedades do contato. Existem propriedades de contato padrão do HubSpot, mas você também pode criar propriedades de contato personalizadas.
Ao criar uma nova empresa, você deve incluir pelo menos uma das seguintes propriedades na solicitação: email
, firstname
ou lastname
. É recomendado incluir sempre o email
, pois o endereço de e-mail é o principal identificador exclusivo para evitar contatos duplicados no HubSpot.
Para exibir todas as propriedades disponíveis, você pode recuperar uma lista das propriedades do contato da sua conta, fazendo uma solicitação GET
para /crm/v3/properties/contacts
. Saiba mais sobre a API de propriedades.
Observação: se você incluiu lifecyclestage
em sua solicitação, os valores devem se referir ao nome interno da fase do ciclo de vida. Os nomes internos das fases padrão são valores de texto e não mudam, mesmo se você editar o rótulo da fase (por exemplo, subscriber
ou marketingqualifiedlead
). Os nomes internos das fases personalizadas são valores numéricos. Você pode encontrar o ID interno de uma fase nas configurações de fase do ciclo de vida ou recuperando a propriedade de fase do ciclo de vida por meio da API.
Por exemplo, para criar um novo contato, a solicitação pode ser semelhante à seguinte:
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "(555) 555-5555",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
}
}
Ao criar um novo contato, você também pode associá-lo a registros ou atividades existentes, incluindo um objeto de associações. Por exemplo, para associar um novo contato a uma empresa e e-mail existentes, a solicitação seria parecida com a seguinte:
xxxxxxxxxx
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "(555) 555-5555",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
},
"associations": [
{
"to": {
"id": 123456
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 197
}
]
}
]
}
No objeto de associações, você deve incluir o seguinte:
Descrição | Parâmetro |
---|---|
to | O registro ou a atividade que você deseja associar ao contato especificado por seu valor de id exclusivo. |
types | O tipo de associação entre o contato e o registro/atividade. Inclua associationCategory e associationTypeId . Os IDs de tipo de associação padrão são listados aqui, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações. |
Você pode recuperar contatos individualmente ou em lotes.
- Para recuperar um contato individual, faça uma solicitação
GET
para/crm/v3/objects/contacts/{contactId} or``/crm/v3/objects/contacts/{email}?idProperty=email
. - Para solicitar uma lista de todos os contatos, faça uma solicitação
GET
para/crm/v3/objects/contacts
.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
Descrição | Parâmetro |
---|---|
properties | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o contato solicitado não tiver um valor para uma propriedade, ele não aparecerá na resposta. |
propertiesWithHistory | Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se o contato solicitado não tiver um valor para uma propriedade, ele não aparecerá na resposta. |
associations | Uma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações. |
- Para recuperar um lote de contatos específicos por ID de registo, endereço de e-mail ou uma propriedade de identificador exclusivo personalizada, faça uma solicitação POST
POST
paracrm/v3/objects/contacts/batch/read
. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a API de associações.
Para o ponto de extremidade de leitura em lote, você pode usar o parâmetro idProperty
opcional para recuperar contatos por email
ou uma propriedade de identificador exclusivo personalizada. Por padrão, os valores de id
na solicitação referem-se ao ID do registro (hs_object_id
); portanto, o parâmetro idProperty
não é necessário ao recuperar pelo ID do registro. Para utilizar email
ou uma propriedade de valor exclusivo personalizada para recuperar contatos, você deve incluir o parâmetroidProperty
.
Por exemplo, para recuperar um lote de contatos com base em valores de ID do registro, sua solicitação pode ser parecida com o seguinte (somente valores atuais ou valores atuais e do histórico):
xxxxxxxxxx
// Example request body with record ID (current values)
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"inputs": [
{
"id": "1234567"
},
{
"id": "987456"
}
]
}
xxxxxxxxxx
// Example request body with record ID (current and historical values)
{
"propertiesWithHistory": ["lifecyclestage", "hs_lead_status"],
"inputs": [
{
"id": "1234567"
},
{
"id": "987456"
}
]
}
Para recuperar contatos com base no endereço de e-mail ou uma propriedade de identificador exclusivo personalizada (por exemplo, um número de ID de cliente exclusivo para a sua empresa), a sua solicitação seria semelhante a:
xxxxxxxxxx
// Example request body with email address
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "email",
"inputs": [
{
"id": "lgilmore@thedragonfly.com"
},
{
"id": "sstjames@thedragonfly.com"
}
]
}
xxxxxxxxxx
// Example request body with a unique value property
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "internalcustomerid",
"inputs": [
{
"id": "12345"
},
{
"id": "67891"
}
]
}
Você pode atualizar contatos individualmente ou em massa.
Para atualizar contatos individuais, você pode usar o ID de registro (id
) ou o endereço de e-mail do contato (email
).
- Para atualizar um contato individual por seu ID de registro, faça uma solicitação
PATCH
para/crm/v3/objects/contacts/{contactId}
e inclua os dados que deseja atualizar. - Para atualizar um contato individual por seu e-mail, faça uma solicitação
PATCH
para/crm/v3/objects/contacts/{email}?idProperty=email
e inclua os dados que deseja atualizar.
Por exemplo:
xxxxxxxxxx
// Example request body with record ID
// PATCH /crm/v3/objects/contacts/123456789
{
"properties": {
"favorite_food": "burger",
"jobtitle": "Manager",
"lifecyclestage": "Customer"
}
}
Observe: se atualizar a propriedade lifecyclestage
, você só pode definir o valor avançar na ordem do estágio. Para definir o estágio do ciclo de vida para trás, primeiro você precisa limpar o valor do estágio do ciclo de vida existente do registro. O valor pode ser apagado manualmente ou automaticamente por meio de um fluxo de trabalho ou de uma integração que sincroniza os dados do contato.
Para atualizar contatos em lotes, você pode usar os valores de ID de registro dos contatos (id
). Para atualizar vários contatos, faça uma solicitação POST
para /crm/v3/objects/contacts/batch/update
. No corpo da solicitação, inclua o ID de registro de cada contato como id
e inclua as propriedades que deseja atualizar.
Por exemplo:
xxxxxxxxxx
// Example request body
// POST /crm/v3/objects/contacts/batch/update
{
"inputs": [
{
"id": "123456789",
"properties": {
"favorite_food": "burger"
}
},
{
"id": "56789123",
"properties": {
"favorite_food": "Donut"
}
}
]
}
Você também pode criar e atualizar contatos em lote ao mesmo tempo usando o ponto de extremidade upsert. Para este endpoint, você pode usar email
ou uma propriedade de identificador exclusivo personalizado. Após a solicitação, se os contatos já existirem, eles serão atualizados e, se não existirem, eles serão criados.
Para inserir contatos, faça um pedido POST
para /crm/v3/objects/contacts/batch/upsert
. No corpo da sua solicitação, inclua o parâmetro idProperty
para identificar se você está usando email
ou uma propriedade de identificador exclusivo personalizado. Inclua o valor dessa propriedade como id
e adicione as outras propriedades que você deseja definir ou atualizar.
Por exemplo, sua solicitação poderia ser semelhante a esta:
xxxxxxxxxx
// Example request body with email
// POST /crm/v3/objects/contacts/batch/upsert
{
"inputs": [
{
"properties": {
"phone": "5555555555"
},
"id": "test@test.com",
"idProperty": "email"
},
{
"properties": {
"phone": "7777777777"
},
"id": "example@hubspot.com",
"idProperty": "email"
}
]
}
Para associar um contato a outros registros do CRM ou a uma atividade, faça uma solicitação PUT
para /crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
Para recuperar o valor associationTypeId
, consulte esta lista de valores padrão ou envie uma solicitação GET
para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
.
Saiba mais sobre a API de associações.
Para remover uma associação entre um contato e um registro ou uma atividade, faça uma solicitação DELETE
para o seguinte URL: /crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}
.
Você pode fixar uma atividade em um registro de empresa por meio da API, incluindo o campo hs_pinned_engagement_id
na sua solicitação. No campo, inclua o id
da atividade a ser fixada, que pode ser recuperado por meio das APIs de engajamentos. Você pode fixar uma atividade por registro. No entanto, a atividade já deve estar associada ao contato antes da fixação.
Para definir ou atualizar a atividade fixada de um contato, sua solicitação pode ser parecida com o seguinte:
xxxxxxxxxx
// Example request body PATCH /crm/v3/objects/contacts/{contactId}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
Você também pode criar um contato, associá-lo a uma atividade existente e fixar a atividade na mesma solicitação. Por exemplo:
xxxxxxxxxx
// Example request body POST /crm/v3/objects/contacts
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "(555) 555-5555",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 201
}
]
}
]
}
Você pode excluir contatos individualmente ou em massa, o que adicionará o contato à lixeira no HubSpot. Posteriormente, você pode restaurar o contato no HubSpot.
Para excluir um contato individual por seu ID, faça uma solicitaçãoDELETE
para /crm/v3/objects/contacts/{contactId}
.
Saiba mais sobre exclusão de contatos em lote na documentação de referência.
Endereços de e-mail secundários são usados quando um contato tem mais de um e-mail. E-mails adicionais ainda são identificadores exclusivos para contatos, portanto, vários contatos não podem ter o mesmo endereço de e-mail secundário.
- Para visualizar e-mails secundários para contatos, ao recuperar todos ou contatos individuais, inclua o parâmetro
properties
com as propriedadesemail
e **hs_additional_emails
. ** O endereço de e-mail principal de um contato será exibido no campoemail
e e-mails adicionais serão exibidos nohs_additional_emails
campo. - Para adicionar e-mails secundários a um contato, ao criar ou editar o contato, no corpo da solicitação, inclua e-mails no campo
hs_additional_emails
. Vários e-mails podem ser separados por ponto e vírgula.
Se você estiver usando as APIs de contato V1, aprenda a usar os endpoints de e-mail secundários neste guia de referência.
As operações em lote são limitadas a 100 registros por vez. Por exemplo, não é possível atualizar em lote mais de 100 contatos em uma solicitação. Há também limites para contatos e envios de formulários.