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.
- x-api-keystringrequiredDescription
- Content-TypestringDescription
- flowIdstringrequiredDescription
- userIdstringDescription
- userInfoobjectDescription
- phoneNumberstringDescription
- dateOfBirthstringDescription
- matchImagestringDescription
- emailAddressstringDescription
- externalReferenceIdstringDescription
- nameobjectDescription
- firstNamestring
- lastNamestring
- addressobjectDescription
- streetstring
- street2string
- citystring
- regionstring
- postalCodestring
- countrystringDescription
- idobjectDescription
- idTypestringDescription
- countrystringDescription
- documentNumbersarrayDescription
- countrystringDescription
- processingConfigobjectDescription
- callbackUrlstringDescription
- authKeyForCallbackstringDescription
- redirectTimeintegerDescription
- successRedirectUrlstringDescription
- failureRedirectUrlstringDescription
- journeyLinkValidityintegerDescription
- journeySessionExpiryintegerDescription
- languagestringDescription
{
"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"
}
}
{
"result": {
"journeyId": "MORTD2FO1N",
"journeyUrl": "https://kyc-preproduction.signzy.app/MORTD2FO1N",
"createdAt": 1774862133493,
"ttl": "0.17 hours"
}
}{
"error": {
"error": {
"name": "error",
"message": "flowId must be a valid UUID",
"status": 400,
"reason": "VALIDATION_ERROR",
"type": "Bad Request",
"statusCode": 400
}
}
}{
"error": {
"error": {
"message": "Unable to create journey",
"name": "error",
"reason": "Error",
"status": 409,
"statusCode": 409,
"type": "Conflict"
}
}
}{
"status": "ERROR",
"message": "Internal Server Error"
}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.