Contactos

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, 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.

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

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

# 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"}
)

// 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

{
  "data": [
    {
      "id": 1,
      "first_name": "Jane",
      "last_name": "Smith",
      "work_email": "[email protected]",
      "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 "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"

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

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

Respuesta

{
  "data": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Smith",
    "full_name": "Jane Smith",
    "work_email": "[email protected]",
    "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 -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": "[email protected]",
    "job_title": "CTO",
    "company_domain": "techcorp.io"
  }'

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

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: "[email protected]",
    job_title: "CTO",
    company_domain: "techcorp.io"
  })
});
const { data: result } = await response.json();

Respuesta `201 Created`

{
  "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 -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"}'

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

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

{
  "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 -X DELETE "https://be.graph8.com/api/v1/contacts/1" \
  -H "Authorization: Bearer $API_KEY"

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

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

Respuesta

{
  "data": {
    "deleted": true
  }
}

Errores

Estado	Significado
`404`	Contacto no encontrado

Contactos

Listar contactos

Parámetros de consulta

Ejemplo

Respuesta

Obtener contacto

Parámetros de ruta

Ejemplo

Respuesta

Errores

Crear contacto

Cuerpo de la solicitud

Ejemplo

Respuesta 201 Created

Actualizar contacto

Parámetros de ruta

Cuerpo de la solicitud

Ejemplo

Respuesta

Errores

Eliminar contacto

Parámetros de ruta

Ejemplo

Respuesta

Errores

Respuesta `201 Created`