Get details of an identity request

GET /identity/request/{access_request_code}/{identity_session_code}

Get details of an identity request.

This endpoint is useful for checking the status of an identity request, and for retrieving the redirect URL.

Parameters

Name	In	Required	Description
`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`
`access_request_code`	path	yes
`identity_session_code`	path	yes

Responses

Status	Description
`200 OK`	Request details retrieved successfully
`400 Bad Request`	Validation error
`401 Unauthorized`	Authentication failed or invalid token
`403 Forbidden`	Unauthorized or insufficient permissions
`404 Not Found`	Validation error
`429 Too Many Requests`	Too many requests
`500 Internal Server Error`	Internal server error

Content type application/json

Response fields (200)

Field	Type	Required	Description
`data`	object	yes
`data.first_name`	string	no
`data.last_name`	string	no
`data.email`	string	no
`data.phone`	string	no	Contact's personal mobile phone number, without country code
`data.phone_country_code`	integer	no	Country code for phone number
`data.purpose`	string	no	One of: `identity`, `police-check`
`data.time_expires`	integer	no
`data.opened_at`	integer	no
`data.completed_at`	integer	no
`data.request_code`	string	no
`data.redirect_url`	string	no
`data.send_email`	boolean	no
`correlation_id`	string	yes
`meta`	object	no	Optional metadata about the response

Example 200 response

{
  "correlation_id": "req-64b4a7e123456",
  "data": {
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "phone": 412321123,
    "phone_country_code": 61,
    "purpose": "identity",
    "time_expires": 0,
    "opened_at": 0,
    "completed_at": 0,
    "request_code": "string",
    "redirect_url": "string",
    "send_email": true
  }
}

Content type application/json

ErrorResponse (400, 404)

Field Type Required Description

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.

Code	Type	HTTP
`E1001`	`VALIDATION_ERROR`	400
`E1002`	`INVALID_REQUEST`	400
`E1003`	`AUTHENTICATION_FAILED`	401
`E1004`	`UNAUTHORIZED`	403
`E1005`	`NOT_FOUND`	404
`E1006`	`CONFLICT`	409
`E1007`	`RATE_LIMIT_EXCEEDED`	429
`E1008`	`PRECONDITION_FAILED`	412
`E1009`	`CREDENTIAL_EXPIRED`	412
`E1010`	`CREDENTIAL_REVOKED`	412
`E1011`	`CREDENTIAL_PENDING_ACCEPTANCE`	412
`E1012`	`CREDENTIAL_VERIFICATION_FAILED`	412
`E2001`	`INTERNAL_ERROR`	500
`E2002`	`INTERNAL_ERROR_EMAIL`	500
`E2003`	`DATABASE_ERROR`	500
`E2004`	`EXTERNAL_SERVICE_ERROR`	502
`E2005`	`SERVICE_UNAVAILABLE`	503

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

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)

Field	Type	Required	Description
`error`	object	yes

Example 401 response

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

Content type application/json

Response fields (403)

Field	Type	Required	Description
`error`	object	yes

Example 403 response

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

Content type application/json

Response fields (429)

Field	Type	Required	Description
`error`	object	yes

Example 429 response

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

Content type application/json

Response fields (500)

Field	Type	Required	Description
`error`	object	yes

Example 500 response

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

Example request

curl --request GET \
  --url https://api.sandbox.truevault.com.au/api/v1/identity/request/{access_request_code}/{identity_session_code} \
  --header 'X-Correlation-Id: <value>' \
  --header 'Authorization: <value>' \
  --header 'X-Tenant-Id: <value>' \
  --header 'X-Request-Timestamp: <value>'