Búsqueda

Los endpoints de búsqueda consultan el índice de datos abiertos de graph8: una base de datos B2B global con millones de contactos y empresas agregados a partir de múltiples proveedores de datos. Úselo para descubrir nuevos prospectos que coincidan con su perfil de cliente ideal (ICP) y guardarlos en su espacio de trabajo.

Esto se diferencia de los endpoints /contacts y /companies, que solo devuelven datos que usted ya guardó: sus datos propios del CRM.

Qué puede buscar

Contactos: filtre por título de trabajo, antigüedad, departamento, habilidades, ubicación, atributos de empresa y más (~28 campos filtrables)
Empresas: filtre por industria, número de empleados, ingresos, geografía, año de fundación, presencia en LinkedIn y más (~15 campos filtrables)

Cómo se conecta con sus datos

Los resultados de búsqueda provienen del índice de datos abiertos y son de solo lectura. Para trabajar con ellos en sus flujos de trabajo:

Buscar: encuentre contactos o empresas que coincidan con sus criterios
Guardar en lista: use /search/contacts/save o /search/companies/save para copiar los registros coincidentes en su espacio de trabajo
Gestionar: una vez guardados, aparecen en /contacts y /companies como datos propios

Costos de créditos

Operación	PAYG	Platform
Búsqueda de contactos	1 crédito por registro devuelto	Incluido gratis (dentro de 5 rps)
Búsqueda de empresas	1 crédito por registro devuelto	Incluido gratis (dentro de 5 rps)
Guardar en lista	1 crédito por registro guardado	Incluido gratis (dentro de 5 rps)

En PAYG, una búsqueda que devuelve 25 contactos cuesta 25 créditos. Una búsqueda que devuelve 0 resultados no tiene costo.

En Platform, la búsqueda forma parte del paquete ilimitado del índice de graph8; el único límite es el tope de velocidad de 5 rps.

Operadores de filtro

Todos los endpoints de búsqueda aceptan un array filters en el cuerpo de la solicitud. Cada filtro tiene un field, operator y value.

Operador	Descripción	Valor de ejemplo
`any_of`	Coincidencia exacta: el campo coincide con cualquier valor de la lista	`["CEO", "CTO"]`
`contains`	Coincidencia difusa o por subcadena	`["sales"]`
`all_of`	El campo debe contener TODOS los valores	`["python", "javascript"]`
`none_of`	El campo NO debe coincidir con ningún valor	`["intern", "student"]`
`is_empty`	El campo no tiene valor	`[]`
`is_not_empty`	El campo tiene un valor	`[]`
`between`	Rango numérico (inclusivo)	`[2015, 2025]`
`exists`	El campo existe en el registro	`[]`

Búsqueda de contactos

POST /search/contacts

Busca en el índice de datos abiertos los contactos que coincidan con los filtros indicados. Devuelve resultados paginados con hasta 100 resultados por página.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`filters`	array	No	Condiciones de filtro (lógica AND). Consulte operadores de filtro
`page`	integer	No	Número de página, indexado desde 1 (predeterminado: 1, máx.: 100)
`limit`	integer	No	Resultados por página (predeterminado: 25, máx.: 100)

Campos de contacto filtrables

Campo	Descripción
`first_name`	Nombre
`last_name`	Apellido
`work_email`	Dirección de email laboral
`personal_emails`	Direcciones de email personal
`direct_phone`	Número de teléfono directo
`mobile_phone`	Número de teléfono móvil
`job_title`	Título de trabajo
`job_department`	Departamento
`seniority_level`	Nivel de antigüedad (p. ej., “VP”, “Director”, “Manager”)
`role`	Rol
`linkedin_url`	URL de perfil de LinkedIn
`gender`	Género
`skills`	Habilidades
`education_degree`	Título académico
`education_field`	Campo de estudio
`education_university_name`	Nombre de la universidad
`city`	Ciudad
`state`	Estado o provincia
`country`	País
`confidence_score`	Puntuación de confianza del dato
`company_name`	Nombre de la empresa
`company_domain`	Dominio de la empresa
`company_industry`	Industria de la empresa
`company_employee_count`	Número de empleados de la empresa
`company_country`	País de la empresa
`company_state`	Estado de la empresa
`company_city`	Ciudad de la empresa
`company_revenue`	Ingresos de la empresa
`company_founded_year`	Año de fundación de la empresa

