# Contactos

> Listar, crear, actualizar y eliminar contactos en su espacio de trabajo

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

> **Tip: ¿Utiliza el SDK o la CLI?**
> La [CLI](https://docs.graph8.com/developers/cli/#g8-search-contacts) admite `g8 search-contacts`, `g8 create-contact` y `g8 add-to-list`. El [SDK de JavaScript](https://docs.graph8.com/developers/sdk/) rastrea visitantes e identifica usuarios mediante `g8.identify()`.

Administre los contactos de su espacio de trabajo en graph8: sus datos de CRM propios.

Los contactos llegan a su espacio de trabajo por varias vías: guardando resultados de los endpoints de [Search](https://docs.graph8.com/developers/search/), importando desde un CSV o CRM, creándolos manualmente mediante la API, o de forma automática durante el enriquecimiento. Una vez que un contacto está en su espacio de trabajo, estos endpoints le otorgan acceso completo de lectura y escritura sin consumir créditos.

> **Tip: ¿Busca nuevos contactos?**
> Estos endpoints solo devuelven los contactos **que usted ya tiene**. Para descubrir nuevos contactos en la base de datos B2B global de graph8, utilice los endpoints de [Search](https://docs.graph8.com/developers/search/).

---

## Listar contactos

`GET /contacts`

Devuelve una lista paginada de contactos.

### Parámetros de consulta

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|----------------|-------------|
| `page` | integer | `1` | Número de página (índice desde 1) |
| `limit` | integer | `50` | Elementos por página (1-200) |
| `email` | string | — | Filtrar por correo laboral (coincidencia exacta) |
| `list_id` | integer | — | Filtrar por membresía en lista |
| `name` | string | — | Filtrar por nombre o apellido (coincidencia parcial, sin distinción de mayúsculas) |
| `job_title` | string | — | Filtrar por cargo (coincidencia parcial, sin distinción de mayúsculas) |
| `seniority_level` | string | — | Filtrar por nivel de antigüedad (coincidencia exacta) |
| `company_name` | string | — | Filtrar por nombre de empresa (coincidencia parcial, sin distinción de mayúsculas) |
| `company_id` | integer | — | Filtrar por ID de empresa |
| `country` | string | — | Filtrar por país (coincidencia exacta) |
| `state` | string | — | Filtrar por estado (coincidencia exacta) |
| `city` | string | — | Filtrar por ciudad (coincidencia parcial, sin distinción de mayúsculas) |
| `job_department` | string | — | Filtrar por departamento (coincidencia parcial, sin distinción de mayúsculas) |
| `industry` | string | — | Filtrar por industria de la empresa (coincidencia parcial, sin distinción de mayúsculas) |

Todos los filtros son opcionales y se pueden combinar. Cuando se proporcionan varios filtros, los resultados deben cumplir todos ellos (lógica AND).

### Ejemplo

**cURL**

```bash
# Basic pagination
curl "https://be.graph8.com/api/v1/contacts?limit=10&page=1" \
  -H "Authorization: Bearer $API_KEY"

# Search by name and company
curl "https://be.graph8.com/api/v1/contacts?name=jane&company_name=acme" \
  -H "Authorization: Bearer $API_KEY"

# Filter by seniority and country
curl "https://be.graph8.com/api/v1/contacts?seniority_level=VP&country=US" \
  -H "Authorization: Bearer $API_KEY"

# Filter by department and industry
curl "https://be.graph8.com/api/v1/contacts?job_department=Engineering&industry=SaaS" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
# Basic pagination
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"limit": 10, "page": 1}
)
contacts = response.json()

# Search by name and company
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"name": "jane", "company_name": "acme"}
)

# Filter by department and industry
response = requests.get(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    params={"job_department": "Engineering", "industry": "SaaS"}
)
```

**TypeScript**

```typescript
// Basic pagination
const response = await fetch(`${BASE_URL}/contacts?limit=10&page=1`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const contacts = await response.json();

// Search by name and company
const filtered = await fetch(
  `${BASE_URL}/contacts?name=jane&company_name=acme`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

// Filter by department and industry
const deptFiltered = await fetch(
  `${BASE_URL}/contacts?job_department=Engineering&industry=SaaS`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
```

### Respuesta

```json
{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "work_email": "jane@acme.com",
      "direct_phone": "+1-555-0100",
      "mobile_phone": null,
      "job_title": "VP of Engineering",
      "job_department": "Engineering",
      "seniority_level": "VP",
      "linkedin_url": "https://linkedin.com/in/janesmith",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "company_id": 42
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 243,
    "has_next": true
  }
}
```

---

## Obtener contacto

`GET /contacts/{contact_id}`

Devuelve información detallada sobre un contacto individual, incluidos los datos de la empresa asociada.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `contact_id` | integer | ID del contacto |

### Ejemplo

**cURL**

```bash
curl "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.get(f"{BASE_URL}/contacts/1", headers=HEADERS)
contact = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/contacts/1`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { data: contact } = await response.json();
```

### Respuesta

```json
{
  "data": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith",
    "full_name": "Jane Smith",
    "work_email": "jane@acme.com",
    "personal_emails": null,
    "direct_phone": "+1-555-0100",
    "mobile_phone": null,
    "job_title": "VP of Engineering",
    "job_department": "Engineering",
    "seniority_level": "VP",
    "linkedin_url": "https://linkedin.com/in/janesmith",
    "twitter_url": null,
    "facebook_url": null,
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "about": null,
    "confidence_score": 0.95,
    "company": {
      "id": 42,
      "name": "Acme Inc",
      "domain": "acme.com",
      "website": "https://acme.com",
      "industry": "Technology",
      "employee_count": "500",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "linkedin_url": "https://linkedin.com/company/acme",
      "logo_url": "https://logo.clearbit.com/acme.com"
    },
    "meta_data": null,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-01T14:20:00Z"
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `404` | Contacto no encontrado |

---

## Crear contacto

`POST /contacts`

Crea un nuevo contacto y lo agrega a una lista.

### Cuerpo de la solicitud

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `list_id` | integer | **Sí** | Lista de destino a la que se agrega el contacto |
| `first_name` | string | No | Nombre |
| `last_name` | string | No | Apellido |
| `work_email` | string | No | Correo electrónico laboral |
| `personal_emails` | string | No | Correos electrónicos personales |
| `direct_phone` | string | No | Número de teléfono directo |
| `mobile_phone` | string | No | Número de teléfono móvil |
| `job_title` | string | No | Cargo |
| `job_department` | string | No | Departamento |
| `seniority_level` | string | No | Nivel de antigüedad |
| `linkedin_url` | string | No | URL del perfil de LinkedIn |
| `city` | string | No | Ciudad |
| `state` | string | No | Estado o provincia |
| `country` | string | No | País |
| `company_domain` | string | No | Dominio de la empresa para la coincidencia |

### Ejemplo

**cURL**

```bash
curl -X POST "https://be.graph8.com/api/v1/contacts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 5,
    "first_name": "John",
    "last_name": "Doe",
    "work_email": "john@techcorp.io",
    "job_title": "CTO",
    "company_domain": "techcorp.io"
  }'
```

**Python**

```python
response = requests.post(
    f"{BASE_URL}/contacts",
    headers=HEADERS,
    json={
        "list_id": 5,
        "first_name": "John",
        "last_name": "Doe",
        "work_email": "john@techcorp.io",
        "job_title": "CTO",
        "company_domain": "techcorp.io"
    }
)
result = response.json()["data"]
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/contacts`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    list_id: 5,
    first_name: "John",
    last_name: "Doe",
    work_email: "john@techcorp.io",
    job_title: "CTO",
    company_domain: "techcorp.io"
  })
});
const { data: result } = await response.json();
```

### Respuesta `201 Created`

```json
{
  "data": {
    "status": "success",
    "count": 1,
    "validation_errors": []
  }
}
```

---

## Actualizar contacto

`PATCH /contacts/{contact_id}`

Actualiza uno o más campos de un contacto. Incluya solo los campos que desea modificar.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `contact_id` | integer | ID del contacto |

### Cuerpo de la solicitud

Todos los campos son opcionales. Incluya únicamente los campos que desea actualizar.

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `first_name` | string | Nombre |
| `last_name` | string | Apellido |
| `work_email` | string | Correo electrónico laboral |
| `direct_phone` | string | Número de teléfono directo |
| `mobile_phone` | string | Número de teléfono móvil |
| `job_title` | string | Cargo |
| `job_department` | string | Departamento |
| `seniority_level` | string | Nivel de antigüedad |
| `linkedin_url` | string | URL del perfil de LinkedIn |
| `city` | string | Ciudad |
| `state` | string | Estado o provincia |
| `country` | string | País |

### Ejemplo

**cURL**

```bash
curl -X PATCH "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "CTO", "city": "New York"}'
```

**Python**

```python
response = requests.patch(
    f"{BASE_URL}/contacts/1",
    headers=HEADERS,
    json={"job_title": "CTO", "city": "New York"}
)
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/contacts/1`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ job_title: "CTO", city: "New York" })
});
```

### Respuesta

```json
{
  "data": {
    "updated": 1
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `400` | No se proporcionaron campos para actualizar |
| `404` | Contacto no encontrado |

---

## Eliminar contacto

`DELETE /contacts/{contact_id}`

Elimina un contacto de forma lógica. El contacto se marca como eliminado, pero no se borra de forma permanente.

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `contact_id` | integer | ID del contacto |

### Ejemplo

**cURL**

```bash
curl -X DELETE "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
response = requests.delete(f"{BASE_URL}/contacts/1", headers=HEADERS)
```

**TypeScript**

```typescript
const response = await fetch(`${BASE_URL}/contacts/1`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${API_KEY}` }
});
```

### Respuesta

```json
{
  "data": {
    "deleted": true
  }
}
```

### Errores

| Estado | Significado |
|--------|-------------|
| `404` | Contacto no encontrado |

> **Caution:**
> Los contactos eliminados no pueden restaurarse mediante la API. Comuníquese con soporte si necesita recuperar datos eliminados.