Create Journey V2

Journey Tokens expire in 10 minutes. Initialize the SDK immediately after creation.

Journey Types

The journeyType field determines the verification flow. Choose based on your use case:

ONBOARDING
REKYC
AUTHORISE
ONE_TO_MANY

First-time identity verification for new customers who have not been previously verified on the platform.Use case: A bank onboarding a new customer — the user presents their Emirates ID, passport, or GCC ID for the first time, completes liveness detection, and their identity is registered in the system.

No identifier is needed — must be empty or omitted
All configured document types are available
Liveness gestures (blink or smile) can be required

Authentication

x-transaction-key

string

required

Your API key. Get your key →

Content-Type

string

required

Must be application/json

Request Body

The V2 API groups related fields into logical sections: identifier, sdkConfig, and verificationConfig.

{
  "journeyType": "ONBOARDING", // ONBOARDING, REKYC, AUTHORISE, ONE_TO_MANY
  "identifier": {
    "uaeKycId": "13903"
  },
  "sdkConfig": {
    "skipConsentPage": false,
    "skipSuccessPage": false,
    "skipFailurePage": true,
    "gesture": "blink",
    "documents" : [
        {
          "type": "emirates_id",
          "captureMethod": "scan"
        },
        {
          "type": "gcc_id",
          "captureMethod": "manual_input"
        },
        {
          "type": "passport",
          "captureMethod": "all"
        }
    ]
  },
  "verificationConfig": {
    "nonVisitorOnboarding" : true,
    "nfcVerification" : true
  }
}

journeyType

string

required

Type of verification journey: ONBOARDING, REKYC, AUTHORISE, or ONE_TO_MANY.

identifier (Conditional)

The identifier object contains pre-filled user identification information.

Mutual Exclusivity Rule: Only one identifier can be provided at a time. Providing multiple identifiers will result in a validation error.

Journey Type	Identifier Required?	Validation Rule
`ONBOARDING`	No	Must be empty or omitted
`ONE_TO_MANY`	No	Must be empty or omitted
`REKYC`	Optional	If provided, must have exactly one identifier
`AUTHORISE`	Required	Must have exactly one identifier

identifier

object

Pre-filled user identification information.

Show properties

emiratesId

string

Emirates ID number. Format: 784XXXXXXXXXXXX (15 digits starting with 784). Hyphens are auto-stripped.

passport

object

Passport-based identification.

Show properties

number

string

required

Passport number.

type

string

required

Passport type code (e.g., P for ordinary).

nationality

string

required

ISO 3166-1 alpha-3 nationality code (e.g., IND, GBR).

gccId

object

GCC ID-based identification.

Show properties

number

string

required

GCC ID number.

nationality

string

required

ISO 3166-1 alpha-3 nationality code (e.g., KWT, SAU).

uaeKycId

string

Links journey to existing UAE KYC record for re-verification or authorization.

uidNumber

integer

UID person number.

sdkConfig (Optional)

Configuration for SDK UI/UX behavior and controls. All fields are optional. If not provided, SDK uses default behavior or organization level settings.

sdkConfig

object

SDK configuration object.

Show properties

Pre-configures user consent. When true, SDK skips consent screen and assumes consent given. When false or omitted, SDK shows consent screen to user.

Client is responsible for obtaining proper consent if set to true.

skipSuccessPage

boolean

default:"false"

Controls success page display after successful verification. When true, SDK skips success page and redirects immediately. When false, SDK shows success message before redirecting. Use case: seamless embedded experiences where you want to show your own success UI.

skipFailurePage

boolean

default:"false"

Controls failure page display. When true, SDK skips failure page and redirects immediately. When false, SDK shows failure page with verification status. Use case: custom result handling in your application.

gesture

string

Adds liveness detection gesture during face verification. Valid values: blink, smile. When empty or omitted, standard liveness detection without gestures is used. Gestures provide enhanced liveness detection against spoofing attacks.

documents

object[]

Documents allowed for verification. Each document type can appear only once in the array. Duplicate types throw a validation error.Organization constraints: client can only request documents and capture methods allowed by organization configuration. Client can restrict further (subset) but not expand.Journey type specific rules:

ONE_TO_MANY: documents are ignored (face-only)
AUTHORISE with identifier: documents are ignored (uses pre-filled ID)
REKYC with identifier: documents are ignored (uses pre-filled ID)

Show document object properties

type

string

required

Document type. Valid values: emirates_id, gcc_id, passport.

captureMethod

string

required

How the document is captured. Valid values:

scan — Camera capture only. Shows camera interface with auto-capture, manual-capture, and upload options.
manual_input — Text input only. Shows text input form for document details.
all — User choice. Shows option to choose between scan and manual input.

verificationConfig (Optional)

Configuration for verification strategy, document requirements, and verification level. Organization configuration may restrict available verification levels.

verificationConfig

object

Verification configuration object.

Show properties

nonVisitorOnboarding

boolean

default:"false"

Allows user who has no record in government database to get onboarded using facematch between scanned document (passport) and captured selfie.

nfcVerification

boolean

default:"false"

Allows user who has no record or no biometric data in government database to get onboarded using facematch between image present in NFC chip and captured selfie.

Code Examples

ONBOARDING
REKYC
AUTHORISE

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "ONBOARDING",
  "sdkConfig": {
    "skipConsentPage": false,
    "skipSuccessPage": false,
    "skipFailurePage": false,
    "gesture": "blink",
    "documents": [
      {
        "type": "emirates_id",
        "captureMethod": "scan"
      },
      {
        "type": "passport",
        "captureMethod": "all"
      }
    ]
  },
  "verificationConfig": {
    "nonVisitorOnboarding": false,
    "nfcVerification": false
  }
}'

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "REKYC",
  "identifier": {
    "emiratesId": "784123412345678"
  },
  "sdkConfig": {
    "gesture": "smile"
  }
}'

