Última modificação: 22 de agosto de 2025

Run in Postman

 Você pode registrar observações em registros do CRM para adicionar informações à linha do tempo do registro ou associar um anexo a um registro. Por exemplo, se você precisar acompanhar uma conversa offline que teve com um contato, poderá adicionar uma observação ao registro do contato com detalhes e documentos relacionados à conversa. Outros usuários na conta poderão visualizar e referenciar essa observação. Você pode gerenciar observações no HubSpot ou por meio da API de observações. Abaixo, aprenda os métodos básicos de gerenciamento de observações por meio da API. Você pode revisar todos os endpoints disponíveis na documentação de referência.

​
Criar uma observação

Para criar uma observação, envie uma solicitação POST para /crm/v3/objects/notes. No corpo da solicitação, adicione detalhes da observação em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar sua nova observação a um registro existente (por exemplo, contatos, empresas).

​
Propriedades

No objeto de propriedades, você pode incluir os seguintes campos:
CampoDescrição
hs_timestampObrigatório. Este campo marca a hora de criação da observação e determina onde ela se encontra na linha do tempo do registro. Você pode usar um carimbo de data e hora do Unix em milissegundos ou no formato UTC.
hs_note_bodyO conteúdo de texto da observação, limitado a 65.536 caracteres.
hubspot_owner_idO ID do proprietário associado à observação. Este campo determina o usuário listado como o criador da observação na linha do tempo do registro.
hs_attachment_idsOs IDs dos anexos da observação. Vários IDs de anexo são separados por ponto e vírgula.

​
Associações

Para criar e associar uma observação a registros existentes, inclua um objeto de associações na solicitação. Por exemplo, para criar uma observação e associá-la a uma empresa e a um negócio, o corpo da solicitação pode ser semelhante ao seguinte: 
// Example POST request to https://api.hubspot.com/crm/v3/objects/notes
{
  "properties": {
    "hs_timestamp": "2021-11-12T15:48:22Z",
    "hs_note_body": "Spoke with decision maker Carla. Attached the proposal and draft of contract.",
    "hubspot_owner_id": "14240720",
    "hs_attachment_ids": "24332474034;24332474044"
  },
  "associations": [
    {
      "to": {
        "id": 301
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 190
        }
      ]
    },
    {
      "to": {
        "id": 401
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 214
        }
      ]
    }
  ]
}
No objeto de associações, você deve incluir o seguinte:
CampoDescrição
toO registro que deseja associar à observação, especificado por seu valor de id exclusivo.
typesO tipo de associação entre a observação e o registro. 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.
Saiba mais sobre criação de notas em lote na documentação de referência.

​
Recuperar observações

Você pode recuperar observações individualmente ou em lotes. Para recuperar uma observação individual, faça uma solicitação GET para /crm/v3/objects/notes/{noteId}. Para solicitar uma lista de todas as observações, faça uma solicitação GET para /crm/v3/objects/notes. Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
DescriçãoParâmetro
propertiesUma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta.
associationsUma lista separada por vírgulas de tipos de objeto 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.
Por exemplo, para recuperar observações com o conteúdo do texto e qualquer ID de contato associado, o URL da solicitação pode ser semelhante ao seguinte: https://api.hubapi.com/crm/v3/objects/notes?limit=10&properties=hs_note_body&associations=contact&archived=false. Saiba mais sobre como recuperar um lote de notas pelo ID interno ou pelo valor de uma propriedade única na documentação de referência.

​
Atualizar observações

Você pode atualizar observações individualmente ou em massa. Para atualizar uma observação individual pelo seu ID, faça uma solicitação PATCH para /crm/v3/objects/notes/{noteId}. No corpo da solicitação, inclua as propriedades de observação que deseja atualizar: 
// Example PATCH request to https://api.hubspot.com/crm/v3/objects/notes/{noteID}
{
  "properties": {
    "hs_note_body": "Spoke with decision maker Carla.",
    "hs_attachment_ids": "24332474034;24332474044"
  }
}
O HubSpot ignorará valores para propriedades somente leitura e inexistentes. Para limpar um valor de propriedade, passe uma string vazia para a propriedade no corpo da solicitação. Saiba mais sobre atualização de notas em lote na documentação de referência.

​
Associar chamadas existentes a registros

Para associar uma observação a outros registros do CRM, como um contato, faça uma solicitação PUT para /crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. A URL da solicitação contém os campos a seguir:
CampoDescrição
noteIdO ID da observação.
toObjectTypeO tipo de objeto ao qual você deseja associar a observação (por exemplo, contato ou empresa)
toObjectIdO ID do registro ao qual você deseja associar a observação.
associationTypeIdUm identificador exclusivo para indicar o tipo de associação entre a observação e o outro objeto. O ID pode ser representado numericamente ou em maiúsculas (por exemplo, note_to_contact). Você pode recuperar o valor por meio da API de associações.
Por exemplo, a URL da sua solicitação pode ser parecida com o seguinte: https://api.hubspot.com/crm/v3/objects/notes/17147287858/associations/contact/581751/202

​
Remover uma associação

Para remover uma associação entre uma chamada e um registro, faça uma solicitação DELETE para o mesmo URL acima: /crm/v3/objects/notes/{noteId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

​
Fixar uma observação em um registro

Você pode fixar uma observação em um registro para que permaneça no topo da linha do tempo do registro. A chamada já deve estar associada ao registro antes da fixação e você só pode fixar uma atividade por registo. Para fixar uma observação, inclua o id da observação no campo hs_pinned_engagement_id ao criar ou atualizar um registro por meio das APIs de objeto. Saiba mais sobre como usar as APIs de empresas,contatos, negócios, tickets e objetos personalizados.

​
Excluir observações

Você pode excluir observações individualmente ou em massa, o que adicionará a observação à lixeira no HubSpot. Você pode restaurar posteriormente a observação da linha do tempo do registro. Para excluir uma observação individual pelo seu ID, faça uma solicitação DELETE para /crm/v3/objects/notes/{noteId}. Saiba mais sobre exclusão de notas na documentação de referência.