Create Journey API

Create a Journey

Generates a hosted verification link tied to a specific Flow. Send the link to your end user (by email, SMS, in-app redirect, etc.) — they complete the KYC steps you configured in that Flow, and you're notified via callback when they're done.

Create Journey API

Preproduction Endpoint

POST

https://onetouch-preproduction.signzy.app/otk-service/v1/create-journey-url

{
   "flowId": "<flow_id>",
   "userId": "<user_id>",
   "userInfo": {
       "phoneNumber": "string",
       "dateOfBirth": "string",
       "matchImage":"<image_url>",
       "emailAddress": "string",
       "externalReferenceId": "string",
       "name": {
         "firstName": "string",
         "lastName": "string"
       },
       "address": {
         "street": "string",
         "street2": "string",
         "city": "string",
         "region": "string",
         "postalCode": "string",
         "country": "string"
       },
       "id": {
         "idType": "string",
         "country": "string"
       }
     },
   "processingConfig": {
       "callbackUrl": "<callback_url>",
       "authKeyForCallback": "string",
       "redirectTime": 0,
       "successRedirectUrl": "<success_redirect_url>",
       "failureRedirectUrl": "<failure_redirect_url.com",
       "journeyLinkValidity": 3600,
       "language": "string"
   }
}

Headers: x-api-key: <your-api-key>, Content-Type: application/json

Body:

Field	Type	Required	Description
flowId	string	Yes	The Flow this journey should run (from your Flows dashboard).
userId	string	No	Your own internal identifier for this user, echoed back in results.
userInfo	object	No	Pre-fill known user details so they don't have to re-enter them. See below.
processingConfig	object	No	Callback/redirect/expiry behavior for this specific journey. See below.

userInfo fields (all optional):

Field	Type	Notes
phoneNumber	string	User phone number
emailAddress	string	Must be a valid email if provided
dateOfBirth	string	YYYY-MM-DD
clientUserId	string	Alternate identifier on your side
externalReferenceId	string	Free-form reference for your own records
name.firstName, name.lastName	string
address.street, .street2, .city, .region, .postalCode, .country	string	country is a 2-letter ISO code
id.idType, .idType2, .idType3	string	Expected ID document type(s)
id.country	string	2-letter ISO code
id.documentNumbers	array	[{ "type": "...", "country": "...", "value": "..." }]
country	string	2-letter ISO code

processingConfig fields (all optional — fall back to your team-level defaults if omitted):

Field	Type	Notes
callbackUrl	string (URL)	Overrides your team's default callback URL for this journey only
authKeyForCallback	string	Sent back to you in the callback's Authorization header
language	string	Language code for the hosted verification UI
redirectTime	integer	Seconds to wait before auto-redirecting the user after completion
successRedirectUrl	string (URL)	Where to send the user after a successful verification
failureRedirectUrl	string (URL)	Where to send the user after a failed/rejected verification
journeyLinkValidity	integer	Seconds the link stays usable before it expires (minimum 600)
journeySessionExpiry	integer	Seconds a started session stays active before timing out (minimum 600)

Example request:

curl -X POST "https://<your-environment-domain>/api/v1/journeys/create-url" \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "flowId": "17d7d5c6-0f92-4cd5-93ce-2d7461ce4440",
    "userId": "user-98765",
    "userInfo": {
      "emailAddress": "[email protected]",
      "name": { "firstName": "John", "lastName": "Doe" },
      "country": "IN"
    },
    "processingConfig": {
      "successRedirectUrl": "https://yourapp.com/kyc/success",
      "failureRedirectUrl": "https://yourapp.com/kyc/failed",
      "journeyLinkValidity": 3600
    }
  }'

Example response:

{
  "success": true,
  "message": "Create Journey URL executed successfully",
  "data": {
    "journeyId": "7QZY374O30",
    "url": "https://kyc.example.com/journey/7QZY374O30",
    "ttl": 3600,
    "createdAt": "2026-07-29T10:30:00Z"
  }
}

Send data.url to your end user. The link expires after journeyLinkValidity seconds (or your account default) if the user never opens it.

One Touch KYC

One Touch KYC

Create Journey API

Create a Journey

One Touch KYC

One Touch KYC

Create Journey API

Create a Journey

﻿

﻿