Enriquecimiento

Los endpoints de enriquecimiento cubren tres capacidades:

Lookup: encuentra una persona o empresa específica en el índice de datos abiertos cuando ya conoce su correo electrónico, URL de LinkedIn o dominio. Devuelve los datos completos del perfil de forma instantánea.
Enrich: completa campos faltantes (correos electrónicos, números de teléfono) en los contactos que ya tiene en su espacio de trabajo, procesándolos a través de varios proveedores de datos en secuencia (enriquecimiento en cascada).
Verify: comprueba si una dirección de correo electrónico es válida para envío antes de utilizarla.

Dos categorías de facturación

Los endpoints de enriquecimiento se dividen en dos categorías con modelos de facturación distintos. La diferencia es relevante porque graph8 asume el costo en una de ellas y paga a un proveedor externo en la otra.

Index Lookups: gratuitos en Platform

Estos endpoints consultan los índices propios de graph8 (OpenSearch + ClickHouse). Registro único, instantáneo, sin cascada.

Endpoint	PAYG	Platform
`POST /enrichment/lookup/person`	2 créditos	Incluido gratis (dentro de 5 rps)
`POST /enrichment/lookup/company`	2 créditos	Incluido gratis (dentro de 5 rps)
`POST /enrichment/verify-email` (validador interno)	1 crédito	Incluido gratis (dentro de 5 rps)

Waterfall Enrichment: siempre con créditos

Estos endpoints encadenan proveedores externos (Prospeo, Dropcontact, Cognism, entre otros). graph8 paga al proveedor por cada registro, por lo que los créditos aplican tanto en PAYG como en Platform.

Endpoint	PAYG	Platform
`POST /enrichment/enrich` (cascada)	Variable por registro	Variable por registro
Verificadores de correo externos (Kickbox, ZeroBounce)	Por verificación	Por verificación

Consulte Pricing para la comparación completa de planes.

Person Lookup

POST /enrichment/lookup/person

Búsqueda instantánea de personas. Proporcione al menos uno de los siguientes datos: email, linkedin_url, o first_name + last_name + company_domain.

Precios: 2 créditos en PAYG. Gratuito en Platform dentro del límite de 5 rps.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`email`	string	No*	Correo electrónico de trabajo
`linkedin_url`	string	No*	URL del perfil de LinkedIn
`first_name`	string	No*	Nombre (requiere `last_name` + `company_domain`)
`last_name`	string	No*	Apellido (requiere `first_name` + `company_domain`)
`company_domain`	string	No*	Dominio de la empresa (requiere `first_name` + `last_name`)

*Se requiere al menos una estrategia de búsqueda.

curl -X POST "https://be.graph8.com/api/v1/enrichment/lookup/person" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

response = requests.post(
    f"{BASE_URL}/enrichment/lookup/person",
    headers=HEADERS,
    json={"email": "[email protected]"}
)

Respuesta

{
  "data": {
    "found": true,
    "confidence": 0.95,
    "data": {
      "first_name": "Jane",
      "last_name": "Doe",
      "job_title": "VP of Sales",
      "company": "Acme Inc",
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "work_email": "[email protected]"
    }
  }
}

Company Lookup

POST /enrichment/lookup/company

Búsqueda instantánea de empresa por dominio o nombre.

Precios: 2 créditos en PAYG. Gratuito en Platform dentro del límite de 5 rps.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`domain`	string	No*	Dominio de la empresa
`name`	string	No*	Nombre de la empresa

*Se requiere al menos uno de los siguientes: domain o name.

Ejemplo

cURL
Python

curl -X POST "https://be.graph8.com/api/v1/enrichment/lookup/company" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

response = requests.post(
    f"{BASE_URL}/enrichment/lookup/company",
    headers=HEADERS,
    json={"domain": "acme.com"}
)

Respuesta

{
  "data": {
    "found": true,
    "confidence": 0.98,
    "data": {
      "name": "Acme Inc",
      "domain": "acme.com",
      "industry": "Technology",
      "employee_count": 500,
      "annual_revenue": "$50M-$100M"
    }
  }
}

Iniciar trabajo de enriquecimiento

POST /enrichment/enrich

Inicia un trabajo de enriquecimiento en cascada de forma asíncrona. El trabajo se ejecuta a través de varios proveedores de datos y devuelve un job_id que puede consultar para obtener los resultados.

Devuelve 202 Accepted.

Precios: los créditos aplican tanto en PAYG como en Platform. El enriquecimiento en cascada utiliza proveedores externos (Prospeo, Dropcontact, Cognism, etc.) con costo por registro. El costo varía según los proveedores configurados en fields_config.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`contact_ids`	integer[]	Sí	IDs de los contactos a enriquecer
`list_id`	integer	Sí	ID de la lista a la que pertenecen los contactos
`fields_config`	object	No	Campos a enriquecer y orden de proveedores (ver más abajo)

Ejemplo de fields_config:

{
  "work_email": ["prospeo", "dropcontact"],
  "direct_phone": ["cognism", "lusha"]
}

Si se omite, el valor predeterminado es {"work_email": ["prospeo", "dropcontact"]}.

Ejemplo

cURL
Python

curl -X POST "https://be.graph8.com/api/v1/enrichment/enrich" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [101, 102, 103],
    "list_id": 5,
    "fields_config": {"work_email": ["prospeo", "dropcontact"]}
  }'

response = requests.post(
    f"{BASE_URL}/enrichment/enrich",
    headers=HEADERS,
    json={
        "contact_ids": [101, 102, 103],
        "list_id": 5,
        "fields_config": {"work_email": ["prospeo", "dropcontact"]}
    }
)
job_id = response.json()["data"]["job_id"]

Respuesta

{
  "data": {
    "job_id": "abc-123-def",
    "status": "queued"
  }
}

Consultar estado del trabajo de enriquecimiento

GET /enrichment/jobs/{job_id}

Consulta el estado de un trabajo de enriquecimiento.

Valores de estado

Estado	Descripción
`queued`	El trabajo está en espera para iniciar
`running`	Enriquecimiento en curso
`completed`	Todos los contactos procesados
`failed`	El trabajo falló

Ejemplo

cURL
Python

curl "https://be.graph8.com/api/v1/enrichment/jobs/abc-123-def" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/enrichment/jobs/{job_id}",
    headers=HEADERS
)
status = response.json()["data"]["status"]

Respuesta

{
  "data": {
    "job_id": "abc-123-def",
    "status": "completed"
  }
}

Verificar correo electrónico

POST /enrichment/verify-email

Verifica una dirección de correo electrónico individual y comprueba su estado de entregabilidad.

Precios: 1 crédito en PAYG. Gratuito en Platform dentro del límite de 5 rps cuando el validador interno de graph8 puede responder. Las llamadas que se derivan a verificadores externos (Kickbox, ZeroBounce) consumen créditos en ambos planes.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de correo electrónico a verificar

Ejemplo

cURL
Python

curl -X POST "https://be.graph8.com/api/v1/enrichment/verify-email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

response = requests.post(
    f"{BASE_URL}/enrichment/verify-email",
    headers=HEADERS,
    json={"email": "[email protected]"}
)

Respuesta

{
  "data": {
    "email": "[email protected]",
    "status": "valid",
    "sub_status": null,
    "is_valid": true
  }
}

Estado	Descripción
`valid`	Dirección de correo entregable
`invalid`	No entregable
`catch-all`	El dominio acepta todas las direcciones
`unknown`	No se pudo determinar