Get a contact

GET

api

contacts

{contactId}

Get a contact

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

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

fetch('https://levios.app/api/v1/contacts/{contactId}', 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_contact_not_found",
    "message": "The requested contact was not found.",
    "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_invalid_cursor",
    "message": "The contact timeline cursor is invalid.",
    "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 one complete contact record and a page of its activity timeline. Use the contact UUID from List contacts as contactId.

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, and contactId must belong to that account. This endpoint includes personally identifiable information (PII) and is audited. The API fails without returning the contact if it cannot record the required audit entry.

Returned data

The contact object contains every field returned by the contact list, including email, phone, biography, website, tags, attributes, instagram_profile_url, and send_instagram_dm_url. It also contains a timeline object. See List contacts for the complete field groups and enum meanings. The timeline.items array can contain these event types:

first_contact: levios recorded the contact’s first activity.
dm_sent: a direct message was sent.
dm_failed: a direct message failed.
tag_applied: a tag was added to the contact.
attribute_captured: a contact attribute was captured.

Each timeline item includes id, type, and timestamp.

Example request

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

Timeline pagination

Set timeline_limit to a value from 1 through 50. When contact.timeline.next_cursor is not null, send it unchanged as timeline_cursor with the same account_id and contactId. Stop when the cursor is null. Treat timeline cursors as opaque. Do not reuse a cursor for another contact or account. Because this response includes personal data, avoid writing the full payload to logs, analytics events, or error reports.

Authorizations

Authorization

string

header

required

Levios API key sent as a Bearer token.

Path Parameters

contactId

string<uuid>

required

Query Parameters

account_id

string<uuid>

required

timeline_cursor

string

Required string length: 1 - 2048

timeline_limit

string

Response

Successful response.

Get a contact

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

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

fetch('https://levios.app/api/v1/contacts/{contactId}', 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_contact_not_found",
    "message": "The requested contact was not found.",
    "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_invalid_cursor",
    "message": "The contact timeline cursor is invalid.",
    "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

Example request

Authorizations

Path Parameters

Query Parameters

Response

​Access

​Returned data

​Example request

​Timeline pagination

Authorizations

Path Parameters

Query Parameters

Response

Access

Returned data

Example request

Timeline pagination