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

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:

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

curl -X POST https://portal.watcheye.com.au/api/v1/adhoc-idpasses \
  -H "Authorization: Bearer <key>|<secret>" \
  -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:

{
  "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

curl -H "Authorization: Bearer <key>|<secret>" \
     https://portal.watcheye.com.au/api/v1/idpasses/5b1c7c8e-0b6e-4f0a-9b3a-1f2e3d4c5b6a

Keep polling until status is terminal. A completed pass looks like:

{
  "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:

curl -H "Authorization: Bearer <key>|<secret>" \
     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):

curl -H "Authorization: Bearer <key>|<secret>" \
     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).

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.