# List IDPasses

`GET /idpasses`

- Base: `GET https://portal.watcheye.com.au/api/v1/idpasses`

Returns a paginated list of IDPasses on the calling account. Each IDPass is a remote
identity verification that the individual completes via a hosted link; the result is
updated asynchronously, so poll [show IDPass](/docs/reference/idpass.show) until `status` is
terminal.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `page` | query | integer [min 1] | The page of results to return, starting at 1. |
| `per_page` | query | integer [1..500] | The number of records per page (defaults to 30, max 500). |
| `filter[status]` | query | string | Only records with the given status. The endpoint description lists the values. Enum: `new`, `opened`, `in_progress`, `complete`, `expired`, `failed`, `cancelled` |
| `filter[verification_status]` | query | string | Only IDPasses with the given verification status. Enum: `passed`, `review`, `failed` |
| `filter[source]` | query | string | Only IDPasses launched from the given source (the `source` field of the IDPass). Enum: `entity`, `adhoc` |
| `filter[entity_uuid]` | query | string (uuid) | Only records for the given entity. |
| `filter[program_uuid]` | query | string (uuid) | Only records for entities in the given program. |
| `filter[created_after]` | query | string (date-time) | Inclusive lower bound on `created_at` (ISO 8601). |
| `filter[created_before]` | query | string (date-time) | Inclusive upper bound on `created_at` (ISO 8601). |
| `sort` | query | string | Sort field. Prefix with `-` for descending. Defaults to `-created_at`. Enum: `created_at`, `-created_at`, `status`, `-status` |

## Responses

### 200 A paginated list of IDPasses

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects |  |
| `data[].uuid` | string (uuid) | The IDPass identifier. Use it with the show, image and PDF endpoints. Example: `5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a` |
| `data[].source` | string | Whether the IDPass is bound to a saved entity or was launched adhoc. Enum: `entity`, `adhoc` Example: `entity` |
| `data[].status` | string | Where the individual is in the hosted flow: * `new` - the link has not been opened * `opened` - the welcome page was passed * `in_progress` - consent was given and documents are being submitted * `complete` - the verification finished; read `verification_status` for the outcome * `expired` - `link_validity_days` elapsed before completion * `failed` - the verification could not be completed * `cancelled` - cancelled in the portal The last four are terminal. Enum: `new`, `opened`, `in_progress`, `complete`, `expired`, `failed`, `cancelled` Example: `complete` |
| `data[].completed` | boolean | True once the IDPass has reached a terminal status. Example: `true` |
| `data[].verification_status` | string or null | The outcome once `status` is terminal, null until then: * `passed` - the identity was verified * `review` - the identity was verified but flagged for review in the portal; treat it as not yet passed * `failed` - the identity was not verified (including an expired or cancelled IDPass) Enum: `passed`, `review`, `failed` Example: `passed` |
| `data[].requester_name` | string | Your organisation's name as shown to the individual on the consent page. It comes from the DVS identity (OAC) the IDPass was issued under. Example: `Sample Company Pty Ltd` |
| `data[].check_liveness` | boolean | Whether the individual was asked to complete a face liveness check. Example: `true` |
| `data[].require_id_photo` | boolean | Whether the individual was asked to supply a standalone ID photo. Example: `true` |
| `data[].document_allowed_types` | object | The allowed document types for each of the (up to three) verification steps. |
| `data[].document_allowed_types.document_1` | array of strings | The document types the individual could present for the first step: * `licence` - Australian driver licence * `passport` - Australian passport * `medicare` - Medicare card * `visa` - foreign passport with an Australian visa * `centrelink` - Centrelink card (details typed in, no photo) * `birth_certificate` - Australian birth certificate (details typed in, no photo) * `nz_licence` - New Zealand driver licence Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data[].document_allowed_types.document_2` | array of strings | The document types for the second step, from the same list as `document_1`. Empty when there is no second step. Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data[].document_allowed_types.document_3` | array of strings | The document types for the third step, from the same list as `document_1`. Empty when there is no third step. Enum: `licence`, `passport`, `medicare`, `visa`, `centrelink`, `birth_certificate`, `nz_licence` |
| `data[].link_validity_days` | integer | How many days the hosted link stays open before the IDPass expires. Example: `7` |
| `data[].return_verification_images` | boolean | Whether verification images are retained and made available for download. Example: `true` |
| `data[].delivery_method` | string or null | How the link reached the individual: * `sms` - WatchEye sent it to `delivery_phone` by text message * `manual` - you delivered `idpass_link` yourself Enum: `manual`, `sms` Example: `sms` |
| `data[].idpass_link` | string or null | The hosted link the individual opens to complete their verification. Treat it as opaque - pass it on as-is and do not parse or rebuild it. Example: `https://idpass.globaldata.net.au/idpass?token=abcd123456` |
| `data[].sent_at` | string (date-time) or null | When the link was sent by SMS. Null when `delivery_method` is `manual`. Example: `2026-08-01T02:15:30+00:00` |
| `data[].created_at` | string (date-time) or null | When the IDPass was launched. Example: `2026-08-01T02:15:28+00:00` |
| `data[].detail_url` | string | Path to the full IDPass resource (GET /v1/idpasses/{uuid}). Example: `/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a` |
| `meta` | object |  |
| `meta.current_page` | integer |  |
| `meta.per_page` | integer |  |
| `meta.total` | integer |  |
| `meta.last_page` | integer |  |
| `api_reference` | string (uuid) |  |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a",
            "source": "entity",
            "status": "complete",
            "completed": true,
            "verification_status": "passed",
            "requester_name": "Sample Company Pty Ltd",
            "check_liveness": true,
            "require_id_photo": true,
            "document_allowed_types": {
                "document_1": [
                    "licence",
                    "passport"
                ],
                "document_2": [
                    "medicare"
                ],
                "document_3": []
            },
            "link_validity_days": 7,
            "return_verification_images": true,
            "delivery_method": "sms",
            "idpass_link": "https://idpass.globaldata.net.au/idpass?token=abcd123456",
            "sent_at": "2026-08-01T02:15:30+00:00",
            "created_at": "2026-08-01T02:15:28+00:00",
            "detail_url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a"
        }
    ],
    "meta": {
        "current_page": 0,
        "per_page": 0,
        "total": 0,
        "last_page": 0
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 400, 401, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))