Ejemplo

curl -X POST "https://be.graph8.com/api/v1/search/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["CEO", "CTO", "VP Engineering"]},
      {"field": "company_industry", "operator": "contains", "value": ["Technology"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "page": 1,
    "limit": 25
  }'

response = requests.post(
    f"{BASE_URL}/search/contacts",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CEO", "CTO", "VP Engineering"]},
            {"field": "company_industry", "operator": "contains", "value": ["Technology"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "page": 1,
        "limit": 25
    }
)

const response = await fetch(`${BASE_URL}/search/contacts`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CEO", "CTO", "VP Engineering"] },
      { field: "company_industry", operator: "contains", value: ["Technology"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    page: 1,
    limit: 25
  }),
});

Respuesta

{
  "data": [
    {
      "first_name": "Jane",
      "last_name": "Doe",
      "middle_name": null,
      "work_email": "[email protected]",
      "personal_emails": null,
      "direct_phone": "+1-555-0100",
      "mobile_phone": null,
      "job_title": "CEO",
      "job_department": "Executive",
      "seniority_level": "C-Suite",
      "role": "Chief Executive Officer",
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "linkedin_headline": "CEO at Acme Inc",
      "city": "San Francisco",
      "state": "California",
      "country": "United States",
      "company_name": "Acme Inc",
      "company_domain": "acme.com",
      "company_industry": "Technology",
      "company_employee_count": "200",
      "company_country": "United States",
      "confidence_score": 95
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "has_next": true
  }
}

Búsqueda de empresas

POST /search/companies

Busca en el índice de datos abiertos las empresas que coincidan con los filtros indicados.

Cuerpo de la solicitud

Misma estructura que la búsqueda de contactos. Consulte el cuerpo de la solicitud anterior.

Campos de empresa filtrables

Campo	Descripción
`name`	Nombre de la empresa
`domain`	Dominio de la empresa
`website`	URL del sitio web
`description`	Descripción de la empresa
`industry`	Industria
`industry_group`	Grupo de industria
`employee_count`	Número de empleados
`revenue`	Ingresos anuales
`founded_year`	Año de fundación
`country`	País
`state`	Estado o provincia
`city`	Ciudad
`phone`	Número de teléfono
`linkedin_url`	URL de LinkedIn
`linkedin_followers`	Número de seguidores en LinkedIn

Ejemplo

curl -X POST "https://be.graph8.com/api/v1/search/companies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "industry", "operator": "contains", "value": ["Banking"]},
      {"field": "employee_count", "operator": "between", "value": [100, 1000]},
      {"field": "country", "operator": "any_of", "value": ["United States"]}
    ],
    "page": 1,
    "limit": 50
  }'

response = requests.post(
    f"{BASE_URL}/search/companies",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "industry", "operator": "contains", "value": ["Banking"]},
            {"field": "employee_count", "operator": "between", "value": [100, 1000]},
            {"field": "country", "operator": "any_of", "value": ["United States"]}
        ],
        "page": 1,
        "limit": 50
    }
)

const response = await fetch(`${BASE_URL}/search/companies`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    filters: [
      { field: "industry", operator: "contains", value: ["Banking"] },
      { field: "employee_count", operator: "between", value: [100, 1000] },
      { field: "country", operator: "any_of", value: ["United States"] }
    ],
    page: 1,
    limit: 50
  }),
});

Respuesta

