Listar contatos

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

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.

Autorizações

Authorization

string

header

obrigatório

Levios API key sent as a Bearer token.

Parâmetros de consulta

account_id

string<uuid>

obrigatório

cursor

string

Required string length: 1 - 1024

limit

string

Resposta

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

Referência

Automações

Contas

Contatos

Tags de contato

Métricas

Listar contatos

Acesso

Dados retornados

URLs de ação do Instagram

Encontre um nome de usuário exato do Instagram

Paginação

Autorizações

Parâmetros de consulta

Resposta

​Acesso

​Dados retornados

​URLs de ação do Instagram

​Encontre um nome de usuário exato do Instagram

​Paginação

Autorizações

Parâmetros de consulta

Resposta

Acesso

Dados retornados

URLs de ação do Instagram

Encontre um nome de usuário exato do Instagram

Paginação