TrueVault Identity Manager

Request a new TrueIdentity

POST /identity/request

Request an identity for a given person. Requires seed data to be provided.

Once approved (or cancelled), you will receive a callback via webhook. See below.

To receive a callback, you must configure a webhook URL in your user portal, and subscribe to the 'TrueIdentity Actions' webhook.

Note an error code of INTERNAL_ERROR_EMAIL 'E2002' will be returned if the email fails to send. In this case the request will still be created and the user will be able to complete their TrueIdentity using the redirect URL. The code and redirect_url will be provided inside the details object of the error response.

Parameters

NameInRequiredDescription
X-Correlation-Id header no

Unique identifier for tracking the request through the system

Example: req-64b4a7e123456
Authorization header yes

Access key generated from the auth API

Example: Bearer 048c2a1c-0881-4dcc-bfca-ccccccccc51
X-Tenant-Id header yes

The tenant ID for the request

Example: 048c2a1c-0881-4dcc-bfca-ccccccccc51
X-Request-Timestamp header yes

The timestamp for the request

Example: 1754261500

Request body

Content type application/json

Fields

FieldTypeRequiredDescription
first_name string yes
last_name string yes
email string yes

Contact's personal email address
phone string yes

Contact's personal mobile phone number, without country code
phone_country_code integer yes

Country code for phone number
purpose string yes

One of: identity, police-check
return_url string yes

The client URL to redirect the user to after finishing their TrueIdentity process. This location should be configured to await the webhook response.
off_ramp_url string yes

The client URL to redirect the user to if they cannot provide all the documents required by the rule set.
results_emails string yes

Optional email addresses to send notification of results to. Comma separated list. Not required, as webhook is required for onward processing.
download_email string yes

Optional email address to send the download link to if any credential source files are requested, e.g. a Police Check certificate.
expiry_hours integer yes

Optional number of hours the request should be valid for. Leave unset to default to 24. Set to 0 to disable expiry (not recommended).
send_email boolean no

Whether TrueVault should send an email to the user with a link to complete their TrueIdentity.
payment_via string no

Optional flag to set billing to invoice (not user-pays). Please contact us to enable invoice billing, if you haven't already.

One of: invoice, user
ruleset string no

The verification ruleset to use for this identity request. It sets the evidence a person has to provide before the identity is issued.

ValueRequires
bronzeOne biometric
bronze_ausOne biometric, Australian documents only
silverOne biometric, 1 other document
goldOne biometric, 2 other documents
acicACIC background and police checks
acic_rtwACIC background checks plus Right to Work
arneccARNECC conveyancing, excluding ConnectID
arnecc_cidARNECC conveyancing, including ConnectID
tranche2_basicTranche 2 AML, general purpose
tranche2Tranche 2 AML, enhanced due diligence
vevortwRight to Work, visa check for non-Australian residents

Omit it and bronze is used. An unrecognised value is rejected with a validation error, so send one of the values above exactly as written.

One of: bronze, bronze_aus, silver, gold, acic, acic_rtw, arnecc, arnecc_cid, tranche2_basic, tranche2, vevortw
claims string yes

The claims to request for this identity request. Document claims only fulfilled if data is known.

Claims can be provided as either:

  • A flat array of claim strings (all optional)
  • An object where keys are claim strings and values are either null (optional) or {"essential": true} (mandatory)

To mark a claim as essential (mandatory), provide it as a key with {"essential": true} as the value. Essential claims will cause the request to fail if the credential type cannot be obtained. Note: Document-type claims cannot be marked as essential; use an appropriate rule set instead.

Flat array example (all optional):

["trueidentity.email", "trueidentity.name", "acicncchc.credential"]

Object with essential markers:

{
  "trueidentity.email": null,
  "acicncchc.credential": {"essential": true},
  "document.driving_license.licence_number": null
}

In this example, acicncchc.credential is essential (mandatory), while the others are optional.

One of: trueidentity.credential (The person's TrueCredential), trueidentity.reference (Unique person reference. Needed to submit additional credentials), trueidentity.name (The person's name), trueidentity.given_name (The person's given name), trueidentity.family_name (The person's family name), trueidentity.phone (The person's phone number), trueidentity.phone_verified (The person's phone number verification status), trueidentity.email (The person's email address), trueidentity.email_verified (The person's email address verification status), trueidentity.birth_date (The person's date of birth), trueidentity.biometric (Biometric image as base64. Warning, may be large), trueidentity.names_verified (All names verified), document.driving_license.licence_number (The person's driving license number) [NOTE the spelling change], document.driving_license.date_expires (The expiry date of the person's driving license), document.driving_license.state (The state of the person's driving license), document.passport.travel_document_number (The person's Australian passport number), document.passport.date_expires (The expiry date of the person's Australian passport), document.passport.document_country (The country of the person's Australian passport. Should be AUS..), document.passport_foreign.passport_number (The person's non-Australian passport number), document.passport_foreign.date_expires (The expiry date of the person's non-Australian passport), document.passport_foreign.document_country (The country of the person's non-Australian passport), acicncchc.credential (The ACIC NCCHC [Police Checks] result credential. Currently limited to Australian residents only), acicncchc.source_data (The raw ACIC NCCHC [Police Checks] NSS result data), acicncchc.source_download (The ACIC NCCHC [Police Checks] result certificate download), acicncchc.result (The ACIC NCCHC [Police Checks] result only (DCO/NDCO)), acicncchc.date_expires (The ACIC NCCHC [Police Checks] expiry date), vevortw.credential (The Right To Work credential), vevortw.source_data (The Right To Work raw data), vevortw.source_download (The Right To Work certificate download), vevortw.work_entitlements (The Right To Work work entitlements (e.g. allowed or not allowed)), vevortw.document_number (The Right To Work document (usually passport) number), vevortw.date_expires (The Right To Work expiry date)