{
  "data": [
    {
      "name": "First National Bank",
      "domain": "fnb.com",
      "website": "https://www.fnb.com",
      "description": "Regional banking institution...",
      "industry": "Banking",
      "industry_group": "Financial Services",
      "employee_count": "450",
      "revenue": "$100M-$500M",
      "founded_year": 1987,
      "phone": "+1-555-0200",
      "address": "100 Main St",
      "city": "Pittsburgh",
      "state": "Pennsylvania",
      "country": "United States",
      "zip": 15222,
      "linkedin_url": "https://linkedin.com/company/fnb",
      "linkedin_followers": "12500",
      "facebook_url": "https://facebook.com/fnb",
      "twitter_url": "https://twitter.com/fnb",
      "crunchbase_url": null,
      "logo_url": "https://logo.clearbit.com/fnb.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 89,
    "has_next": true
  }
}

Guardar contactos en lista

POST /search/contacts/save

Busca contactos y guarda los resultados coincidentes en una nueva lista dentro de su organización. Los resultados se guardan de forma asíncrona. Devuelve 202 Accepted.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`filters`	array	No	Condiciones de filtro (lógica AND)
`list_title`	string	Sí	Título de la nueva lista
`max_results`	integer	No	Máximo de resultados a guardar (predeterminado: 1,000, máx.: 10,000)

Ejemplo

curl -X POST "https://be.graph8.com/api/v1/search/contacts/save" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "job_title", "operator": "any_of", "value": ["VP Sales", "Head of Sales"]},
      {"field": "company_industry", "operator": "contains", "value": ["SaaS"]}
    ],
    "list_title": "Sales Leaders in SaaS",
    "max_results": 5000
  }'

response = requests.post(
    f"{BASE_URL}/search/contacts/save",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["VP Sales", "Head of Sales"]},
            {"field": "company_industry", "operator": "contains", "value": ["SaaS"]}
        ],
        "list_title": "Sales Leaders in SaaS",
        "max_results": 5000
    }
)
list_id = response.json()["data"]["list_id"]

const response = await fetch(`${BASE_URL}/search/contacts/save`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["VP Sales", "Head of Sales"] },
      { field: "company_industry", operator: "contains", value: ["SaaS"] }
    ],
    list_title: "Sales Leaders in SaaS",
    max_results: 5000
  }),
});
const listId = (await response.json()).data.list_id;

Respuesta

{
  "data": {
    "list_id": 42,
    "list_title": "Sales Leaders in SaaS",
    "estimated_total": 3200,
    "status": "processing"
  }
}

Guardar empresas en lista

POST /search/companies/save

Busca empresas y guarda los resultados coincidentes en una nueva lista. Devuelve 202 Accepted.

Cuerpo de la solicitud

Misma estructura que guardar contactos en lista, pero utiliza los campos de filtro de empresa.

Ejemplo

curl -X POST "https://be.graph8.com/api/v1/search/companies/save" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "industry", "operator": "any_of", "value": ["Financial Services"]},
      {"field": "employee_count", "operator": "between", "value": [500, 5000]}
    ],
    "list_title": "Mid-Market Financial Services",
    "max_results": 2000
  }'

response = requests.post(
    f"{BASE_URL}/search/companies/save",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "industry", "operator": "any_of", "value": ["Financial Services"]},
            {"field": "employee_count", "operator": "between", "value": [500, 5000]}
        ],
        "list_title": "Mid-Market Financial Services",
        "max_results": 2000
    }
)

const response = await fetch(`${BASE_URL}/search/companies/save`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    filters: [
      { field: "industry", operator: "any_of", value: ["Financial Services"] },
      { field: "employee_count", operator: "between", value: [500, 5000] }
    ],
    list_title: "Mid-Market Financial Services",
    max_results: 2000
  }),
});

Respuesta

{
  "data": {
    "list_id": 43,
    "list_title": "Mid-Market Financial Services",
    "estimated_total": 890,
    "status": "processing"
  }
}