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.
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:
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.
Punto de terminación de búsqueda | Objetos | Propiedades devueltas predeterminadas |
---|---|---|
/crm/v3/objects/companies/search
| Companies |
|
/crm/v3/objects/contacts/search
| Contacts |
|
/crm/v3/objects/{objectType}/search
| Custom objects |
|
/crm/v3/objects/deals/search
| Deals |
|
/crm/v3/objects/feedback_submissions/search
| Feedback submissions |
|
/crm/v3/objects/line_items/search
| Line items |
|
/crm/v3/objects/products/search
| Products |
|
/crm/v3/objects/quotes/search
| Quotes |
|
/crm/v3/objects/tickets/search
| Tickets |
|
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.
Punto de terminación de búsqueda | Interacciones | Propiedades devueltas predeterminadas |
---|---|---|
/crm/v3/objects/calls/search
| Calls |
|
/crm/v3/objects/emails/search
| Emails |
|
/crm/v3/objects/meetings/search
| Meetings |
|
/crm/v3/objects/notes/search
| Notes |
|
/crm/v3/objects/tasks/search
| Tasks |
|
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:
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 unfilterGroup
.
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
.
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:
Operador | Description |
---|---|
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 |
IN
| Incluido dentro de la lista especificada. En la solicitud, incluye los valores de la lista en una matriz |
NOT_IN
| No incluido dentro de la lista especificada En la solicitud, incluye los valores de la lista en una matriz |
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 |
NOT_CONTAINS_TOKEN
| No contiene una ficha |
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
:
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.
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:
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.
A continuación se muestran las propiedades que se buscan por opción predeterminada a través del método anterior:
Punto de terminación de búsqueda | Objetos | Propiedades de búsqueda predeterminadas |
---|---|---|
/crm/v3/objects/calls/search
| Calls |
|
/crm/v3/objects/companies/search
| Companies |
|
/crm/v3/objects/contacts/search
| Contacts |
|
/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 |
|
/crm/v3/objects/emails/search
| Emails |
|
/crm/v3/objects/feedback_submissions/search
| Feedback submissions |
|
/crm/v3/objects/meetings/search
| Meetings |
|
/crm/v3/objects/notes/search
| Notes |
|
/crm/v3/objects/products/search
| Products |
|
/crm/v3/objects/quotes/search
| Quotes |
|
/crm/v3/objects/tasks/search
| Tasks |
|
/crm/v3/objects/tickets/search
| Tickets |
|
/crm/v3/objects/line_items/search
| Line items | No hay propiedades de búsqueda predeterminadas para elementos de línea |
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:
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.
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:
- 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.
Gracias por tus comentarios, son muy importantes para nosotros.