# Enriquecimiento

> Busque contactos y empresas, ejecute enriquecimiento en cascada y verifique correos electrónicos

Source: https://docs.graph8.com/es/developers/enrichment/

> **Tip: ¿Usa el SDK?**
> El [SDK de JavaScript](https://docs.graph8.com/developers/sdk/#enrichment) envuelve estos endpoints con tipos TypeScript: `g8.enrich.person()`, `g8.enrich.company()`, `g8.enrich.verifyEmail()`. El [CLI](https://docs.graph8.com/developers/cli/#g8-lookup-person) también admite `g8 lookup-person` y `g8 lookup-company`.

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.

> **Tip: Lookup vs Search**
> **Lookup** encuentra una persona o empresa específica mediante un identificador conocido (correo electrónico, URL de LinkedIn, dominio). Si necesita encontrar **varios** contactos o empresas que coincidan con criterios como cargo, industria o tamaño de empresa, utilice los endpoints de [Search](https://docs.graph8.com/developers/search/) en su lugar.

## 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: 2 créditos cada uno

Estos endpoints consultan los índices propios de graph8 (OpenSearch + ClickHouse). Registro único, instantáneo, sin cascada. Una búsqueda solo se cobra cuando encuentra una coincidencia; si no encuentra nada (`found: false`), no cuesta créditos.

| Endpoint | PAYG | Platform |
|---|---|---|
| `POST /enrichment/lookup/person` | 2 créditos | 2 créditos |
| `POST /enrichment/lookup/company` | 2 créditos | 2 créditos |
| `POST /enrichment/verify-email` | 1 crédito | 1 crédito |

### 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](https://docs.graph8.com/developers/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.

### Ejemplo

**cURL**

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

**Python**

```python
response = requests.post(
    f"{BASE_URL}/enrichment/lookup/person",
    headers=HEADERS,
    json={"email": "jane@acme.com"}
)
```

### Respuesta

```json
{
  "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": "jane@acme.com"
    }
  }
}
```

---

## 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**

```bash
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"}'
```

**Python**

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

### Respuesta

```json
{
  "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:**
```json
{
  "work_email": ["prospeo", "dropcontact"],
  "direct_phone": ["cognism", "lusha"]
}
```

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

### Ejemplo

**cURL**

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

**Python**

```python
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

```json
{
  "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**

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

**Python**

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

### Respuesta

```json
{
  "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 por verificación en ambos planes. Si la llamada al verificador falla, la respuesta llega con `status: "unknown"` y no se cobra nada.

### Cuerpo de la solicitud

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

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/enrichment/verify-email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@acme.com"}'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/enrichment/verify-email",
    headers=HEADERS,
    json={"email": "jane@acme.com"}
)
```

### Respuesta

```json
{
  "data": {
    "email": "jane@acme.com",
    "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 |