Launch an adhoc IDPass
/adhoc-idpasses
Creates a remote identity verification (IDPass) that is not tied to a saved entity and
returns **202 Accepted** with the IDPass shell, including its hosted idpass_link. Use this
for one-off verifications where you do not need to persist the individual as an entity.
Example Request
POSTRequest Schema
Idempotency-Key
Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests
data
The identity being verified.
data.first_name
Required unless `last_name` is supplied.
data.middle_name
data.last_name
Required unless `first_name` is supplied.
data.dob
Date of birth in `YYYY-MM-DD` format. Optional - when omitted, the identity documents are still fully DVS-verified, but the supplied details are matched against the documents on name only. For an entity-bound launch a supplied date of birth must match the entity's recorded date of birth.
oac
The DVS OAC code the IDPass should be issued under. Must be one of the OAC codes configured on your account. The selected OAC determines the requesting organisation name and privacy policy shown to the person being verified. Required when your account is configured with more than one OAC. When your
config
config.link_validity_days
config.check_liveness
Whether to perform a liveness check during verification.
config.document_1_allowed_types
config.document_2_allowed_types
Optional second verification step. Requires document 1 to be supplied, and a step cannot reuse a document type already consumed by an earlier step.
config.document_3_allowed_types
Optional third verification step. Requires document 2 to be supplied, and a step cannot reuse a document type already consumed by an earlier step.
config.require_id_photo
Whether the individual must also supply a standalone ID photo.
config.id_photo_purpose
Required when `require_id_photo` is `true`.
config.return_url
config.return_verification_images
Whether the verification images should be retained and made available for download afterwards via the IDPass image endpoint.
config.delivery_method
config.delivery_phone
Australian mobile number (04XXXXXXXX). Required when `delivery_method` is `sms`, in which case the hosted link is sent to this number.
Available Response Data
13 Data Pointsuuid uuid
source enum
Whether the IDPass is bound to a saved entity or was launched adhoc: entity, adhoc
status enum
new, opened, in_progress, complete, expired, failed, …
status_name string
completed boolean
True once the IDPass has reached a terminal status
verification_status enum
passed, review, failed
verification_status_name string
requester_name string
check_liveness boolean
require_id_photo boolean
document_allowed_types object (The allowed document types for each of the (up to three) verification steps)
link_validity_days integer
api_reference uuid
unique request identifier for log tracing and audit
API Data Scale & Coverage tag
Unmatched data depth to power your compliance and verification workflows.
Sandbox Environment
Build and test against a sandbox account. Sandbox is a separate account with its own UUID and its own API keys, and the environment is fixed at the account level, so you cannot switch an existing key between live and sandbox with a parameter or header. Both share the same base URL, so the account behind your key is what determines which environment you are in. GET /v1/account returns an environment field of live or sandbox, and that is the authoritative answer.
Calls on a sandbox key are not billed. Every endpoint, response shape, error envelope, idempotency and rate-limit behaviour mirrors live, so the only change when you move to production should be the credentials. Sandbox accounts are provisioned by your Global Data account manager.
Identity verification works end to end in sandbox using the same endpoints and response shapes as live. No real SMS is sent for an IDPass delivered by SMS on a sandbox account; the message is recorded instead of delivered.
Technical Use Cases tag
Screening inside your own workflow
Trigger remote identity verification completed by the individual via a hosted link from your application at the exact point your process calls for it, instead of asking staff to run it separately in the portal.
Queue now, collect later
The call returns 202 Accepted with the new UUID. The work runs in the background and you poll the show endpoint until it reaches a terminal state, which suits batch launches.
Safe retries
Send an Idempotency-Key so an ambiguous network failure can be retried without running the check twice or being billed twice.
Compliance & Security tag
Enterprise-grade infrastructure audited against the standards your regulators require.
Common Questions tag
Everything you need to know about implementation details and compliance infrastructure.
rocket_launch Implementation
How do I know when the work has finished?
add
How do I know when the work has finished?
This endpoint returns 202 Accepted, which confirms the work is queued, not complete. Poll the corresponding show endpoint until it reaches a terminal value.
For checks and adhoc checks that means status becomes complete or failed. For a monitor run it means process_status becomes null, failed or paused.
A reasonable cadence is every 2 to 5 seconds for the first 30 seconds, backing off to every 15 to 30 seconds after that. Most screening checks finish within a few seconds; a monitor run across thousands of entities can take several minutes.
rocket_launch Implementation
Is it safe to retry this call?
add
Is it safe to retry this call?
Yes, if you send an Idempotency-Key header. A connection can drop after WatchEye has processed a request but before the response reaches you, and a blind retry would risk a duplicate record or a double charge.
The key is any string of your choosing up to 255 characters, unique per logical operation, and a fresh UUID per request is the usual approach. Sending the same key again returns the original response byte for byte, with no new database changes and no new billable charge.
The header is honoured on POST only. It is silently ignored on GET, PATCH and DELETE, which are already idempotent at the HTTP level.
help_center General
Is this call billed?
add
Is this call billed?
Yes. This is a chargeable endpoint, and the fee is billed to your account at the time of the request. Your rates are set per account and confirmed by your Global Data account manager.
If your balance reaches zero or an agreed call limit is reached, further chargeable requests return 402 Payment Required until the account is topped up. Calls made with a key on a sandbox account are never charged.
Ready to integrate Launch an adhoc IDPass?
Talk to our team about credentials, sandbox access and the right combination of endpoints for your workflow.