---
title: Create Journey Link
slug: us-apis/create-journey-link
createdAt: 2024-05-20T08:20:43.530Z
---

# Overview and Purpose

## Overview

The Create Journey URL API generates a unique journey link for each user, which can be integrated into a business's mobile app or website. This link directs users to the KYC process configured by the client.

## Purpose

The purpose of this API is to create a unique and secure URL for the KYC journey, allowing end users to complete their identity verification process seamlessly through the provided link.

# API Details

**Flow Information&#x20;**: Includes the flowId (identifier for the configured KYC flow), version (version of the flow), and test (boolean indicating if it's a test flow).

**Result Object&#x20;**: Contains journeyId (unique identifier for the journey), journeyUrl (URL for the KYC process), createdAt (timestamp of creation), and ttl (time-to-live for the URL, e.g., "24 hours").

### Endpoint Details

Request type - **POST**

**Pre-prod Environment** ->

:::BlockQuote
[[https://api-preproduction.signzy.app/api/v3/otk-service/create-journey-url](https://api-preproduction.signzy.app/api/v3/otk-service/create-journey-url)](https://api-preproduction.signzy.app/api/v3/liveness-secure/createUrl)
:::

**India Production environment&#x20;**->

[https://api.signzy.app/api/v3/otk-service/create-journey-url](https://api.signzy.app/api/v3/otk-service/create-journey-url)

**US Production environment&#x20;**->

[https://api.signzy.us/api/v3/otk-service/create-journey-url](https://api.signzy.us/api/v3/otk-service/create-journey-url)

**Canada Production environment&#x20;**->

[https://api.signzy.ca/api/v3/otk-service/create-journey-url](https://api.signzy.ca/api/v3/otk-service/create-journey-url)

**UAE Production environment&#x20;**->

[[https://api.signzy.ae/api/v3/otk-service/create-journey-url](https://api.signzy.ae/api/v3/otk-service/create-journey-url)](https://api.signzy.app/api/v3/liveness-secure/createUrl)



## Sample Request

:::CodeblockTabs
PreProduction

```json
curl --location 'https://api-preproduction.signzy.app/api/v3/otk-service/create-journey-url' \
--header 'Content-Type: application/json' \
--header 'Authorization: <Auth-token>' \
--data '{
    "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": "https://www.callbackUrl.com",
        "authKeyForCallback": "string"
        "redirectTime": 0,
        "successRedirectUrl": "https://www.successRedirectUrl.com",
        "failureRedirectUrl": "https://www.failureRedirectUrl.com",
        "journeyLinkValidity": 3600,
        "language": "en"
    }
}'
```
:::

## API Request Body Parameters

| Parameter                            | Data Type | Description                                                                                                                                                                                                                                                                                                                                                                             | Required                                                                                                                      |
| ------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| flowId                               | string    | unique id for flow.                                                                                                                                                                                                                                                                                                                                                                     | yes                                                                                                                           |
| userId                               | string    | userId of client                                                                                                                                                                                                                                                                                                                                                                        | no                                                                                                                            |
| userInfo                             | object    | information about the user                                                                                                                                                                                                                                                                                                                                                              | no                                                                                                                            |
| userInfo.phoneNumber                 | number    | phone number of the user                                                                                                                                                                                                                                                                                                                                                                | no                                                                                                                            |
| userInfo.dateOfBirth                 | date      | dob of the user                                                                                                                                                                                                                                                                                                                                                                         | no                                                                                                                            |
| userInfo.matchImage                  | string    | The URL of the face image used for face match comparison against the selfie captured during the selfie analysis process.                                                                                                                                                                                                                                                                | **Required:&#x20;**&#x4F;nly for Face Verification–only flows<br /><br />**Not Required:&#x20;**&#x46;or all other flow types |
| userInfo.emailAddress                | string    | emailId of the user                                                                                                                                                                                                                                                                                                                                                                     | no                                                                                                                            |
| serInfo.externalReferenceId          | string    | External reference no, eg. client's userID                                                                                                                                                                                                                                                                                                                                              | no                                                                                                                            |
| userInfo.name                        | object    | name of the user                                                                                                                                                                                                                                                                                                                                                                        | no<br />                                                                                                                      |
| userInfo.name.firstName              | string    | first name of the user                                                                                                                                                                                                                                                                                                                                                                  | no                                                                                                                            |
| userInfo.name.lastName               | string    | last name of the user                                                                                                                                                                                                                                                                                                                                                                   | no                                                                                                                            |
| userInfo.address                     | object    | address of the user                                                                                                                                                                                                                                                                                                                                                                     | no                                                                                                                            |
| userInfo.address.street              | string    | specifics of the user's address                                                                                                                                                                                                                                                                                                                                                         | no                                                                                                                            |
| userInfo.address.street2             | string    | specifics of the user's address                                                                                                                                                                                                                                                                                                                                                         | no                                                                                                                            |
| userInfo.address.city                | string    | city                                                                                                                                                                                                                                                                                                                                                                                    | no                                                                                                                            |
| userInfo.address.region              | string    | region                                                                                                                                                                                                                                                                                                                                                                                  | no                                                                                                                            |
| userInfo.address.postalCode          | string    | postal code                                                                                                                                                                                                                                                                                                                                                                             | no                                                                                                                            |
| userInfo.address.country             | string    | country                                                                                                                                                                                                                                                                                                                                                                                 | no                                                                                                                            |
| userInfo.id                          | Object    | details of user's id                                                                                                                                                                                                                                                                                                                                                                    | no                                                                                                                            |
| userInfo.id.idType                   | string    | id type                                                                                                                                                                                                                                                                                                                                                                                 | no                                                                                                                            |
| userInfo.id.country                  | string    | The country where the idType is valid                                                                                                                                                                                                                                                                                                                                                   | no                                                                                                                            |
| processingConfig                     | object    | This object contains all the neccessary configuration for the journey                                                                                                                                                                                                                                                                                                                   | no                                                                                                                            |
| processingConfig.callbackUrl         | string    | The callbackUrl where the result of the journey can be posted post verification                                                                                                                                                                                                                                                                                                         | no                                                                                                                            |
| processingConfig.authKeyForCallback  | string    | Auth key in case required for callback url                                                                                                                                                                                                                                                                                                                                              | no                                                                                                                            |
| processingConfig.redirectTime        | number    | The time in **seconds** after which user will be redirected to redirectUrls                                                                                                                                                                                                                                                                                                             | no                                                                                                                            |
| processingConfig.successRedirectUrl  | string    | The user will be redirected to this URL post succesful flow                                                                                                                                                                                                                                                                                                                             | no                                                                                                                            |
| processingConfig.failureRedirectUrl  | string    | The user will be redirected to this URL post unsuccessful flow                                                                                                                                                                                                                                                                                                                          | no                                                                                                                            |
| processingConfig.journeyLinkValidity | number    | The journey url will be valid for the specified **seconds** only<br />Default value -> 3600 seconds                                                                                                                                                                                                                                                                                     | no                                                                                                                            |
| processingConfig.language            | string    | We use **ISO 639-1** standard two-letter codes to represent languages. This is an internationally recognized format used in software systems, APIs, and localization processes. **This will overwrite the language selected in the flow.&#x20;**<br />Example - <br /><br />- "hi" - Hindi<br />- "en" - English<br />- "es" - Spanish<br />- "ar" - Arabic<br />- "ru" - Russian<br /> | n                                                                                                                             |

## Sample API Response

:::CodeblockTabs
200

```json
{
    "result": {
        "journeyId": "abcdef",
        "journeyUrl": "https://kyc-preproduction.signzy.app/abcdef",
        "createdAt": 1716184320411,
        "ttl": "24 hours"
    }
}

```
:::

## API Response Body Parameter

| Parameter  | Data Type | Description                                        |
| ---------- | --------- | -------------------------------------------------- |
| journeyId  | string    | journey id                                         |
| journeyUrl | string    | Url of the joureny                                 |
| createdAt  | number    | the timestamp of when the journey link was created |
| ttl        | string    | Link validity upto                                 |

## Error Code and Response Mapping

:::CodeblockTabs
400 (Bad Request)

```json
{
  "error": {
     "name": "error",
     "message": "Bad Input and description ",
     "status": 400,
     "reason": "VALIDATION_ERROR",
     "type": "Bad Request",
     "statusCode": 400
  }
}
```

401(Unauthorized)

```json
{
  "error": {
     "name": "error",
     "message": "Invalid authentication credentials",
     "status": 401,
     "reason": "AUTHENTICATION_ERROR",
     "type": "Bad Request",
     "statusCode": 401
  }
}
```

403 (Forbidden)

```json
{
  "error": {
     "name": "error",
     "message": "Forbidden",
     "reason": "ERROR",
     "type": "Bad Request",
     "statusCode": "403"
  }
}
```

500 (Internal Server Error)

```json
{
  "error": {
     "name": "error",
     "message": "Internal server error",
     "status": 500,
     "reason": "ERROR",
     "type": "Bad Request",
     "statusCode": 500
  }
}
```

409(Upstream Down

```json
{
  "error": {
     "name": "error",
     "message": "Upstream Down",
     "status": 409,
     "reason": "ERROR",
     "type": "Bad Request",
     "statusCode": 409
  }
}
```
:::

| **Field**    | **Type** | **Description**                                     |
| ------------ | -------- | --------------------------------------------------- |
| `name`       | string   | Text displayed on the screen explaining error type. |
| `reason`     | string   | Reason for the error.                               |
| `status`     | number   | HTTP status code.                                   |
| `message`    | string   | Error message indicating an upstream error.         |
| `type`       | string   | Error type.                                         |
| `statusCode` | number   | Status code representing the error scenario.        |

:::hint{type="info"}
### Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [help@signzy.com](#). We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!
:::

