> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Identities

> Retrieve a paginated list of visitor identities

## Query Parameters

<ParamField query="limit" type="integer" default="50">
  Maximum number of results to return (max: 100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="email" type="string">
  Filter identities by email address
</ParamField>

<ParamField query="visitor_id" type="string">
  Filter identities by visitor ID (UUID)
</ParamField>

<ParamField query="is_favorite" type="boolean">
  Filter favorite identities (true/false)
</ParamField>

<ParamField query="created_after" type="string">
  Filter identities created after this date (ISO 8601 format)
</ParamField>

<ParamField query="created_before" type="string">
  Filter identities created before this date (ISO 8601 format)
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of visitor identity objects

  <Expandable title="Identity Object">
    <ResponseField name="id" type="string">
      Unique identifier for the identity
    </ResponseField>

    <ResponseField name="workspace_id" type="string">
      Workspace ID (always your workspace)
    </ResponseField>

    <ResponseField name="visitor_id" type="string">
      Associated visitor ID
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address
    </ResponseField>

    <ResponseField name="name" type="string">
      Full name
    </ResponseField>

    <ResponseField name="traits" type="object">
      Custom traits (JSONB)
    </ResponseField>

    <ResponseField name="first_seen" type="string">
      ISO 8601 timestamp of first visit
    </ResponseField>

    <ResponseField name="last_seen" type="string">
      ISO 8601 timestamp of last visit
    </ResponseField>

    <ResponseField name="ip" type="string">
      IP address
    </ResponseField>

    <ResponseField name="city" type="string">
      City
    </ResponseField>

    <ResponseField name="country" type="string">
      Country
    </ResponseField>

    <ResponseField name="is_favorite" type="boolean">
      Whether identity is marked as favorite
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.orwel.io/api/v1/identities?limit=10&is_favorite=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "ee0e8400-e29b-41d4-a716-446655440009",
        "workspace_id": "770e8400-e29b-41d4-a716-446655440002",
        "visitor_id": "660e8400-e29b-41d4-a716-446655440001",
        "email": "user@example.com",
        "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
    }
  }
  ```
</ResponseExample>