Listar contactos

GET

api

contacts

List contacts

curl --request GET \
  --url https://levios.app/api/v1/contacts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://levios.app/api/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "error": {
    "code": "api_invalid_content_length",
    "message": "Invalid Content-Length.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_unauthorized",
    "message": "Authentication required.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_account_not_granted",
    "message": "This credential is not authorized for the request.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_body_too_large",
    "message": "The JSON request body exceeds 1 MiB.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_unsupported_media_type",
    "message": "Content-Type must be application/json.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_instagram_username_invalid",
    "message": "The Instagram username is malformed.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_internal_error",
    "message": "The request could not be completed.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_account_resolution_unavailable",
    "message": "The reachable account set could not be read.",
    "correlation_id": "<string>"
  }
}

Este endpoint devuelve los registros completos de los contactos de una cuenta de Instagram. Úsalo para crear un índice de contactos, sincronizar sus datos o buscar un contacto por su nombre de usuario exacto de Instagram.

Acceso

Tu clave de API necesita el permiso contacts:read_pii. El parámetro de consulta account_id debe identificar una cuenta de Instagram a la que pueda acceder la clave. Los endpoints estándar de contactos ya incluyen información de identificación personal (PII). La API v1 no tiene variantes separadas para PII. Las lecturas de contactos se auditan. Si la API no puede registrar la entrada de auditoría obligatoria, falla sin devolver datos de contactos.

Datos devueltos

Cada elemento contiene estos grupos de campos:

Datos	Campos
Identidad	`id`, `account_id`, `instagram_user_id`, `username`, `name`
Perfil de Instagram	`profile_picture_url`, `biography`, `website`, `followers_count`, `follows_count`, `media_count`, `account_type`, `is_verified`, `is_user_follow_business`
Contacto y entrega	`email`, `phone`, `opt_out`, `opt_out_at`, `blocked`, `blocked_at`
Enriquecimiento	`enrichment_status`, `last_enriched_at`, `last_enrichment_attempt_at`
Marcas de tiempo de actividad	`first_seen_at`, `last_seen_at`, `created_at`, `updated_at`
Datos relacionados	`tags`, `attributes`
Acciones de Instagram	`instagram_profile_url`, `send_instagram_dm_url`

tags contiene hasta 100 etiquetas asignadas, cada una con un UUID estable y un nombre normalizado. attributes contiene hasta 1.000 valores capturados con id, key, value, source, source_ref, created_at y updated_at. El enum source explica cómo se registró un atributo:

capture: una regla de captura de una automatización registró el valor.
lead_capture: el contacto proporcionó el valor en un paso de captura de leads.
manual: alguien estableció el valor manualmente.

El enum account_type puede ser PERSONAL, BUSINESS, CREATOR o UNKNOWN. También puede ser null si Instagram no ha devuelto un tipo de cuenta. El enum enrichment_status describe los datos del perfil:

pending: el enriquecimiento del perfil no ha terminado.
fresh: los datos de enriquecimiento están actualizados.
stale: los datos de enriquecimiento deben actualizarse.
failed: se produjo un error en el intento de enriquecimiento más reciente.

Los campos opcionales que no estén disponibles devuelven null. Esto incluye campos de PII como email y phone. La proyección de la lista no incluye cronologías de actividad. Usa Obtener un contacto cuando también necesites timeline.

URLs de acciones de Instagram

levios genera dos URLs de solo lectura a partir del username canónico:

instagram_profile_url, por ejemplo https://instagram.com/levios_demo_account
send_instagram_dm_url, por ejemplo https://ig.me/m/levios_demo_account

Ambos campos son null si el contacto no tiene un nombre de usuario válido de Instagram. Puedes pasar estas URLs a un cliente con acceso a un navegador para abrir el perfil o iniciar un mensaje directo.

Busca un nombre de usuario exacto de Instagram

Configura el parámetro de consulta opcional instagram_username con un nombre de usuario exacto. La comparación no distingue entre mayúsculas y minúsculas, y se acepta un solo @ al principio. Se rechazan los espacios en blanco, las coincidencias parciales y los nombres de usuario de Instagram con formato no válido.

curl --get \
  --url 'https://levios.app/api/v1/contacts' \
  --header "Authorization: Bearer ${LEVIOS_API_KEY}" \
  --data-urlencode "account_id=${LEVIOS_ACCOUNT_ID}" \
  --data-urlencode 'instagram_username=@levios_demo_account'

El filtro realiza una búsqueda exacta, no una búsqueda por prefijo ni por subcadena.

Paginación

Configura limit con un valor entre 1 y 50. Cuando next_cursor no sea null, envíalo sin cambios como cursor con los mismos account_id y filtro instagram_username. Trata el cursor como un valor opaco y detente cuando next_cursor sea null. No reutilices un cursor con otra cuenta u otro filtro de nombre de usuario. Como esta respuesta incluye datos personales, evita escribir cargas completas en registros, eventos de analítica o informes de errores.

Autorizaciones

Authorization

string

header

requerido

Levios API key sent as a Bearer token.

Parámetros de consulta

account_id

string<uuid>

requerido

cursor

string

Required string length: 1 - 1024

limit

string

Respuesta

Successful response.

List contacts

curl --request GET \
  --url https://levios.app/api/v1/contacts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://levios.app/api/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "error": {
    "code": "api_invalid_content_length",
    "message": "Invalid Content-Length.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_unauthorized",
    "message": "Authentication required.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_account_not_granted",
    "message": "This credential is not authorized for the request.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_body_too_large",
    "message": "The JSON request body exceeds 1 MiB.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_unsupported_media_type",
    "message": "Content-Type must be application/json.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_instagram_username_invalid",
    "message": "The Instagram username is malformed.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_internal_error",
    "message": "The request could not be completed.",
    "correlation_id": "<string>"
  }
}

{
  "error": {
    "code": "api_account_resolution_unavailable",
    "message": "The reachable account set could not be read.",
    "correlation_id": "<string>"
  }
}

Referencia

Automatizaciones

Cuentas

Contactos

Etiquetas de contacto

Métricas

Listar contactos

Acceso

Datos devueltos

URLs de acciones de Instagram

Busca un nombre de usuario exacto de Instagram

Paginación

Autorizaciones

Parámetros de consulta

Respuesta

​Acceso

​Datos devueltos

​URLs de acciones de Instagram

​Busca un nombre de usuario exacto de Instagram

​Paginación

Autorizaciones

Parámetros de consulta

Respuesta

Acceso

Datos devueltos

URLs de acciones de Instagram

Busca un nombre de usuario exacto de Instagram

Paginación