List contacts

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

This endpoint returns complete contact records for one Instagram account. Use it to build a contact index, synchronize contact data, or find a contact by an exact Instagram username.

Access

Your API key needs the contacts:read_pii scope. The account_id query parameter must identify an Instagram account that the key can access. The standard contact endpoints already include personally identifiable information (PII). There are no separate PII variants in API v1. Contact reads are audited, and the API fails without returning contact data if it cannot record the required audit entry.

Returned data

Each item contains these field groups:

Data	Fields
Identity	`id`, `account_id`, `instagram_user_id`, `username`, `name`
Instagram profile	`profile_picture_url`, `biography`, `website`, `followers_count`, `follows_count`, `media_count`, `account_type`, `is_verified`, `is_user_follow_business`
Contact and delivery	`email`, `phone`, `opt_out`, `opt_out_at`, `blocked`, `blocked_at`
Enrichment	`enrichment_status`, `last_enriched_at`, `last_enrichment_attempt_at`
Activity timestamps	`first_seen_at`, `last_seen_at`, `created_at`, `updated_at`
Related data	`tags`, `attributes`
Instagram actions	`instagram_profile_url`, `send_instagram_dm_url`

tags contains up to 100 assigned tags with a stable UUID and normalized name. attributes contains up to 1,000 captured values with id, key, value, source, source_ref, created_at, and updated_at. The source enum explains how an attribute was recorded:

capture: an automation capture rule recorded the value.
lead_capture: the contact provided the value in a lead-capture step.
manual: someone set the value manually.

The account_type enum can be PERSONAL, BUSINESS, CREATOR, or UNKNOWN. It can also be null when Instagram has not returned an account type. The enrichment_status enum describes the profile data:

pending: profile enrichment has not finished.
fresh: the enrichment data is current.
stale: the enrichment data needs to be refreshed.
failed: the most recent enrichment attempt failed.

Nullable fields that are not available return null. This includes PII fields such as email and phone. The list projection does not include activity timelines. Use Get a contact when you also need timeline.

Instagram action URLs

levios derives two read-only URLs from the canonical username:

instagram_profile_url, for example https://instagram.com/levios_demo_account
send_instagram_dm_url, for example https://ig.me/m/levios_demo_account

Both fields are null when the contact has no valid Instagram username. You can pass these URLs to a browser-capable client to open the profile or start a direct message.

Find an exact Instagram username

Set the optional instagram_username query parameter to an exact username. Matching is case-insensitive, and one leading @ is accepted. Whitespace, partial matches, and malformed Instagram usernames are rejected.

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'

The filter performs an exact lookup, not a search by prefix or substring.

Pagination

Set limit to a value from 1 through 50. When next_cursor is not null, send it unchanged as cursor with the same account_id and instagram_username filter. Treat the cursor as opaque and stop when next_cursor is null. Do not reuse a cursor with another account or username filter. Because this response includes personal data, avoid writing full payloads to logs, analytics events, or error reports.

Authorizations

Authorization

string

header

required

Levios API key sent as a Bearer token.

Query Parameters

account_id

string<uuid>

required

cursor

string

Required string length: 1 - 1024

limit

string

Response

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

Reference

Automations

Accounts

Contacts

Contact tags

Metrics

Access

Returned data

Instagram action URLs

Find an exact Instagram username

Authorizations

Query Parameters

Response

​Access

​Returned data

​Instagram action URLs

​Find an exact Instagram username

​Pagination

Authorizations

Query Parameters

Response

Access

Returned data

Instagram action URLs

Find an exact Instagram username

Pagination