Example request body

{
  "first_name": "string",
  "last_name": "string",
  "email": "jamie@gmail.com",
  "phone": 412321123,
  "phone_country_code": 61,
  "purpose": "identity",
  "return_url": "string",
  "off_ramp_url": "string",
  "results_emails": "string",
  "download_email": "string",
  "expiry_hours": 0,
  "send_email": true,
  "payment_via": "invoice",
  "ruleset": "bronze",
  "claims": [
    "string"
  ]
}

Responses

StatusDescription
200 OK

Request created successfully

400 Bad Request

Validation error

401 Unauthorized

Authentication failed or invalid token

403 Forbidden

Unauthorized or insufficient permissions

409 Conflict

Conflict error

429 Too Many Requests

Too many requests

500 Internal Server Error

Internal server error

Content type application/json

Response fields (200)

FieldTypeRequiredDescription
data object yes
data.access_request_code string no

The request code for the identity request. This will be contained in the webhook response for alignment.
data.identity_session_code string no

The identity session code for the identity request. You will need this to retrieve results later.
data.redirect_url string no

The TrueVault URL to redirect the user to in order to complete/share their TrueIdentity.
correlation_id string yes
meta object no

Optional metadata about the response

Example 200 response

{
  "correlation_id": "req-64b4a7e123456",
  "data": {
    "access_request_code": "string",
    "identity_session_code": "string",
    "redirect_url": "string"
  }
}

Content type application/json

ErrorResponse (400)

FieldTypeRequiredDescription
error object yes

Every error carries a machine-readable type and a code. Match on one of these rather than on the message, which is written for people and may change.

CodeTypeHTTP
E1001VALIDATION_ERROR400
E1002INVALID_REQUEST400
E1003AUTHENTICATION_FAILED401
E1004UNAUTHORIZED403
E1005NOT_FOUND404
E1006CONFLICT409
E1007RATE_LIMIT_EXCEEDED429
E1008PRECONDITION_FAILED412
E1009CREDENTIAL_EXPIRED412
E1010CREDENTIAL_REVOKED412
E1011CREDENTIAL_PENDING_ACCEPTANCE412
E1012CREDENTIAL_VERIFICATION_FAILED412
E2001INTERNAL_ERROR500
E2002INTERNAL_ERROR_EMAIL500
E2003DATABASE_ERROR500
E2004EXTERNAL_SERVICE_ERROR502
E2005SERVICE_UNAVAILABLE503
error.message string yes

Human readable error message
error.type string yes

Error type identifier

One of: VALIDATION_ERROR, INVALID_REQUEST, AUTHENTICATION_FAILED, UNAUTHORIZED, NOT_FOUND, CONFLICT, RATE_LIMIT_EXCEEDED, PRECONDITION_FAILED, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CREDENTIAL_PENDING_ACCEPTANCE, CREDENTIAL_VERIFICATION_FAILED, INTERNAL_ERROR, INTERNAL_ERROR_EMAIL, DATABASE_ERROR, EXTERNAL_SERVICE_ERROR, SERVICE_UNAVAILABLE
error.code string yes

Machine-readable error code

One of: E1001, E1002, E1003, E1004, E1005, E1006, E1007, E1008, E1009, E1010, E1011, E1012, E2001, E2002, E2003, E2004, E2005
error.timestamp string yes
error.correlation_id string yes
error.details object no

Additional error context

Example 400 response

{
  "error": {
    "message": "string",
    "type": "VALIDATION_ERROR",
    "code": "E1001",
    "timestamp": "2026-02-20T03:14:15Z",
    "correlation_id": "string"
  }
}

Content type application/json

Response fields (401)

FieldTypeRequiredDescription
error object yes

Example 401 response

{
  "error": {
    "type": "AUTHENTICATION_FAILED",
    "code": "E1003"
  }
}

Content type application/json

Response fields (403)

FieldTypeRequiredDescription
error object yes

Example 403 response

{
  "error": {
    "type": "UNAUTHORIZED",
    "code": "E1004"
  }
}

Content type application/json

ConflictError (409)

FieldTypeRequiredDescription
error object no
error.message string no

Human readable error message
error.type string no

One of: CONFLICT
error.code string no

One of: E1006
error.timestamp string no
error.correlation_id string no
error.details object no
error.details.existing_code string no

Example 409 response

{
  "error": {
    "message": "string",
    "type": "CONFLICT",
    "code": "E1006",
    "timestamp": "2026-02-20T03:14:15Z",
    "correlation_id": "req-64b4a7e123456",
    "details": {
      "existing_code": "string"
    }
  }
}

Content type application/json

Response fields (429)

FieldTypeRequiredDescription
error object yes

Example 429 response

{
  "error": {
    "type": "RATE_LIMIT_EXCEEDED",
    "code": "E1007"
  }
}

Content type application/json

Response fields (500)

FieldTypeRequiredDescription
error object yes

Example 500 response

{
  "error": {
    "type": "INTERNAL_ERROR",
    "code": "E2001"
  }
}

Example request

curl --request POST \
  --url https://api.sandbox.truevault.com.au/api/v1/identity/request \
  --header 'X-Correlation-Id: <value>' \
  --header 'Authorization: <value>' \
  --header 'X-Tenant-Id: <value>' \
  --header 'X-Request-Timestamp: <value>' \
  --header 'Content-Type: application/json'