Buscar 

Utiliza los puntos de terminación de búsqueda de CRM para filtrar, clasificar y buscar objetos, registros y compromisos en tu CRM. Por ejemplo, usa los puntos de terminación para obtener una lista de contactos en tu cuenta o una lista de todos los negocios abiertos.

Para usar estos puntos de terminación de una aplicación, se requiere el alcance del CRM. Consulta esta lista de alcances disponibles para saber qué alcances detallados del CRM se pueden usar para lograr tu meta.

Realizar una solicitud de búsqueda

Para buscar en tu CRM, realiza una solicitud POST en el punto de terminación de búsqueda del objeto. Los puntos de terminación de búsqueda de CRM se construyen utilizando el siguiente formato:

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

Para hacer una búsqueda básica, devolviendo solo las propiedades predeterminadas sin filtrado u ordenamiento adicional, incluye solo un objeto vacío en el cuerpo de la solicitud. Por ejemplo:

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

Objetos del CRM

Las tablas a continuación contienen los puntos de terminación de búsqueda de objetos, los objetos a los que se refieren y las propiedades que se devuelven de forma predeterminada. Más información sobre cómo especificar las propiedades devueltas.

Use this table to describe parameters / fields
Punto de terminación de búsquedaObjetosPropiedades devueltas predeterminadas
/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

Interacciones

La siguiente tabla contiene los puntos de terminación de búsqueda de interacciones, las interacciones a las que se refieren y las propiedades que se devuelven de forma predeterminada. Más información sobre cómo especificar las propiedades devueltas.

Use this table to describe parameters / fields
Punto de terminación de búsquedaInteraccionesPropiedades devueltas predeterminadas
/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 búsqueda

Usa filtros en el cuerpo de la solicitud para limitar los resultados solo a los registros con valores de propiedad coincidentes. Por ejemplo, la siguiente solicitud busca todos los contactos con el nombre 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 varios criterios de filtro, puedes agrupar filters dentro de filterGroups:

  • Para aplicar la lógica AND, incluye una lista separada por comas de condiciones dentro de un conjunto de filters.
  • Para aplicar la lógica OR, incluye varios filters con un filterGroup.

Puedes incluir un máximo de tres filterGroups con hasta tres filters en cada grupo.

Por ejemplo, la siguiente solicitud busca contactos con el primer nombre Alice AND un apellido que no sea Smith, OR contactos que no tienen un valor para la propiedad email. 

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" } ] } ] }'

Puedes usar operadores en filtros para especificar qué registros deben devolverse. Los valores en los filtros no distinguen entre mayúsculas y minúsculas, con la excepción de los operadores IN y NOT_IN. Puedes usar los siguientes operadores en un filtro:

Use this table to describe parameters / fields
OperadorDescription
LT

Menor que

LTE

Menor que o igual a

GT

Mayor que

GTE

Mayor que o igual a

EQ

Igual a

NEQ

No es igual a

BETWEEN

Dentro del rango especificado. En tu solicitud, usa pares clave-valor para establecer highValue y value. Consulta el siguiente ejemplo.

IN

Incluido dentro de la lista especificada. En la solicitud, incluye los valores de la lista en una matriz values. Este operador distingue entre mayúsculas y minúsculas, por lo que los valores introducidos deben estar en minúsculas. Consulta el siguiente ejemplo.

NOT_IN

No incluido dentro de la lista especificada En la solicitud, incluye los valores de la lista en una matriz values. Este operador distingue entre mayúsculas y minúsculas, por lo que los valores introducidos deben estar en minúsculas.

HAS_PROPERTY

Tiene un valor para la propiedad especificada

NOT_HAS_PROPERTY

No tiene un valor para la propiedad especificada

CONTAINS_TOKEN

Contiene una ficha. En tu solicitud, puedes usar comodines (*) para realizar una búsqueda parcial. Por ejemplo, usa el valor *@hubspot.com para recuperar contactos con una dirección de correo electrónico de HubSpot.

NOT_CONTAINS_TOKEN

No contiene una ficha

