# List accounts

`GET https://app.shuttleglobal.com/c/api/instances/{instance_key}/accounts`

Search and list account objects with various filtering criteria.

The search criteria syntax supports various operators:
- `=` Exact match (multiple values with `;` for IN)
- `~=` Partial match (contains)
- `!=`, `>=`, `>`, `<`, `<=` Comparisons
- `<>` Between (separate with `;`)
- `!` Is null
- `!!` Is not null

Multiple criteria can be combined with `,` (AND).
See project README.md for detailed examples and usage.

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `criteria` | query | string | no | Search criteria for filtering accounts. Available fields: `id`, `first_name`, `last_name`, `email`, `phone`, `company`, `crm_key`, `crm`, `channel`, `division`, `tags`, `last_transacted`, `created`, `updated` Examples: - `email=user@example.com` - `status=ACTIVE;PENDING` - `company~=Tech` - `created<>2024-01-01;2024-12-31` - `status=ACTIVE,email~=example.com` |
| `order` | query | string | no | Sort order for results. Supports any field that criteria supports. Defaults to `created:desc` if not specified. Append `:desc` for descending order. Separate multiple order fields with commas. Examples: - `order=updated` - `order=last_name:desc` - `order=company,created:desc` |
| `expand` | query | string | no | Fields to expand into full objects. Separate multiple fields with commas. Available fields: - last_transaction (transaction object) - created_session (session object) - updated_session (session object) Example: `expand=last_transaction,created_session` |
| `limit` | query | integer | no | Number of records to return: 20 if not set, at most 1000. |
| `offset` | query | integer | no | Number of records to skip before the first one returned. `offset` + `limit` can't exceed 5000; to read further, page by a field such as `created` instead. See [Paging through results](/platforms/reference/paging/). |

## Responses

### 200: List of accounts

```json
{
  "accounts": [
    {
      "address": {},
      "bolton_values": {},
      "channels": [
        "string"
      ],
      "code": "string",
      "company": "string",
      "created": "2026-01-01T12:00:00Z",
      "created_session": "string",
      "crm": "string",
      "crm_key": "string",
      "disconnected_account": true,
      "divisions": [
        "string"
      ],
      "email": "string",
      "first_name": "string",
      "full_address": "string",
      "giftaid_ineligible": true,
      "id": "string",
      "initiatives": [
        "string"
      ],
      "last_name": "string",
      "last_transacted": "2026-01-01T12:00:00Z",
      "last_transaction": "string",
      "locale": "string",
      "metadata": {},
      "name": "string",
      "phone": "string",
      "status": "ACTIVE",
      "tags": "string",
      "timezone": "string",
      "updated": "2026-01-01T12:00:00Z",
      "updated_session": "string",
      "v": 0
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Invalid credentials (authentication is validated before instance key)

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

### 404: Instance not found (only checked after successful authentication)

```json
{
  "code": "string",
  "message": "string"
}
```

## Example request

```sh
curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/accounts \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/listaccounts/