Contatos

Visão geralEndpoints

No HubSpot, os contatos armazenam informações sobre as pessoas que interagem com os seus negócios. Os endpoints 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.

Criar contatos

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.

Propriedades

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 um novo contato, você deve incluir pelo menos uma das seguintes propriedades na solicitação: email, firstname ou lastname. É recomendável incluir sempre o e-mail, 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 de 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" } }

Associações

Ao criar um novo contato, você também pode associá-lo a registros ou atividades existentes. No objeto de associações, inclua os seguintes campos:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

O ID do registro ou da atividade com o qual você deseja associar o contato.

associationTypeId

Um identificador exclusivo para indicar o tipo de associação entre o contato e o outro objeto ou atividade. Os tipos de associação padrão estão listados aqui, ou você pode recuperar o valor fazendo uma solicitação GET para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. Saiba mais sobre a API de associações.

Você também pode incluir o campo label para atribuir um rótulo de associação definido que descreve a associação. Saiba mais sobre como associar registros por meio da API 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:

///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 } ] }] }

Recuperar contatos

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}. 
  • Para solicitar uma lista de todos os contatos, faça uma solicitação GET para /crm/v3/objects/contacts.

Para ambos os endpoints, você pode incluir os seguintes parâmetros de consulta no URL da solicitação: 

Use this table to describe parameters / fields
ParameterDescription
propriedades

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 será exibido na resposta.

associações

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 o endpoint 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):

///Example request body with record ID (current values) { "properties": [ "email", "lifecyclestage", "jobtitle" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }
///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:

///Example request body with email { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "email", "inputs": [ { "id": "lgilmore@thedragonfly.com" }, { "id": "sstjames@thedragonfly.com" } ] }
///Example request body with a unique value property { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "internalcustomerid", "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Atualizar contatos

Você pode atualizar contatos individualmente ou em massa. Para contatos existentes, o e-mail e o ID do registro são valores exclusivos; portanto, você pode usar o id ou o e-mail para atualizar contatos por meio da API.

Para atualizar um contato individual por seu ID de contato, faça uma solicitação PATCH para /crm/v3/objects/contacts/{contactId} e inclua os dados que deseja atualizar.

Associar contatos existentes a registros ou atividades

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 faça uma solicitação GET para /crm/v4/associations/{fromObjectType}/{toObjectType}/labels. 

Saiba mais sobre a API de associações.

Remover uma associação

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

Fixar uma atividade em um registro de contato

You can pin an activity on a contact record by including the hs_pinned_engagement_id field in your request. In the field, include the id of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.

To set or update a contact's pinned activity, your request could look like:

///Example request body PATCH /crm/v3/objects/contacts/{contactId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:

///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 }] }] }

Delete contacts

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ção DELETE para /crm/v3/objects/contacts/{contactId}.

Saiba mais sobre a exclusão em massa de contatos na guia Endpoints na parte superior deste artigo.

Limites

Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..