> ## Documentation Index
> Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API do CRM | Contatos
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requer um dos seguintes escopos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
# Contatos
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](/docs/guides/crm/understanding-the-crm). Para obter informações mais gerais sobre objetos e registros no HubSpot,[ saiba como gerenciar seu banco de dados do CRM](http://knowledge.hubspot.com/contacts-user-guide).
## 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](https://knowledge.hubspot.com/pt/properties/hubspots-default-contact-properties), mas você também pode [criar propriedades de contato personalizadas](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties).
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](https://knowledge.hubspot.com/pt/records/deduplication-of-records#automatic-deduplication-in-hubspot) 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](/docs/api-reference/crm-properties-v3/guide).
### 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](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties) da fase (por exemplo, `subscriber` ou `marketingqualifiedlead`). Os nomes internos das [fases personalizadas](https://knowledge.hubspot.com/pt/object-settings/create-and-customize-lifecycle-stages) são valores numéricos. Você pode encontrar o ID interno de uma fase nas [configurações de fase do ciclo de vida](https://knowledge.hubspot.com/pt/object-settings/create-and-customize-lifecycle-stages) 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:
```json theme={null}
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
}
}
```
### Associações
Ao criar um novo contato, você também pode associá-lo a [registros](https://knowledge.hubspot.com/pt/records/associate-records) ou [atividades existentes](https://knowledge.hubspot.com/pt/records/associate-activities-with-records), 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:
```json theme={null}
///Example request body
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"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:
| Parâmetro | Descrição |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](/docs/api-reference/crm-associations-v4/guide#association-type-id-values), ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da [API de associações](/docs/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## Recuperar contatos por ID de registro, e-mail ou propriedade de valor exclusivo personalizada
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:
| Parâmetro | Descrição |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.](/docs/api-reference/crm-associations-v4/guide) |
* Para recuperar um lote de contatos específicos por ID de registo, endereço de e-mail ou uma [propriedade de identificador exclusivo personalizada](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties), faça uma solicitação POST`POST` para `crm/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](/docs/api-reference/crm-associations-v4/guide).
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](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties) 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âmetro`idProperty`.
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):
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"inputs": [
{
"id": "1234567"
},
{
"id": "987456"
}
]
}
```
```json theme={null}
{
"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:
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "email",
"inputs": [
{
"id": "lgilmore@thedragonfly.com"
},
{
"id": "sstjames@thedragonfly.com"
}
]
}
```
```json theme={null}
{
"properties": ["email", "lifecyclestage", "jobtitle"],
"idProperty": "internalcustomerid",
"inputs": [
{
"id": "12345"
},
{
"id": "67891"
}
]
}
```
## Atualizar contatos
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:
```json theme={null}
{
"properties": {
"favorite_food": "burger",
"jobtitle": "Manager",
"lifecyclestage": "Customer"
}
}
```
### Observação:
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](https://knowledge.hubspot.com/pt/records/update-a-property-value-for-a-record) ou automaticamente por meio de um[ fluxo de trabalho](https://knowledge.hubspot.com/pt/records/change-record-lifecycle-stages-in-bulk) 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:
```json theme={null}
{
"inputs": [
{
"id": "123456789",
"properties": {
"favorite_food": "burger"
}
},
{
"id": "56789123",
"properties": {
"favorite_food": "Donut"
}
}
]
}
```
## Inserir contatos
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](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties). 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.
### Observação:
Não há suporte para upserts parciais ao usar `email` como a `idProperty` para contatos. Para concluir uma substituição parcial, use uma propriedade de identificador exclusivo personalizada como `idProperty` em vez disso.
Por exemplo, sua solicitação poderia ser semelhante a esta:
```json theme={null}
{
"inputs": [
{
"properties": {
"phone": "+18884827768"
},
"id": "test@test.com",
"idProperty": "email"
},
{
"properties": {
"phone": "+18888888888"
},
"id": "example@hubspot.com",
"idProperty": "email"
}
]
}
```
## 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](/docs/api-reference/crm-associations-v4/guide#association-type-id-values) 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.](/docs/api-reference/crm-associations-v4/guide)
### 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
Você pode [fixar uma atividade](https://knowledge.hubspot.com/pt/records/pin-an-activity-on-a-record) 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](/docs/api-reference/overview). 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:
```json theme={null}
{
"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:
```json theme={null}
{
"properties": {
"email": "example@hubspot.com",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 201
}
]
}
]
}
```
## Excluir contatos
Você pode excluir contatos individualmente ou em massa, o que adicionará o contato à lixeira no HubSpot. Posteriormente, você pode[ restaurar o contato no HubSpot](https://knowledge.hubspot.com/pt/records/restore-deleted-records).
Para excluir um contato individual por seu ID, faça uma solicitação`DELETE` para `/crm/v3/objects/contacts/{contactId}`.
Saiba mais sobre exclusão de contatos em lote na [documentação de referência](/docs/api-reference/crm-contacts-v3/guide).
## E-mails adicionais
Endereços de e-mail adicionais são usados quando um contato tem mais de um e-mail. Estes podem ser adicionados [manualmente em um registro do contato na HubSpot](https://knowledge.hubspot.com/pt/records/add-multiple-email-addresses-to-a-contact) ou podem ser adicionados automaticamente após uma [Mesclagem de contato](https://knowledge.hubspot.com/pt/records/merge-records#contact-merge-exceptions). E-mails adicionais ainda são identificadores exclusivos para contatos, portanto, vários contatos não podem ter os mesmos endereços de e-mail adicionais.
Para visualizar e-mails adicionais para contatos, ao recuperar todos ou contatos individuais, inclua o parâmetro `properties` com as propriedades `email` e `hs_additional_emails`. O endereço de e-mail principal de um contato será exibido no campo `email` e e-mails adicionais serão exibidos no `hs_additional_emails` campo.
## Limites
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](https://br.developers.hubspot.com/docs#limits_contacts).