Como ejemplo adicional, puedes usar el operador BETWEEN para buscar todas las tareas que se modificaron por última vez dentro de un intervalo de tiempo 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 otro ejemplo, puedes usar el operador IN para buscar todas las ofertas en etapas específicas de tu 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"] } ] } ] }'

Buscar en asociaciones

Busca registros que estén asociados con otros registros específicos mediante las pseudopropiedades associations.{objectType}.

Por ejemplo, la siguiente solicitud busca todos los tickets asociados con un contacto que tiene el ID de contacto de 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" } ] }'

Puedes buscar a través de asociaciones usando los siguientes valores de pseudopropiedad:

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

Nota: la opción de buscar a través de asociaciones de objetos personalizadas no es compatible actualmente a través de los puntos de terminación de búsqueda. Para encontrar asociaciones de objetos personalizados, puedes usar la API de asociaciones.

Ordenar resultados de búsqueda

Usa una regla de ordenamiento en el cuerpo de la solicitud para listar los resultados en orden ascendente o descendente. Solo se puede aplicar una regla de ordenamiento a cualquier búsqueda.

Por ejemplo, la siguiente solicitud ordena los contactos devueltos con la mayoría de los contactos creados recientemente:

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

Buscar propiedades predeterminadas que se pueden buscar

Busca todas las propiedades de texto predeterminadas en los registros del objeto especificado para encontrar todos los registros que tienen un valor que contiene la cadena especificada. Por opción predeterminada, los resultados se devolverán en el orden de creación de los objetos (más antiguo primero), pero puedes anular esto con ordenar.

Por ejemplo, la solicitud a continuación busca todos los contactos con un valor de propiedad de texto predeterminado que contenga la letra X.

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

A continuación se muestran las propiedades que se buscan por opción predeterminada a través del método anterior:

Use this table to describe parameters / fields
Punto de terminación de búsquedaObjetosPropiedades de búsqueda predeterminadas
/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 las propiedades de objetos personalizados se pueden buscar de forma predeterminada

/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

No hay propiedades de búsqueda predeterminadas para elementos de línea

Especificar propiedades devueltas

Cada solicitud devolverá un conjunto predeterminado de propiedades en sus resultados de búsqueda para el objeto solicitado. Puedes anular esto proporcionando una matriz de nombres de propiedad específicos en el parámetro de properties de tu cuerpo de solicitud. 

Por ejemplo, la siguiente solicitud busca todos los contactos y devolverá su correo electrónico y el estado:

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

Paginación de resultados

Por opción predeterminada, los puntos de terminación de búsqueda devolverán páginas de 10 registros al mismo tiempo. Esto puede cambiarse configurando el parámetro limit en el cuerpo de tu solicitud. El número máximo de objetos admitidos por página es 100.

Por ejemplo, la solicitud a continuación devolvería páginas que contienen 20 resultados cada una.

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

Para acceder a la siguiente página de resultados, debes pasar un parámetro after proporcionado en la propiedad paging.next.after de la página anterior. Si no se proporciona la propiedad paging.next.after, no hay resultados adicionales que mostrar. Debes formatear el valor en el parámetro after como un entero.

Por ejemplo, la siguiente solicitud devolvería la siguiente página de resultados:

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

Limitaciones

  • Es posible que los objetos del CRM recién creados o actualizados tarden unos minutos en aparecer en los resultados de búsqueda.
  • Los objetos de CRM archivados no aparecerán en ningún resultado de búsqueda.
  • Los puntos de terminación tienen una tasa limitada de cuatro solicitudes por segundo.
  • Una consulta puede contener un máximo de 3.000 caracteres. Si el cuerpo de tu solicitud supera los 3.000 caracteres, se devolverá un error 400.
  • Los puntos de terminación de búsqueda están limitados a 10.000 resultados totales para cualquier consulta dada. Tratar de obtener más de 10.000 generará un error 400.
  • Cuando buscas números de teléfono, HubSpot usa propiedades calculadas especiales para estandarizar el formato. Todas estas propiedades comienzan con hs_searchable_calculated_*. Como parte de esta estandarización, HubSpot solo utiliza el código de área y el número local. Debes abstenerte de incluir el código de país en tus criterios de búsqueda o filtro.
¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.