List Identities

Retrieve a paginated list of visitor identities

GET /api/v1/identities

cURL

curl -X GET "https://api.orwel.io/api/v1/identities?limit=10&is_favorite=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.orwel.io/api/v1/identities?limit=10&is_favorite=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

params = {
    'limit': 10,
    'is_favorite': True
}

response = requests.get(
    'https://api.orwel.io/api/v1/identities',
    headers=headers,
    params=params
)

data = response.json()

Response

{
  "data": [
    {
      "id": "ee0e8400-e29b-41d4-a716-446655440009",
      "workspace_id": "770e8400-e29b-41d4-a716-446655440002",
      "visitor_id": "660e8400-e29b-41d4-a716-446655440001",
      "email": "[e-mail]",
      "name": "John Visitor",
      "traits": {
        "plan": "enterprise",
        "company": "Acme Corp"
      },
      "first_seen": "2025-01-10T08:00:00Z",
      "last_seen": "2025-01-15T16:30:00Z",
      "ip": "192.168.1.1",
      "city": "San Francisco",
      "country": "USA",
      "is_favorite": true,
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 250
  }
}

Query Parameters

limit · integer · default: "50"

Maximum number of results to return (max: 100)

offset · integer · default: "0"

Number of results to skip for pagination

email · string

Filter identities by email address

visitor_id · string

Filter identities by visitor ID (UUID)

is_favorite · boolean

Filter favorite identities (true/false)

created_after · string

Filter identities created after this date (ISO 8601 format)

created_before · string

Filter identities created before this date (ISO 8601 format)

Response

data · array

Array of visitor identity objects

Show Identity Object

id · string

Unique identifier for the identity

workspace_id · string

Workspace ID (always your workspace)

visitor_id · string

Associated visitor ID

email · string

Email address

name · string

Full name

traits · object

Custom traits (JSONB)

first_seen · string

ISO 8601 timestamp of first visit

last_seen · string

ISO 8601 timestamp of last visit

ip · string

IP address

city · string

City

country · string

Country

is_favorite · boolean

Whether identity is marked as favorite

created_at · string

ISO 8601 timestamp of creation

pagination · object

Pagination information

cURL

curl -X GET "https://api.orwel.io/api/v1/identities?limit=10&is_favorite=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.orwel.io/api/v1/identities?limit=10&is_favorite=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

params = {
    'limit': 10,
    'is_favorite': True
}

response = requests.get(
    'https://api.orwel.io/api/v1/identities',
    headers=headers,
    params=params
)

data = response.json()

Response

{
  "data": [
    {
      "id": "ee0e8400-e29b-41d4-a716-446655440009",
      "workspace_id": "770e8400-e29b-41d4-a716-446655440002",
      "visitor_id": "660e8400-e29b-41d4-a716-446655440001",
      "email": "[e-mail]",
      "name": "John Visitor",
      "traits": {
        "plan": "enterprise",
        "company": "Acme Corp"
      },
      "first_seen": "2025-01-10T08:00:00Z",
      "last_seen": "2025-01-15T16:30:00Z",
      "ip": "192.168.1.1",
      "city": "San Francisco",
      "country": "USA",
      "is_favorite": true,
      "created_at": "2025-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 250
  }
}