# IDPass An **IDPass** is a remote identity verification. Rather than you submitting document details for a synchronous DVS check (as the ID check endpoints do), an IDPass produces a secure hosted link that the individual opens themselves to photograph their documents, complete a liveness check and consent to the verification. Because a person has to interact with the hosted link, an IDPass is **asynchronous**: the launch call returns immediately and you poll for the result. IDPasses can be launched in two ways: - **Entity-bound** (`POST /v1/entities/{uuid}/idpasses`) - tied to a saved entity. The supplied `dob` must match the entity's date of birth. - **Adhoc** (`POST /v1/adhoc-idpasses`) - a one-off verification with no entity record. Both forms share the same configuration, the same response shape and the same polling, PDF and image endpoints described below. ## Endpoints | Endpoint | Method | Purpose | |---|---|---| | `/v1/idpasses` | `GET` | List IDPasses on the account. Filter by `source` (`entity`/`adhoc`) and `status`. | | `/v1/idpasses/{uuid}` | `GET` | Show a single IDPass with full configuration, status, document/validation summaries, activity log and image metadata. Poll this for the result. | | `/v1/entities/{uuid}/idpasses` | `POST` | Launch an entity-bound IDPass. Returns `202 Accepted`. | | `/v1/adhoc-idpasses` | `POST` | Launch an adhoc IDPass. Returns `202 Accepted`. | | `/v1/idpasses/{uuid}/pdf` | `GET` | Download the verification certificate PDF (only once the IDPass is terminal). | | `/v1/idpasses/{uuid}/images/{type}` | `GET` | Download a single verification image as raw bytes (only when `return_verification_images` was set). | Both launch endpoints are chargeable and accept the `Idempotency-Key` header. The product billed depends on how many document verification steps are configured. The PDF and image endpoints are not billed - they read from the on-record IDPass. Manual correction of an IDPass result and cancellation of an in-flight IDPass remain **portal-only** functions; they are not exposed through the API. ## Discoverability from ID checks When an ID check was satisfied by an IDPass, the ID check show/list payloads (`/v1/id-checks/...` and `/v1/adhoc-id-checks/...`) embed a lightweight `idpass` shell - its `uuid`, `status`, `verification_status` and `idpass_link` - alongside an `idpass_url` pointing at the full IDPass resource. Follow `idpass_url` to `GET /v1/idpasses/{uuid}` for the complete record. Conversely, the IDPass detail payload carries an `id_check` block linking back to the originating check. ## Lifecycle and status The launch response is `202 Accepted` and carries the IDPass `uuid`, its `detail_url`, and the hosted `idpass_link`. Poll `GET /v1/idpasses/{uuid}` until `status` reaches a terminal value: | `status` | Meaning | |---|---| | `new` | Created; the individual has not opened the link yet. | | `opened` | The individual has opened the hosted link. | | `in_progress` | Documents are being submitted/processed. | | `complete` | **Terminal.** Verification finished - read `verification_status` (`passed`, `review` or `failed`) for the outcome. | | `expired` | **Terminal.** The link validity window elapsed before completion. | | `failed` | **Terminal.** The verification could not be completed. | | `cancelled` | **Terminal.** Cancelled in the portal. | `completed` is `true` once any terminal status is reached. A `review` outcome means the identity was verified but has been flagged for review in the portal - treat it as not yet passed until it has been looked at. Because completion depends on a person, polling can run for minutes to hours - poll every few seconds initially, then back off to a longer interval (e.g. every 30-60 seconds), and rely on `link_validity_days` for the upper bound. ## Delivery `config.delivery_method` controls how the hosted link reaches the individual: - `manual` - the link is returned to you as `idpass_link` and you deliver it yourself. - `sms` - WatchEye sends the link by SMS to `config.delivery_phone` (an Australian mobile, `04XXXXXXXX`). The link is still returned as `idpass_link` as well. ## Worked example The example below launches an **adhoc** IDPass, polls for the result, then downloads the certificate and a verification image. ### 1. Launch the IDPass ```bash curl -X POST https://portal.watcheye.com.au/api/v1/adhoc-idpasses \ -H "Authorization: Bearer |" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c3f9a1e-2b44-4f6a-9d2e-8a1b6c5d4e3f" \ -d '{ "data": { "first_name": "John", "last_name": "Smith", "dob": "1980-06-23" }, "config": { "link_validity_days": 7, "check_liveness": true, "document_1_allowed_types": ["licence"], "document_2_allowed_types": ["medicare"], "require_id_photo": false, "return_verification_images": true, "delivery_method": "sms", "delivery_phone": "0412345678" } }' ``` The response is `202 Accepted`. The `data` block holds what exists at launch: the IDPass's identifier, configuration, delivery details, the hosted link and the ID check it belongs to. The verification outcome, summaries, log and images are not part of it - they come from `GET /v1/idpasses/{uuid}` once the individual has completed the link. Abridged, note the `uuid`, the `detail_url` to poll, and the hosted `idpass_link`: ```json { "data": { "uuid": "5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a", "source": "adhoc", "delivery_method": "sms", "idpass_link": "https://idpass.globaldata.net.au/idpass?token=abcd123456", "detail_url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a" }, "api_reference": "9f8e7d6c-..." } ``` Because `delivery_method` is `sms`, the individual receives the `idpass_link` by text message. Treat `idpass_link` as opaque: pass it on exactly as returned and do not parse or rebuild it. (See the sandbox note below for how this behaves in sandbox.) ### 2. Poll for the result ```bash curl -H "Authorization: Bearer |" \ https://portal.watcheye.com.au/api/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a ``` Keep polling until `status` is terminal. A completed pass looks like: ```json { "data": { "uuid": "5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a", "status": "complete", "completed": true, "verification_status": "passed", "return_verification_images": true, "images": [ { "type": "id_photo", "title": "ID Photo", "mime_type": "image/jpeg", "url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a/images/id_photo" }, { "type": "licence_front", "title": "Drivers Licence Front", "mime_type": "image/jpeg", "url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a/images/licence_front" } ], "pdf_url": "/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a/pdf" }, "api_reference": "..." } ``` ### 3. Download the certificate PDF Once `status` is terminal, fetch the certificate. The PDF streams as raw bytes with a `Content-Disposition` filename, so write the body straight to a file: ```bash curl -H "Authorization: Bearer |" \ https://portal.watcheye.com.au/api/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a/pdf \ -o idpass-certificate.pdf ``` Requesting the PDF before the IDPass is terminal returns `409 Conflict` - keep polling and retry. ### 4. Download a verification image When the IDPass was launched with `return_verification_images: true`, each entry in the `images` array can be fetched by its `type`. Images also stream as raw bytes (`image/jpeg`): ```bash curl -H "Authorization: Bearer |" \ https://portal.watcheye.com.au/api/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a/images/id_photo \ -o id-photo.jpg ``` Requesting a type that was not captured, or any image when `return_verification_images` was `false`, returns `404`. ## Sandbox behaviour IDPasses work end-to-end in sandbox using the same endpoints and response shapes as live, against the sandbox environment - so you can launch, poll and download without consuming live credit. To exercise the hosted verification flow you open the `idpass_link` yourself and upload a synthetic identity document. The sample licences and passports to use, and the result each one produces, are listed under [IDPass Test Documents (login required)](/docs/guides/watcheye_api/idpass-test-documents). ### SMS delivery in sandbox In sandbox, **no real SMS is sent.** When you launch a `sms`-delivery IDPass on a sandbox account, the message is recorded as sent but is not handed to the SMS gateway, so no text reaches the `delivery_phone`. The `idpass_link` is still returned in the launch response, so use that value to open the hosted flow during testing. On a live account the SMS is delivered normally.