Pesquisa 

Use os endpoints de pesquisa do CRM para filtrar, classificar e pesquisar objetos, registros e engajamentos em seu CRM. Por exemplo, use os endpoints para obter uma lista de contatos em sua conta ou uma lista de todos os negócios abertos.

Para usar esses endpoint de um app, é necessário um escopo de CRM. Consulte esta lista de escopos disponíveis para saber quais escopos granulares do CRM podem ser usados para atingir seu objetivo.

Fazer um pedido de pesquisa

Para pesquisar seu CRM, faça uma solicitação POST para o endpoint de pesquisa do objeto. Os endpoints de pesquisa do CRM são construídos usando o seguinte formato:

/crm/v3/objects/{object}/search

Para fazer uma pesquisa básica que retorna apenas propriedades padrão sem filtragem ou classificação adicional, inclua apenas um objeto vazio no corpo da solicitação. Por exemplo:

// Example POST request to /crm/v3/objects/contacts/search {}

Objetos do CRM

As tabelas abaixo contêm os endpoints de pesquisa de objetos, os objetos aos quais eles se referem e as propriedades que são retornadas por padrão. Saiba mais sobre como especificar propriedades retornadas.

Use this table to describe parameters / fields
Endpoint de pesquisaObjetoPropriedades padrão retornadas
/crm/v3/objects/companies/search
Companies

name, domain, createdate,

hs_lastmodifieddate, hs_object_id

/crm/v3/objects/contacts/search
Contacts

firstname,lastname,email,lastmodifieddate,hs_object_id, createdate

/crm/v3/objects/{objectType}/search
Custom objects

hs_createdate,hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/deals/search
Deals

dealname, amount, closedate,
pipeline,dealstage, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/feedback_submissions/search
Feedback submissions

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/line_items/search
Line items

quantity, amount, price, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/products/search
Products

name, description ,price, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/quotes/search
Quotes

hs_expiration_date, hs_public_url_key, hs_status,

hs_title, hs_createdate, hs_lastmodifieddate,

hs_object_id

/crm/v3/objects/tickets/search
Tickets

content, hs_pipeline, hs_pipeline_stage,

hs_ticket_category, hs_ticket_priority, subject,

createdate, hs_lastmodifieddate, hs_object_id

Engajamentos

A tabela abaixo contém os endpoints de pesquisa de engajamento, os engajamentos aos quais eles se referem e as propriedades que são retornadas por padrão. Saiba mais sobre como especificar propriedades retornadas.

Use this table to describe parameters / fields
Endpoint de pesquisaEngajamentoPropriedades padrão retornadas
/crm/v3/objects/calls/search
Calls

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/emails/search
Emails

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/meetings/search
Meetings

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/notes/search
Notes

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/tasks/search
Tasks

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Filtrar resultados de pesquisa

Use filtros no corpo da solicitação para limitar os resultados apenas aos registros com valores de propriedade correspondentes. Por exemplo, a solicitação abaixo pesquisa todos os contatos com o nome Alice.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[ { "filters":[ { "propertyName": "firstname", "operator": "EQ", "value": "Alice" } ] } ] }'

Para incluir vários critérios de filtro, você pode agrupar os filters em filterGroups:

  • Para aplicar a lógica E, inclua uma lista de condições separada por vírgulas dentro de um conjunto de filters.
  • Para aplicar a lógica OU, inclua vários filters com um filterGroup.

Você pode incluir, no máximo, três filterGroups com até três filtros em cada grupo.

Por exemplo, a solicitação abaixo procura contatos com o nome Alice E um sobrenome que não seja Smith, OU contatos que não tenham um valor para o e-mail da propriedade. 

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups": [ { "filters": [ { "propertyName": "firstname", "operator": "EQ", "value": "Alice" }, { "propertyName": "lastname", "operator": "NEQ", "value": "Smith" } ] }, { "filters": [ { "propertyName": "email", "operator": "NOT_HAS_PROPERTY" } ] } ] }'

