---
title: Create Journey API
slug: one-touch-kyc/create-journey-api
createdAt: 2026-07-29T08:07:55.441Z
---

## 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.

:::ApiMethodV2
```json
{
  "name": "Create Journey API",
  "method": "POST",
  "url": "https://onetouch-preproduction.signzy.app/otk-service/v1/create-journey-url",
  "description": "Preproduction Endpoint",
  "tab": "examples",
  "examples": {
    "languages": [
      {
        "id": "R0RdWORaTI2-fa9KuriP1",
        "language": "json",
        "code": "{\n   \"flowId\": \"<flow_id>\",\n   \"userId\": \"<user_id>\",\n   \"userInfo\": {\n       \"phoneNumber\": \"string\",\n       \"dateOfBirth\": \"string\",\n       \"matchImage\":\"<image_url>\",\n       \"emailAddress\": \"string\",\n       \"externalReferenceId\": \"string\",\n       \"name\": {\n         \"firstName\": \"string\",\n         \"lastName\": \"string\"\n       },\n       \"address\": {\n         \"street\": \"string\",\n         \"street2\": \"string\",\n         \"city\": \"string\",\n         \"region\": \"string\",\n         \"postalCode\": \"string\",\n         \"country\": \"string\"\n       },\n       \"id\": {\n         \"idType\": \"string\",\n         \"country\": \"string\"\n       }\n     },\n   \"processingConfig\": {\n       \"callbackUrl\": \"<callback_url>\",\n       \"authKeyForCallback\": \"string\",\n       \"redirectTime\": 0,\n       \"successRedirectUrl\": \"<success_redirect_url>\",\n       \"failureRedirectUrl\": \"<failure_redirect_url.com\",\n       \"journeyLinkValidity\": 3600,\n       \"language\": \"string\"\n   }\n}\n"
      }
    ],
    "selectedLanguageId": "R0RdWORaTI2-fa9KuriP1"
  },
  "results": {
    "languages": [
      {
        "id": "eJWb1tv6alvBuJ4Th02yX",
        "language": "200",
        "code": "{\n    \"result\": {\n        \"journeyId\": \"MORTD2FO1N\",\n        \"journeyUrl\": \"https://kyc-preproduction.signzy.app/MORTD2FO1N\",\n        \"createdAt\": 1774862133493,\n        \"ttl\": \"0.17 hours\"\n    }\n}",
        "customLabel": ""
      },
      {
        "id": "iRc-INYU2wLcc8fAANy5q",
        "language": "400",
        "code": "{\n    \"error\": {\n        \"error\": {\n            \"name\": \"error\",\n            \"message\": \"flowId must be a valid UUID\",\n            \"status\": 400,\n            \"reason\": \"VALIDATION_ERROR\",\n            \"type\": \"Bad Request\",\n            \"statusCode\": 400\n        }\n    }\n}"
      },
      {
        "id": "jHV-LtBZAzjKPvZD0q86q",
        "language": "409",
        "code": "{\n    \"error\": {\n        \"error\": {\n            \"message\": \"Unable to create journey\",\n            \"name\": \"error\",\n            \"reason\": \"Error\",\n            \"status\": 409,\n            \"statusCode\": 409,\n            \"type\": \"Conflict\"\n        }\n    }\n}"
      },
      {
        "id": "eq9roe92hjqB6i4JpyVfZ",
        "language": "500",
        "code": "{\n    \"status\": \"ERROR\",\n    \"message\": \"Internal Server Error\"\n}"
      }
    ],
    "selectedLanguageId": "eJWb1tv6alvBuJ4Th02yX"
  },
  "request": {
    "pathParameters": [],
    "queryParameters": [],
    "headerParameters": [
      {
        "name": "x-api-key",
        "kind": "required",
        "type": "string",
        "description": "your API key from the team settings",
        "": "your API key from the team settings"
      },
      {
        "name": "Content-Type",
        "kind": "optional",
        "type": "string",
        "description": "application/json",
        "": "application/json"
      }
    ],
    "bodyDataParameters": [
      {
        "name": "flowId",
        "kind": "required",
        "type": "string",
        "description": "The Flow this journey should run (from your Flows dashboard).",
        "": "The Flow this journey should run (from your Flows dashboard)."
      },
      {
        "name": "userId",
        "kind": "optional",
        "type": "string",
        "description": "Your own internal identifier for this user, echoed back in results.",
        "": "Your own internal identifier for this user, echoed back in results."
      },
      {
        "name": "userInfo",
        "kind": "optional",
        "type": "object",
        "description": "Pre-fill known user details so they don't have to re-enter them. See below.",
        "": "object",
        "children": [
          {
            "name": "phoneNumber",
            "kind": "optional",
            "type": "string",
            "description": "User's phone number"
          },
          {
            "name": "dateOfBirth",
            "kind": "optional",
            "type": "string",
            "description": "YYYY-MM-DD format only"
          },
          {
            "name": "matchImage",
            "kind": "optional",
            "type": "string",
            "description": "Image URL in jpg/png format"
          },
          {
            "name": "emailAddress",
            "kind": "optional",
            "type": "string",
            "description": "Must be a valid email if provided"
          },
          {
            "name": "externalReferenceId",
            "kind": "optional",
            "type": "string",
            "description": "Free-form reference for your own records"
          },
          {
            "name": "name",
            "kind": "optional",
            "type": "object",
            "description": "Full name which can be used for later cross name matching",
            "children": [
              {
                "name": "firstName",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "lastName",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ]
          },
          {
            "name": "address",
            "kind": "optional",
            "type": "object",
            "description": "Address details of the user which can be used for later cross matching",
            "children": [
              {
                "name": "street",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "street2",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "city",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "region",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "postalCode",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "country",
                "kind": "optional",
                "type": "string",
                "description": "2 Letter ISO Code of the country (CA,US,IN...)"
              }
            ]
          },
          {
            "name": "id",
            "kind": "optional",
            "type": "object",
            "description": "ID information to prefill, idType, idType2, idType3...",
            "children": [
              {
                "name": "idType",
                "kind": "optional",
                "type": "string",
                "description": "Expected ID document type(s)"
              },
              {
                "name": "country",
                "kind": "optional",
                "type": "string",
                "description": "2 Letter ISO Code of the country (CA,US,IN...)"
              },
              {
                "name": "documentNumbers",
                "kind": "optional",
                "type": "array",
                "description": "[{ \"type\": \"...\", \"country\": \"...\", \"value\": \"...\" }]"
              }
            ]
          },
          {
            "name": "country",
            "kind": "optional",
            "type": "string",
            "description": "2 Letter ISO Code of the country (CA,US,IN...)"
          }
        ],
        "schema": [
          {
            "name": "phoneNumber",
            "kind": "optional",
            "type": "string",
            "description": "User's phone number"
          },
          {
            "name": "dateOfBirth",
            "kind": "optional",
            "type": "string",
            "description": "YYYY-MM-DD format only"
          },
          {
            "name": "matchImage",
            "kind": "optional",
            "type": "string",
            "description": "Image URL in jpg/png format"
          },
          {
            "name": "emailAddress",
            "kind": "optional",
            "type": "string",
            "description": "Must be a valid email if provided"
          },
          {
            "name": "externalReferenceId",
            "kind": "optional",
            "type": "string",
            "description": "Free-form reference for your own records"
          },
          {
            "name": "name",
            "kind": "optional",
            "type": "object",
            "description": "Full name which can be used for later cross name matching",
            "children": [
              {
                "name": "firstName",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "lastName",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ]
          },
          {
            "name": "address",
            "kind": "optional",
            "type": "object",
            "description": "Address details of the user which can be used for later cross matching",
            "children": [
              {
                "name": "street",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "street2",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "city",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "region",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "postalCode",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "country",
                "kind": "optional",
                "type": "string",
                "description": "2 Letter ISO Code of the country (CA,US,IN...)"
              }
            ]
          },
          {
            "name": "id",
            "kind": "optional",
            "type": "object",
            "description": "ID information to prefill, idType, idType2, idType3...",
            "children": [
              {
                "name": "idType",
                "kind": "optional",
                "type": "string",
                "description": "Expected ID document type(s)"
              },
              {
                "name": "country",
                "kind": "optional",
                "type": "string",
                "description": "2 Letter ISO Code of the country (CA,US,IN...)"
              },
              {
                "name": "documentNumbers",
                "kind": "optional",
                "type": "array",
                "description": "[{ \"type\": \"...\", \"country\": \"...\", \"value\": \"...\" }]"
              }
            ]
          },
          {
            "name": "country",
            "kind": "optional",
            "type": "string",
            "description": "2 Letter ISO Code of the country (CA,US,IN...)"
          }
        ]
      },
      {
        "name": "processingConfig",
        "kind": "optional",
        "type": "object",
        "description": "Callback/redirect/expiry behavior for this specific journey. ",
        "": "Callback/redirect/expiry behavior for this specific journey. ",
        "children": [
          {
            "name": "callbackUrl",
            "kind": "optional",
            "type": "string",
            "description": "Overrides your team's default callback URL for this journey only in URL format"
          },
          {
            "name": "authKeyForCallback",
            "kind": "optional",
            "type": "string",
            "description": "Sent back to you in the callback's Authorization header"
          },
          {
            "name": "redirectTime",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds to wait before auto-redirecting the user after completion"
          },
          {
            "name": "successRedirectUrl",
            "kind": "optional",
            "type": "string",
            "description": "Where to send the user after a successful journey"
          },
          {
            "name": "failureRedirectUrl",
            "kind": "optional",
            "type": "string",
            "description": "Where to send the user after a failed/terminated journey"
          },
          {
            "name": "journeyLinkValidity",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds the link stays usable before it expires (minimum 600)"
          },
          {
            "name": "journeySessionExpiry",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds a started session stays active before timing out (minimum 600)"
          },
          {
            "name": "language",
            "kind": "optional",
            "type": "string",
            "description": "Language code for the journey to start with"
          }
        ],
        "schema": [
          {
            "name": "callbackUrl",
            "kind": "optional",
            "type": "string",
            "description": "Overrides your team's default callback URL for this journey only in URL format"
          },
          {
            "name": "authKeyForCallback",
            "kind": "optional",
            "type": "string",
            "description": "Sent back to you in the callback's Authorization header"
          },
          {
            "name": "redirectTime",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds to wait before auto-redirecting the user after completion"
          },
          {
            "name": "successRedirectUrl",
            "kind": "optional",
            "type": "string",
            "description": "Where to send the user after a successful journey"
          },
          {
            "name": "failureRedirectUrl",
            "kind": "optional",
            "type": "string",
            "description": "Where to send the user after a failed/terminated journey"
          },
          {
            "name": "journeyLinkValidity",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds the link stays usable before it expires (minimum 600)"
          },
          {
            "name": "journeySessionExpiry",
            "kind": "optional",
            "type": "integer",
            "description": "Seconds a started session stays active before timing out (minimum 600)"
          },
          {
            "name": "language",
            "kind": "optional",
            "type": "string",
            "description": "Language code for the journey to start with"
          }
        ]
      }
    ],
    "formDataParameters": []
  },
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  },
  "hasTryItOut": false,
  "autoGeneratedAnchorSlug": "create-journey-api",
  "legacyHash": "Xm1UxzV4w5S9y0anIUN9X"
}
```
:::

**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`**&#x20;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`**&#x20;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:**

```bash
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": "john.doe@example.com",
      "name": { "firstName": "John", "lastName": "Doe" },
      "country": "IN"
    },
    "processingConfig": {
      "successRedirectUrl": "https://yourapp.com/kyc/success",
      "failureRedirectUrl": "https://yourapp.com/kyc/failed",
      "journeyLinkValidity": 3600
    }
  }'
```

**Example response:**

```json
{
  "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.

***

##

***

##

