> ## Documentation Index > Fetch the complete documentation index at: https://docs.levios.app/llms.txt > Use this file to discover all available pages before exploring further. # Listar contactos > Lista contactos completos de Instagram de una cuenta o encuentra la coincidencia exacta de un usuario, con paginación por cursor. 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](/es/api/v1/contacts/get) 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. ```bash theme={null} 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. ## OpenAPI ````yaml openapi/v1.json GET /api/v1/contacts openapi: 3.1.0 info: title: levios public API version: '1' servers: - url: https://levios.app security: - bearerAuth: [] paths: /api/v1/contacts: get: tags: - contact summary: List contacts description: >- Returns full contact records for one Instagram account, with an optional exact Instagram username filter. operationId: contacts.list parameters: - name: account_id in: query required: true schema: type: string format: uuid - name: cursor in: query required: false schema: type: string minLength: 1 maxLength: 1024 - name: instagram_username in: query required: false schema: $ref: '#/components/schemas/PublicInstagramUsernameFilter' - name: limit in: query required: false schema: type: string responses: '200': description: Successful response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: $ref: '#/components/schemas/PublicContactPage' '400': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_content_length correlation_id: type: string message: type: string enum: - Invalid Content-Length. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_json correlation_id: type: string message: type: string enum: - The request body is not valid JSON. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_request_url correlation_id: type: string message: type: string enum: - The request URL is invalid. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_utf8 correlation_id: type: string message: type: string enum: - The request body is not valid UTF-8. required: - code - message additionalProperties: false required: - error additionalProperties: false '401': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ WWW-Authenticate: description: API key Bearer challenge. schema: type: string enum: - Bearer content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - api_unauthorized correlation_id: type: string message: type: string enum: - Authentication required. required: - code - message additionalProperties: false required: - error additionalProperties: false '403': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_account_not_granted correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_forbidden correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_scope_denied correlation_id: type: string message: type: string enum: - >- This credential is not authorized for the request. required: - code - message additionalProperties: false required: - error additionalProperties: false '413': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_body_too_large correlation_id: type: string message: type: string enum: - The JSON request body exceeds 1 MiB. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_json_too_deep correlation_id: type: string message: type: string enum: - The JSON request body exceeds maximum depth. required: - code - message additionalProperties: false required: - error additionalProperties: false '415': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - api_unsupported_media_type correlation_id: type: string message: type: string enum: - Content-Type must be application/json. required: - code - message additionalProperties: false required: - error additionalProperties: false '422': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_instagram_username_invalid correlation_id: type: string message: type: string enum: - The Instagram username is malformed. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_cursor correlation_id: type: string message: type: string enum: - >- The contact cursor is invalid for this account and filter. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_limit correlation_id: type: string message: type: string enum: - >- The page limit must be an integer between 1 and 50. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_validation_error correlation_id: type: string details: type: object properties: issues: type: array items: type: object properties: code: type: string minLength: 1 maxLength: 64 path: type: array items: type: integer minimum: 0 maxItems: 16 required: - code - path additionalProperties: false maxItems: 32 required: - issues additionalProperties: false message: type: string enum: - The request does not match the declared schema. required: - code - message additionalProperties: false required: - error additionalProperties: false '429': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - rate_limited correlation_id: type: string message: type: string enum: - Rate limit exceeded. required: - code - message additionalProperties: false required: - error additionalProperties: false '500': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_internal_error correlation_id: type: string message: type: string enum: - The request could not be completed. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_invalid_projection correlation_id: type: string message: type: string enum: - The contact projection is invalid. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_projection_too_large correlation_id: type: string message: type: string enum: - >- The projected result exceeds the result byte limit. required: - code - message additionalProperties: false required: - error additionalProperties: false '503': description: Error response. headers: X-Correlation-ID: description: Correlation identifier for this request. schema: type: string pattern: ^[0-9A-HJKMNP-TV-Z]{26}$ content: application/json: schema: oneOf: - type: object properties: error: type: object properties: code: type: string enum: - api_account_resolution_unavailable correlation_id: type: string message: type: string enum: - The reachable account set could not be read. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_audit_unavailable correlation_id: type: string message: type: string enum: - The security audit log is unavailable. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - api_contact_read_unavailable correlation_id: type: string message: type: string enum: - The contact data could not be read. required: - code - message additionalProperties: false required: - error additionalProperties: false - type: object properties: error: type: object properties: code: type: string enum: - rate_limiter_unavailable correlation_id: type: string message: type: string enum: - Rate limiter unavailable. required: - code - message additionalProperties: false required: - error additionalProperties: false components: schemas: PublicInstagramUsernameFilter: $ref: 0b1de94a-6d70-4bb1-b3d7-c9cd1beef334 $defs: PublicInstagramUsernameFilter: description: >- Exact Instagram username. One leading @ is accepted, whitespace is rejected, and matching is case-insensitive. pattern: >- ^@?(?=[A-Za-z0-9._]{1,30}$)(?=[A-Za-z0-9._]*[A-Za-z0-9][A-Za-z0-9._]*$)(?!\.)(?![A-Za-z0-9._]*\.\.)(?![A-Za-z0-9._]*\.$)[A-Za-z0-9._]+$ type: string $id: https://levios.app/schemas/public-instagram-username-filter-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicInstagramUsernameFilter x-levios-max-serialized-bytes: 65536 x-levios-schema-version: 1 PublicContactPage: $ref: 24b9314c-bcdf-4fca-9c58-f874db71724c $defs: PublicContactPage: additionalProperties: false properties: items: items: additionalProperties: false properties: account_id: format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string account_type: anyOf: - description: >- Values: `BUSINESS`: an Instagram business account; `CREATOR`: an Instagram creator account; `PERSONAL`: an Instagram personal account; `UNKNOWN`: the Instagram account type is unavailable. enum: - PERSONAL - BUSINESS - CREATOR - UNKNOWN type: string - type: 'null' attributes: items: additionalProperties: false properties: created_at: format: date-time type: string id: pattern: ^[1-9][0-9]{0,18}$ type: string key: maxLength: 100 minLength: 1 type: string source: description: >- Values: `capture`: derived from an automation capture rule; `lead_capture`: provided by the contact through a lead-capture step; `manual`: set manually. enum: - capture - lead_capture - manual type: string source_ref: anyOf: - maxLength: 200 minLength: 1 type: string - type: 'null' updated_at: format: date-time type: string value: anyOf: - maxLength: 10000 minLength: 0 type: string - type: 'null' required: - id - key - value - source - source_ref - created_at - updated_at type: object maxItems: 1000 type: array biography: anyOf: - maxLength: 100000 minLength: 1 type: string - type: 'null' blocked: type: boolean blocked_at: anyOf: - format: date-time type: string - type: 'null' created_at: format: date-time type: string email: anyOf: - maxLength: 320 minLength: 1 type: string - type: 'null' enrichment_status: description: >- Values: `failed`: the most recent enrichment attempt failed; `fresh`: the enrichment data is current; `pending`: profile enrichment has not finished; `stale`: the enrichment data needs to be refreshed. enum: - pending - fresh - stale - failed type: string first_seen_at: format: date-time type: string followers_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' follows_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' id: format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string instagram_profile_url: anyOf: - format: uri pattern: ^https://instagram\.com/[a-z0-9._]{1,30}$ type: string - type: 'null' description: >- Server-derived profile URL for the canonical username; null when username is absent or invalid. readOnly: true instagram_user_id: maxLength: 100 minLength: 1 type: string is_user_follow_business: anyOf: - type: boolean - type: 'null' is_verified: anyOf: - type: boolean - type: 'null' last_enriched_at: anyOf: - format: date-time type: string - type: 'null' last_enrichment_attempt_at: anyOf: - format: date-time type: string - type: 'null' last_seen_at: format: date-time type: string media_count: anyOf: - maximum: 9007199254740991 minimum: 0 type: integer - type: 'null' name: anyOf: - maxLength: 120 minLength: 1 type: string - type: 'null' opt_out: type: boolean opt_out_at: anyOf: - format: date-time type: string - type: 'null' phone: anyOf: - maxLength: 64 minLength: 1 type: string - type: 'null' profile_picture_url: anyOf: - maxLength: 2048 minLength: 1 type: string - type: 'null' send_instagram_dm_url: anyOf: - format: uri pattern: ^https://ig\.me/m/[a-z0-9._]{1,30}$ type: string - type: 'null' description: >- Server-derived Instagram DM URL for the canonical username; null when username is absent or invalid. readOnly: true tags: items: additionalProperties: false properties: id: description: >- Stable public tag UUID. Internal numeric catalog IDs are never exposed. format: uuid pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string name: description: >- Normalized tag name: trimmed, with consecutive whitespace collapsed to one ASCII space. maxLength: 50 minLength: 1 pattern: >- ^(?!.*\s{2})(?!\s)(?!.*\s$)(?!.*[\u0000-\u001F\u007F]).+$ type: string required: - id - name type: object maxItems: 100 type: array updated_at: format: date-time type: string username: anyOf: - pattern: >- ^(?=[a-z0-9._]{1,30}$)(?=[a-z0-9._]*[a-z0-9][a-z0-9._]*$)(?!\.)(?![a-z0-9._]*\.\.)(?![a-z0-9._]*\.$)[a-z0-9._]+$ type: string - type: 'null' website: anyOf: - maxLength: 2048 minLength: 1 type: string - type: 'null' required: - id - account_id - instagram_user_id - username - instagram_profile_url - send_instagram_dm_url - name - profile_picture_url - biography - website - followers_count - follows_count - media_count - account_type - is_verified - is_user_follow_business - email - phone - opt_out - opt_out_at - blocked - blocked_at - enrichment_status - first_seen_at - last_seen_at - last_enriched_at - last_enrichment_attempt_at - created_at - updated_at - tags - attributes type: object maxItems: 50 type: array next_cursor: anyOf: - maxLength: 1024 minLength: 1 type: string - type: 'null' required: - items - next_cursor type: object $id: https://levios.app/schemas/public-contact-page-v1 $schema: https://json-schema.org/draft/2019-09/schema# title: PublicContactPage x-levios-max-serialized-bytes: 65536 x-levios-schema-version: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: Levios API key sent as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.