Você pode usar operadores em filtros para especificar quais registros devem ser retornados. Os valores nos filtros não fazem distinção entre maiúsculas e minúsculas, com exceção dos operadores IN e NOT_IN. Você pode usar os seguintes operadores em um filtro:

Use this table to describe parameters / fields
OperadorDescription
LT

Menor que

LTE

Menor ou igual a

GT

Maior que

GTE

Maior ou igual a

EQ

Igual a

NEQ

Não é igual a

BETWEEN

No intervalo especificado. Em sua solicitação, use pares de chave-valor para definir highValue e value. Consulte o exemplo acima.

IN

Incluído na lista especificada. Em sua solicitação, inclua os valores da lista em uma matriz de valores. Este operador diferencia letras maiúsculas e minúsculas, portanto, os valores inseridos devem estar em minúsculas. Consulte o exemplo acima.

NOT_IN

Não incluído na lista especificada. Em sua solicitação, inclua os valores da lista em uma matriz de valores . Este operador diferencia letras maiúsculas e minúsculas, portanto, os valores inseridos devem estar em minúsculas.

HAS_PROPERTY

Tem um valor para a propriedade especificada

NOT_HAS_PROPERTY

Não tem um valor para a propriedade especificada

CONTAINS_TOKEN

Contém um token. Em sua solicitação, você pode usar curingas (*) para realizar uma pesquisa parcial. Por exemplo, use o valor *@hubspot.com para recuperar contatos com um endereço de e-mail da HubSpot.

NOT_CONTAINS_TOKEN

Não contém um token

Por exemplo, você pode usar o operador BETWEEN para pesquisar todas as tarefas que foram modificadas pela última vez em um intervalo de tempo específico:

curl https://api.hubapi.com/crm/v3/objects/tasks/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"hs_lastmodifieddate", "operator":"BETWEEN", "highValue": "1642672800000", "value":"1579514400000" } ] } ] }'

Para outro exemplo, você pode usar o operador IN para pesquisar todos os negócios em etapas específicas do seu pipeline: 

curl https://api.hubapi.com/crm/v3/objects/deals/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"dealstage", "operator":"IN", "values": ["appointmentscheduled", "contractsent", "qualifiedtobuy"] } ] } ] }'

Pesquisar por associações

Pesquise por registros associados a outros registros específicos usando a pseudopropriedade associations.{objectType}.

Por exemplo, a solicitação abaixo procura por todos os tíquetes associados a um contato com o ID de contato 123:

curl https://api.hubapi.com/crm/v3/objects/tickets/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filters": [ { "propertyName": "associations.contact", "operator": "EQ", "value": "123" } ] }'

Você pode pesquisar por meio de associações usando os seguintes valores de pseudopropriedade:

  • associations.company
  • associations.contact
  • associations.ticket
  • associations.deal
  • associations.quote

Observação: no momento, a opção de pesquisar por associações de objetos personalizados não é suportada por meio de endpoints de pesquisa. Para encontrar associações de objetos personalizados, você pode usar a API de associações.

Classificar resultados de pesquisa

Use uma regra de classificação no corpo da solicitação para listar os resultados em ordem crescente ou decrescente. Apenas uma regra de classificação pode ser aplicada a qualquer pesquisa.

Por exemplo, a solicitação abaixo classifica contatos retornados com o mais recente criado primeiro:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "sorts": [ { "propertyName": "createdate", "direction": "DESCENDING" } ] }'

Pesquisar propriedades de pesquisa padrão

Pesquise todas as propriedades de texto padrão nos registros do objeto especificado para encontrar todos os registros que têm um valor que contém a sequência de caracteres especificada. Por padrão, os resultados serão retornados na ordem de criação do objeto (primeiro o mais antigo), mas você pode substituir isso com classificar.

Por exemplo, a solicitação abaixo pesquisa todos os contatos com um valor de propriedade de texto padrão que contém a letra X.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "query": "x" }'

