# Descripción general de la REST API

> Acceso programático a los datos de CRM, enriquecimiento y prospección de graph8

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

> **Tip: ¿Nuevo en graph8?**
> Comience con la guía de [Primeros pasos](https://docs.graph8.com/developers/getting-started/) para elegir la ruta de integración correcta (SDK, MCP, CLI o REST API).

> **Tip:**
> Pruebe el nivel para desarrolladores de forma gratuita: 1,000 créditos, sin necesidad de tarjeta. [Comenzar](https://auth.graph8.com/en/signup).
>
> Agentes de IA: obtenga el índice completo de documentación en [https://docs.graph8.com/llms.txt](https://docs.graph8.com/llms.txt).

La REST API le brinda acceso HTTP directo a contactos, empresas, listas, enriquecimiento, búsqueda, secuencias y webhooks. Cualquier lenguaje de programación, cualquier plataforma.

## Referencia rápida

- **URL base:** `https://be.graph8.com/api/v1`
- **Autenticación:** `Authorization: Bearer YOUR_API_KEY` ([detalles](https://docs.graph8.com/developers/authentication/))
- **Formato:** Solicitud/respuesta en JSON
- **Documentación:** [Swagger interactivo →](https://be.graph8.com/api/v1/docs)

**Contactos**

    Liste, cree, actualice y elimine contactos en su espacio de trabajo.
    [Ver referencia →](https://docs.graph8.com/developers/contacts/)

**Empresas**

    Liste, actualice y elimine empresas, junto con sus contactos asociados.
    [Ver referencia →](https://docs.graph8.com/developers/companies/)

**Búsqueda**

    Encuentre contactos y empresas en la base de datos global de graph8, con más de 700M de registros.
    [Ver referencia →](https://docs.graph8.com/developers/search/)

**Enriquecimiento**

    Busque personas y empresas, ejecute enriquecimiento en cascada y verifique correos electrónicos.
    [Ver referencia →](https://docs.graph8.com/developers/enrichment/)

**Listas**

    Cree listas, gestione membresías y organice contactos para campañas.
    [Ver referencia →](https://docs.graph8.com/developers/lists/)

**Secuencias**

    Liste, ejecute y gestione secuencias de correo electrónico automatizadas.
    [Ver referencia →](https://docs.graph8.com/developers/sequences/)

También: [Notas](https://docs.graph8.com/developers/notes/) | [Tareas](https://docs.graph8.com/developers/tasks/) | [Campos](https://docs.graph8.com/developers/fields/) | [Oportunidades](https://docs.graph8.com/developers/deals/) | [Assert/Upsert](https://docs.graph8.com/developers/assert/) | [Webhooks](https://docs.graph8.com/developers/webhooks/)

**Engagement:** [Ciclo de vida de secuencias](https://docs.graph8.com/developers/sequences-lifecycle/) | [Bandeja de entrada](https://docs.graph8.com/developers/inbox/)

**GTM:** [Campañas GTM](https://docs.graph8.com/developers/gtm-campaigns/) | [Contexto GTM](https://docs.graph8.com/developers/gtm-context/)

**Sincronización:** [Sincronización de audiencias](https://docs.graph8.com/developers/audience-syncs/) | [Sincronización de CRM](https://docs.graph8.com/developers/crm-syncs/)

**Público (navegador, write key):** [Endpoints públicos](https://docs.graph8.com/developers/public-endpoints/)

**Referencia:** [Precios](https://docs.graph8.com/developers/pricing/) | [Paginación](https://docs.graph8.com/developers/pagination/) | [Errores](https://docs.graph8.com/developers/errors/) | [Límites de velocidad](https://docs.graph8.com/developers/rate-limits/)

---

La API para desarrolladores de graph8 le permite descubrir nuevos prospectos, gestionar los datos de su CRM y enriquecer la información de contactos de forma programática, todo a través de una única REST API.

## Cómo funcionan los datos en graph8

graph8 le brinda acceso a **dos conjuntos de datos diferenciados**. Comprender la diferencia es clave para utilizar la API de manera efectiva.

### Sus datos (propios)

Estos son datos **de su propiedad**: contactos y empresas que residen en su espacio de trabajo de graph8. Llegaron allí mediante una de estas vías:

- **Guardó resultados de búsqueda** del índice de datos abiertos (mediante [`/search/contacts/save`](https://docs.graph8.com/developers/search/#save-contacts-to-list))
- **Importó** contactos desde un CSV o una integración de CRM
- Los **creó** manualmente mediante la API (con [`POST /contacts`](https://docs.graph8.com/developers/contacts/#create-contact))
- Se **crearon automáticamente** durante flujos de trabajo de enriquecimiento o campañas

Usted tiene acceso completo de lectura y escritura sobre sus datos. Consúltelos, actualícelos, elimínelos u organícelos en listas, sin costo en créditos.

**Endpoints**: [`/contacts`](https://docs.graph8.com/developers/contacts/), [`/companies`](https://docs.graph8.com/developers/companies/), [`/lists`](https://docs.graph8.com/developers/lists/)

### Índice de datos abiertos

Esta es la **base de datos B2B global** de graph8: millones de contactos y empresas agregados desde múltiples proveedores de datos. Piense en ella como una guía telefónica del mundo empresarial: nombres, cargos, correos electrónicos, números de teléfono, datos de empresas y mucho más.

Puede **buscar** en este índice con filtros (cargo, industria, tamaño de empresa, ubicación, etc.) y **guardar** los resultados coincidentes en su espacio de trabajo. Una vez guardados, pasan a ser sus datos.

También puede **consultar** a una persona o empresa por correo electrónico, URL de LinkedIn o dominio.

Las consultas al índice de datos abiertos consumen créditos.

**Endpoints**: [`/search/contacts`](https://docs.graph8.com/developers/search/), [`/search/companies`](https://docs.graph8.com/developers/search/#search-companies), [`/enrichment/lookup`](https://docs.graph8.com/developers/enrichment/)

### El flujo de datos

El flujo de trabajo típico traslada los datos de abiertos a propios:

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   1. DISCOVER            2. SAVE              3. MANAGE         │
│                                                                 │
│   /search/contacts  ──►  /search/.../save  ──►  /contacts      │
│   /search/companies      (creates a list)       /companies      │
│   /enrichment/lookup                            /lists          │
│                                                                 │
│   Open data index        Moves into your        Full CRUD on    │
│   (read-only, credits)   workspace as a list    your data (free)│
│                                                                 │
│                          4. ENRICH                              │
│                          /enrichment/enrich                     │
│                          Fill missing fields                    │
│                          on your saved contacts                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Cómo elegir el endpoint correcto

| Quiero... | Usar | PAYG | Plataforma |
|--------------|-----|------|----------|
| Encontrar nuevos contactos que coincidan con mi ICP | [`POST /search/contacts`](https://docs.graph8.com/developers/search/) | 1 por registro devuelto | **Gratuito** (dentro de 5 rps) |
| Encontrar nuevas empresas por industria, tamaño, etc. | [`POST /search/companies`](https://docs.graph8.com/developers/search/#search-companies) | 1 por registro devuelto | **Gratuito** (dentro de 5 rps) |
| Guardar resultados de búsqueda en mi espacio de trabajo | [`POST /search/contacts/save`](https://docs.graph8.com/developers/search/#save-contacts-to-list) | 1 por registro guardado | **Gratuito** (dentro de 5 rps) |
| Consultar a una persona por correo electrónico o LinkedIn | [`POST /enrichment/lookup/person`](https://docs.graph8.com/developers/enrichment/) | 2 por consulta | **Gratuito** (dentro de 5 rps) |
| Consultar una empresa por dominio | [`POST /enrichment/lookup/company`](https://docs.graph8.com/developers/enrichment/#company-lookup) | 2 por consulta | **Gratuito** (dentro de 5 rps) |
| Listar contactos ya guardados | [`GET /contacts`](https://docs.graph8.com/developers/contacts/) | Gratuito | Gratuito |
| Listar empresas en mi espacio de trabajo | [`GET /companies`](https://docs.graph8.com/developers/companies/) | Gratuito | Gratuito |
| Gestionar mis listas | [`GET /lists`](https://docs.graph8.com/developers/lists/) | Gratuito | Gratuito |
| Completar correos o teléfonos faltantes en mis contactos (cascada) | [`POST /enrichment/enrich`](https://docs.graph8.com/developers/enrichment/#start-enrichment-job) | Variable por contacto | Variable por contacto |
| Verificar una dirección de correo electrónico (validador interno) | [`POST /enrichment/verify-email`](https://docs.graph8.com/developers/enrichment/#verify-email) | 1 por correo | **Gratuito** (dentro de 5 rps) |

Consulte [Precios](https://docs.graph8.com/developers/pricing/) para ver el mapa completo de créditos y la comparación de planes.

## URL base

```
https://be.graph8.com/api/v1
```

Todos los endpoints son relativos a esta URL base. Por ejemplo, para listar contactos:

```
GET https://be.graph8.com/api/v1/contacts
```

## Inicio rápido

**cURL**

```bash
export API_KEY="YOUR_API_KEY"

# 1. Search the open data index for CTOs at tech companies
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": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "limit": 5
  }'

# 2. Save matching contacts to a list in your workspace
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": ["CTO", "VP Engineering"]},
      {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
    ],
    "list_title": "Tech CTOs"
  }'

# 3. Query your saved contacts (free, no credits)
curl "https://be.graph8.com/api/v1/contacts?list_id=42&limit=10" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://be.graph8.com/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Search the open data index for CTOs at tech companies
results = requests.post(
    f"{BASE_URL}/search/contacts",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "limit": 5
    }
).json()

print(f"Found {results['pagination']['total']} matches")

# 2. Save matching contacts to a list in your workspace
save = requests.post(
    f"{BASE_URL}/search/contacts/save",
    headers=HEADERS,
    json={
        "filters": [
            {"field": "job_title", "operator": "any_of", "value": ["CTO", "VP Engineering"]},
            {"field": "company_employee_count", "operator": "between", "value": [50, 500]}
        ],
        "list_title": "Tech CTOs"
    }
).json()

list_id = save["data"]["list_id"]

# 3. Query your saved contacts (free, no credits)
contacts = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"list_id": list_id, "limit": 10}
).json()

for c in contacts["data"]:
    print(f"{c['first_name']} {c['last_name']} - {c['work_email']}")
```

**TypeScript**

```typescript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://be.graph8.com/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 1. Search the open data index for CTOs at tech companies
const results = await fetch(`${BASE_URL}/search/contacts`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    limit: 5
  }),
}).then(r => r.json());

console.log(`Found ${results.pagination.total} matches`);

// 2. Save matching contacts to a list in your workspace
const save = await fetch(`${BASE_URL}/search/contacts/save`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    filters: [
      { field: "job_title", operator: "any_of", value: ["CTO", "VP Engineering"] },
      { field: "company_employee_count", operator: "between", value: [50, 500] }
    ],
    list_title: "Tech CTOs"
  }),
}).then(r => r.json());

// 3. Query your saved contacts (free, no credits)
const contacts = await fetch(
  `${BASE_URL}/contacts?list_id=${save.data.list_id}&limit=10`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
).then(r => r.json());

contacts.data.forEach(c =>
  console.log(`${c.first_name} ${c.last_name} - ${c.work_email}`)
);
```

## Referencia de endpoints

### Descubrir (datos abiertos: créditos)

**Búsqueda**

    Encuentre contactos y empresas en la base de datos B2B global de graph8 usando filtros como cargo, industria, tamaño de empresa y ubicación.
    [Ver referencia](https://docs.graph8.com/developers/search/)

**Enriquecimiento**

    Consulte a una persona o empresa, ejecute enriquecimiento en cascada entre proveedores y verifique la entregabilidad del correo electrónico.
    [Ver referencia](https://docs.graph8.com/developers/enrichment/)

### Gestionar (sus datos: gratuito)

**Contactos**

    Liste, cree, actualice y elimine contactos en su espacio de trabajo.
    [Ver referencia](https://docs.graph8.com/developers/contacts/)

**Empresas**

    Liste, actualice y elimine empresas, junto con sus contactos asociados.
    [Ver referencia](https://docs.graph8.com/developers/companies/)

**Listas**

    Cree listas, gestione membresías y organice contactos para campañas.
    [Ver referencia](https://docs.graph8.com/developers/lists/)

### Referencia

**Precios**

    Planes, costos de créditos, el paquete de API ilimitada y el comportamiento de captura automática en el CRM.
    [Ver precios](https://docs.graph8.com/developers/pricing/)

**Autenticación**

    Cree claves de API y autentique sus solicitudes.
    [Comenzar](https://docs.graph8.com/developers/authentication/)

**Paginación**

    Estructura de respuesta y patrones de paginación.
    [Más información](https://docs.graph8.com/developers/pagination/)

**Errores**

    Códigos de error y estrategias de manejo.
    [Más información](https://docs.graph8.com/developers/errors/)

**Límites de velocidad**

    Límites de solicitudes y estrategias de reintento.
    [Más información](https://docs.graph8.com/developers/rate-limits/)

## Referencia interactiva de la API

Para una vista interactiva y en tiempo real de todos los endpoints, con esquemas de solicitud y respuesta, visite la documentación OpenAPI:

**[Abrir documentación interactiva de la API →](https://be.graph8.com/api/v1/docs)**

Puede probar los endpoints directamente desde el navegador: autentíquese con su clave de API y ejecute solicitudes en tiempo real.

## Formato de respuesta

Todas las respuestas utilizan una estructura estándar:

```json
{
  "data": { ... },
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 243,
    "has_next": true
  }
}
```

Las respuestas de un solo recurso incluyen `data` sin `pagination`. Consulte [Paginación](https://docs.graph8.com/developers/pagination/) para más detalles.