Handshake (Create Journey)

The handshake is an API call that creates a verification journey and returns a uiHandle. Create a journey and receive:

transactionId — internal identifier for the journey
uiHandle — URL used to start the hosted verification UI

Handshake Request

The handshake request initiates a customer journey. Please note that:

You define which components of the IDCanopy product offering you would like to consume with this request.
You can configure each component as well as validation data.
Define the process name, which will appear on the invoice as billing item.
You can enable a developer mode by switching on “magicFlow” in the handshake.

Request Structure

{
  "journey": {
    "customerId": "string",
    "processName": "string"
  },
  "validationData": {
    "fullName": "John Doe",
    "DOB": "1980/01/31",
    "address": {
      "streetAddress": "123 Main Street",
      "locality": "Anytown",
      "region": "CA",
      "postalCode": "90210",
      "country": "US"
    },
    "iban": "DE11XXXX3245664",
    "phoneNumber": "+4915738901234",
    "unstructuredInput": "This is some free unstructured text input for AI, OSINT and other analysis. John@doe.com aged 44, NHL player at Detroit RedWings; He might be in debt and has a Chinese Crested as dog."
  },
  "passThroughData": {
    "userId": "12345"
  },
  "steps": [
    {
      "id": "1",
      "type": "documentVerification",
      "interface": "Umbrella Toolbox",
      "blocking": true,
      "configuration": {
        "extraForensics": false,
        "biometricMatching": true,
        "liveness": true,
        "photoIdentPlus": false,
        "permittedDocuments": [
          {
            "idType": "passport"
          },
          {
            "idType": "nationalId",
            "bloc": "EEA",
            "excludedCountries": ["DK"]
          },
          {
            "idType": "driversLicense",
            "countries": ["BG"]
          }
        ]
      }
    },
    {
      "id": "2",
      "type": "amlScreening",
      "interface": "Umbrella Toolbox",
      "blocking": true,
      "configuration": {
        "monitoring": false,
        "dossier": true
      }
    },
    {
      "id": "3",
      "type": "mobileIdent",
      "interface": "Umbrella Toolbox",
      "blocking": false,
      "configuration": {}
    },
    {
      "id": "4",
      "type": "idvProtocol",
      "interface": "Umbrella Toolbox",
      "blocking": false,
      "configuration": {}
    }
  ],
  "matchName": "strict",
  "matchDob": true,
  "magicFlow": false,
  "validitySuperpower": false,
  "journeyDuration": "standard"
}

Request DTO

Field	Type	Required	Description
`journey`	object	Yes	Verification journey configuration root.
`journey.customerId`	string	Yes	Unique identifier for the customer journey.
`journey.processName`	string	Yes	Human-readable process name (appears on invoices/billing).
`validationData`	object	No	User data object for validation and matching.
`validationData.fullName`	string	No	Full name (e.g., `John Doe`).
`validationData.DOB`	string	No	Date of birth, format `YYYY/MM/DD`.
`validationData.address`	object	No	Address object with structured fields or single-line string.
`address.streetAddress`	string	No	Street and number (e.g., `123 Main Street`).
`address.locality`	string	No	City / town (e.g., `Anytown`).
`address.region`	string	No	State / province / region (e.g., `CA`).
`address.postalCode`	string	No	Postal / ZIP code (e.g., `90210`).
`address.country`	string	No	Country code (ISO 3166-1 alpha-2, e.g., `US`).
`validationData.iban`	string	No	International Bank Account Number (e.g., `DE11XXXX3245664`).
`validationData.phoneNumber`	string	No	Phone in E.164 format (e.g., `+4915738901234`).
`validationData.unstructuredInput`	string	No	Free-form text for AI analysis (e.g., email, profession, additional context).
`passThroughData`	object	No	Custom data to correlate with your internal systems.
`passThroughData.userId`	string	No	Your internal user reference (e.g., `12345`).
`steps`	array	No	Array of verification steps in order. Omit to use pre-defined process.
`steps[].id`	string	Yes	Step identifier (e.g., `1`, `2`).
`steps[].type`	string	Yes	Step type: `documentVerification` \| `amlScreening` \| `mobileIdent` \| `idvProtocol`.
`steps[].interface`	string	Yes	UI interface to use (e.g., `Umbrella Toolbox`).
`steps[].blocking`	boolean	Yes	Whether this step blocks the journey on failure (e.g., `true`).
`steps[].configuration`	object	Yes	Step-specific configuration (see below).
`configuration.extraForensics`	boolean	No	Enable extra forensic checks for document verification (e.g., `false`).
`configuration.biometricMatching`	boolean	No	Enable face ↔ document photo matching (e.g., `true`).
`configuration.liveness`	boolean	No	Enable liveness checks during selfie capture (e.g., `true`).
`configuration.photoIdentPlus`	boolean	No	Enable additional assisted checks (e.g., `false`).
`configuration.permittedDocuments`	array	No	Array of allowed document types and regions.
`permittedDocuments[].idType`	string	Yes	Document type: `passport` \| `nationalId` \| `driversLicense`.
`permittedDocuments[].bloc`	string	No	Geo/economic bloc for bulk allow (e.g., `EEA`).
`permittedDocuments[].countries`	array	No	Allowed country codes (e.g., `["BG"]`).
`permittedDocuments[].excludedCountries`	array	No	Country codes to exclude when using `bloc` (e.g., `["DK"]`).
`configuration.monitoring`	boolean	No	Enable ongoing monitoring registration for AML (e.g., `false`).
`configuration.dossier`	boolean	No	Return enriched dossier details for AML (e.g., `true`).
`matchName`	string	No	Name matching mode: `strict` \| `fuzzy` \| `none` (e.g., `strict`).
`matchDob`	boolean	No	Enable DoB matching (requires `validationData.DOB`; e.g., `true`).
`magicFlow`	boolean	No	Enable developer/test mode (e.g., `false`).
`validitySuperpower`	boolean	No	Extend uiHandle validity from 5 → 60 minutes (e.g., `false`).
`journeyDuration`	string	No	Auto-close timeout: `short` (≈150s) \| `standard` (≈300s) \| `long` (≈600s) \| `eternity` (e.g., `standard`).

Handshake Response

{
  "transactionId": "string",
  "uiHandle": "https://verification.idcanopy.com/init?verificationToken=VERIFICATION_TOKEN",
  "initTimestamp": "string"
}

Handshake Response Structure

Field	Type	Description
`transactionId`	string	Sensitive journey identifier for tracking/correlation. Do not expose to end-users.
`uiHandle`	string (URL)	Short-lived URL to launch the hosted UI (≈5 min by default; extend via `validitySuperpower`). Use in an iframe or redirect.
`initTimestamp`	string	Timestamp when the journey was initialized.

Using the SDK Example

const response = await fetch("https://api-umbrella.io/api/services/sdk/universal/handshake", {
  method: "POST",
  headers: {
    authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(handshakeDto)
});

const { uiHandle } = await response.json();

// Option A: iframe
document.getElementById("kyc-frame").src = uiHandle;

// Option B: redirect
// window.location.href = uiHandle;
<iframe id="kyc-frame" style="width:100%;height:100vh;border:0;"></iframe>

​Handshake (Create Journey)

​Handshake Request

​Request Structure

​Request DTO

​Handshake Response

​Handshake Response Structure

​Using the SDK Example

Handshake (Create Journey)

Handshake Request

Request Structure

Request DTO

Handshake Response

Handshake Response Structure

Using the SDK Example