> ## Documentation Index
> Fetch the complete documentation index at: https://umbrella-docs.info/llms.txt
> Use this file to discover all available pages before exploring further.
# Handshake (Create Journey)
> Start a verification journey and receive a UI handle
# 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
```json theme={null}
{
"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
```json theme={null}
{
"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
```ts theme={null}
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;
```