> ## 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 contatos > Liste contatos completos do Instagram de uma conta ou encontre a correspondência exata de um nome de usuário, com paginação por cursor. Este endpoint retorna os registros completos dos contatos de uma conta do Instagram. Use-o para criar um índice de contatos, sincronizar dados ou encontrar um contato pelo nome de usuário exato do Instagram. ## Acesso Sua chave de API precisa do escopo `contacts:read_pii`. O parâmetro de consulta `account_id` deve identificar uma conta do Instagram que a chave possa acessar. Os endpoints padrão de contatos já incluem informações de identificação pessoal (PII). A API v1 não tem variantes separadas para PII. As leituras de contatos passam por auditoria, e a API falhará sem retornar os dados se não conseguir registrar a entrada de auditoria obrigatória. ## Dados retornados Cada item contém estes grupos de campos: | Dados | Campos | | - | - | | Identidade | `id`, `account_id`, `instagram_user_id`, `username`, `name` | | Perfil do Instagram | `profile_picture_url`, `biography`, `website`, `followers_count`, `follows_count`, `media_count`, `account_type`, `is_verified`, `is_user_follow_business` | | Contato e entrega | `email`, `phone`, `opt_out`, `opt_out_at`, `blocked`, `blocked_at` | | Enriquecimento | `enrichment_status`, `last_enriched_at`, `last_enrichment_attempt_at` | | Timestamps de atividade | `first_seen_at`, `last_seen_at`, `created_at`, `updated_at` | | Dados relacionados | `tags`, `attributes` | | Ações do Instagram | `instagram_profile_url`, `send_instagram_dm_url` | `tags` contém até 100 tags atribuídas, cada uma com um UUID estável e um nome normalizado. `attributes` contém até 1.000 valores capturados com `id`, `key`, `value`, `source`, `source_ref`, `created_at` e `updated_at`. O enum `source` explica como um atributo foi registrado: * `capture`: uma regra de captura da automação registrou o valor. * `lead_capture`: o contato forneceu o valor em uma etapa de captura de lead. * `manual`: alguém definiu o valor manualmente. O enum `account_type` pode ser `PERSONAL`, `BUSINESS`, `CREATOR` ou `UNKNOWN`. Ele também pode ser `null` quando o Instagram não tiver retornado um tipo de conta. O enum `enrichment_status` descreve os dados do perfil: * `pending`: o enriquecimento do perfil ainda não foi concluído. * `fresh`: os dados de enriquecimento estão atualizados. * `stale`: os dados de enriquecimento precisam ser atualizados. * `failed`: a tentativa mais recente de enriquecimento falhou. Os campos anuláveis que não estiverem disponíveis retornarão `null`. Isso inclui campos de PII, como `email` e `phone`. A projeção da lista não inclui linhas do tempo de atividades. Use [Consultar um contato](/pt-BR/api/v1/contacts/get) quando também precisar de `timeline`. ## URLs de ação do Instagram A levios deriva duas URLs somente de leitura a partir do `username` canônico: * `instagram_profile_url`, por exemplo `https://instagram.com/levios_demo_account` * `send_instagram_dm_url`, por exemplo `https://ig.me/m/levios_demo_account` Os dois campos serão `null` quando o contato não tiver um nome de usuário válido do Instagram. Você pode enviar essas URLs a um cliente com acesso a um navegador para abrir o perfil ou iniciar uma mensagem direta. ## Encontre um nome de usuário exato do Instagram Defina o parâmetro de consulta opcional `instagram_username` com o nome de usuário exato. A correspondência não diferencia letras maiúsculas e minúsculas, e um `@` inicial é aceito. Espaços em branco, correspondências parciais e nomes de usuário do Instagram malformados são rejeitados. ```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' ``` O filtro faz uma busca exata, não uma pesquisa por prefixo ou trecho. ## Paginação Defina `limit` com um valor de 1 a 50. Quando `next_cursor` não for `null`, envie-o sem alterações como `cursor` com o mesmo `account_id` e o mesmo filtro `instagram_username`. Trate o cursor como opaco e pare quando `next_cursor` for `null`. Não reutilize um cursor com outra conta ou outro filtro de nome de usuário. Como esta resposta inclui dados pessoais, evite registrar payloads completos em logs, eventos de analytics ou relatórios de erro. ## 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.