Abaixo estão as propriedades que são pesquisadas por padrão pelo método acima:

Use this table to describe parameters / fields
Endpoint de pesquisaObjetoPropriedades de pesquisa padrão
/crm/v3/objects/calls/search
Calls

hs_call_title, hs_body_preview

/crm/v3/objects/companies/search
Companies

website, phone, name, domain

/crm/v3/objects/contacts/search
Contacts

firstname,lastname,email,phone,hs_additional_emails, fax, mobilephone, company, hs_marketable_until_renewal

/crm/v3/objects/{objectType}/search
Custom objects

Todas as propriedades de objetos personalizados são pesquisáveis por padrão

/crm/v3/objects/deals/search
Deals

dealname,pipeline,dealstage, description, dealtype

/crm/v3/objects/emails/search
Emails

hs_email_subject

/crm/v3/objects/feedback_submissions/search
Feedback submissions

hs_submission_name, hs_content

/crm/v3/objects/meetings/search
Meetings

hs_meeting_title, hs_meeting_body

/crm/v3/objects/notes/search
Notes

hs_note_body

/crm/v3/objects/products/search
Products

name, description ,price, hs_sku

/crm/v3/objects/quotes/search
Quotes

hs_sender_firstname, hs_sender_lastname, hs_proposal_slug, hs_title, hs_sender_company_name, hs_sender_email, hs_quote_number, hs_public_url_key

/crm/v3/objects/tasks/search
Tasks

hs_task_body, hs_task_subject

/crm/v3/objects/tickets/search
Tickets

subject, content, hs_pipeline_stage, hs_ticket_category, hs_ticket_id

/crm/v3/objects/line_items/search
Line items

Não há propriedades pesquisáveis padrão para itens de linha

Especifique propriedades retornadas

Cada solicitação retornará um conjunto padrão de propriedades em seus resultados de pesquisa para o objeto solicitado. Você pode substituir isso fornecendo um conjunto de nomes de propriedades específicos no parâmetro properties de seu corpo de solicitação. 

Por exemplo, a solicitação abaixo pesquisa todos os contatos e retornará seu e-mail e estado:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "properties": [ "email", "state" ] }'

Percorrendo páginas de resultados

Por padrão, os endpoints de pesquisa retornarão as páginas com 10 objetos por vez. Isso pode ser alterado definindo o parâmetro limit no corpo da solicitação. O número máximo de objetos permitidos por página é 100.

Por exemplo, a solicitação abaixo retornaria páginas contendo 20 resultados cada.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "limit": 20 }

Para acessar a próxima página dos resultados, você deve informar o parâmetro after fornecido na propriedade paging.next.after da resposta anterior. Se a propriedade paging.next.after não for fornecida, não haverá resultados adicionais para serem exibidos. Você deve formatar o valor no parâmetro after como um número inteiro.

Por exemplo, a solicitação abaixo retornaria a próxima página dos resultados:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "after": "20" }'

Limitações

  • Pode levar algum tempo para que os objetos do CRM recém-criados ou atualizados sejam exibidos nos resultados de pesquisa.
  • Os objetos do CRM arquivados não aparecerão nos resultados de pesquisa.
  • Os endpoints de pesquisa são limitados a quatro solicitações por segundo.
  • Uma consulta pode conter no máximo 3.000 caracteres. Se o corpo da solicitação exceder 3.000 caracteres, um erro 400 será retornado.
  • Os endpoints de pesquisa estão limitados a um total de 10.000 resultados por consulta. Uma tentativa de exibir mais de 10 mil resultados gerará um erro 400.
  • Ao pesquisar números de telefone, a HubSpot usa propriedades calculadas especiais para padronizar o formato. Todas essas propriedades começam comhs_searchable_calculated_*. Como parte dessa padronização, a HubSpot usa apenas o código de área e o número local. Você não deve incluir o código do país nos critérios de pesquisa ou filtro.
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..