Alternative identifiers for REKYC

Using Passport:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "REKYC",
  "identifier": {
    "passport": {
      "number": "A1234567",
      "type": "P",
      "nationality": "USA"
    }
  },
  "sdkConfig": {
    "gesture": "blink"
  }
}'

Using GCC ID:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "REKYC",
  "identifier": {
    "gccId": {
      "number": "123456789",
      "nationality": "SAU"
    }
  },
  "sdkConfig": {
    "gesture": "blink"
  }
}'

Using UAE KYC ID:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "REKYC",
  "identifier": {
    "uaeKycId": "13903"
  },
  "sdkConfig": {
    "gesture": "smile"
  }
}'

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "AUTHORISE",
  "identifier": {
    "emiratesId": "784123412345678"
  },
  "sdkConfig": {
    "skipSuccessPage": false,
    "skipFailurePage": false,
    "gesture": "blink"
  }
}'

Alternative identifiers for AUTHORISE

Using Passport:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "AUTHORISE",
  "identifier": {
    "passport": {
      "number": "A1234567",
      "type": "P",
      "nationality": "USA"
    }
  },
  "sdkConfig": {
    "skipSuccessPage": false,
    "skipFailurePage": false
  }
}'

Using GCC ID:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "AUTHORISE",
  "identifier": {
    "gccId": {
      "number": "123456789",
      "nationality": "SAU"
    }
  },
  "sdkConfig": {
    "skipSuccessPage": false,
    "skipFailurePage": false
  }
}'

Using UAE KYC ID:

curl -X POST "{base_url}/otk-service/v2/create-journey" \
-H "Content-Type: application/json" \
-H "x-transaction-key: your-api-key" \
-d '{
  "journeyType": "AUTHORISE",
  "identifier": {
    "uaeKycId": "13903"
  },
  "sdkConfig": {
    "skipSuccessPage": false,
    "skipFailurePage": false
  }
}'

Response Fields

Success Response

Field	Type	Description	Presence
`success`	boolean	Always `true` for successful requests.	Always present
`data.journeyToken`	string (UUID)	Unique journey identifier.	Always present
`data.expiresAt`	number	Absolute expiry timestamp (epoch milliseconds).	Always present
`message`	string	`"Journey created successfully"`	Always present
`meta.serverTimestamp`	number	Server timestamp (epoch milliseconds).	Always present
`meta.journeyType`	string	Echo of requested journey type.	Always present
`meta.createdAt`	number	Journey creation timestamp (epoch milliseconds).	Always present
`signature`	string	Cryptographic signature for response verification.	Always present

Error Response

Field	Type	Description	Presence
`success`	boolean	Always `false` for error responses.	Always present
`data`	object	Empty object `{}`.	Always present
`message`	string	Human-readable error message.	Always present
`errors`	object[]	Array of error objects.	Always present
`errors[].code`	string	Machine-readable error code.	Always present
`errors[].type`	string	Error category.	Optional
`errors[].message`	string	Error message.	Always present
`meta.serverTimestamp`	number	Server timestamp (epoch milliseconds).	Always present
`meta.journeyType`	string	Echo of requested journey type.	Optional
`signature`	string	Cryptographic signature for response verification.	Optional

Next Steps

Save the journeyToken in your backend

Store it on your server — you’ll need it for the Journey Details API, Customer Details API, and Get Certificate API.

Pass the token to the SDK immediately

The token expires in 10 minutes. Pass it to the Web, Android, or iOS SDK to start the verification flow. Generate a new token for each session.

Do not reuse journey tokens

Each journeyToken is single-use. Once a journey is started, completed, or expired, the token cannot be reused.

Verify the response signature

Use the signature field to verify response integrity before processing.

{
  "success": true,
  "message": "Journey Token has been created successfully",
  "data": {
    "journeyToken": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "expiresAt": 1699209856789
  },
  "meta": {
    "serverTimestamp": 1699209856789,
    "journeyType": "ONBOARDING",
    "createdAt": 1699209856789
  },
  "signature": ""
}

Authorizations

x-transaction-key

string

header

required

Body

application/json

ONBOARDING
REKYC
AUTHORISE
ONE_TO_MANY

journeyType

enum<string>

default:ONBOARDING

required

Set automatically to ONBOARDING for this journey type.

Available options:

ONBOARDING

sdkConfig

object

Configuration for SDK UI/UX behavior and controls.

Show child attributes

verificationConfig

object

Configuration for verification strategy.

Show child attributes

Response

Journey created successfully

success

boolean

Always true for successful requests.

Example:

true

message

string

Success message.

Example:

"Journey Token has been created successfully"

data

object

Show child attributes

Overview

API Key Management

Journey APIs

Remote Verification

Certificate APIs

Validation APIs

Response Integrity

Create Journey V2

Journey Types

Authentication

Request Body

identifier (Conditional)

sdkConfig (Optional)

verificationConfig (Optional)

Code Examples

Response Fields

Success Response

Error Response

Next Steps

Authorizations

Body

Response

Overview

API Key Management

Journey APIs

Remote Verification

Certificate APIs

Validation APIs

Response Integrity

​Journey Types

​Authentication

​Request Body

​identifier (Conditional)

​sdkConfig (Optional)

​verificationConfig (Optional)

​Code Examples

​Response Fields

​Success Response

​Error Response

​Next Steps

Authorizations

Body

Response

Journey Types

Authentication

Request Body

identifier (Conditional)

sdkConfig (Optional)

verificationConfig (Optional)

Code Examples

Response Fields

Success Response

Error Response

Next Steps