---
title: "Start onboarding"
method: POST
path: "/omni/start"
tags: ["Interview"]
---

# Start onboarding

`POST /omni/start`

This endpoint is mandatory to start any onboarding session in Incode Omni and session can be monitored on the Incode Dashboard.
And it generates token which should be used for the authentication of future subsequent calls.

## Headers

- `api-version` string, required

## Request body

- StartRequest
  - `language` string — Language code to be used when doing speech to text. Possible values: en-US, es-ES, pt-BR.
  - `externalId` string — Id that identifies user in clients system should be used for externalId. (Deprecated, use externalCustomerId instead)
  - `externalCustomerId` string — Id that identifies user in clients external system.
  - `uuid` string — uuid key used in redis, can be used as an alternative to sending interviewId.
  - `configurationId` string — Id of the flow to be used for this onboarding.
  - `redirectionUrl` string — Url the user will be redirected to after finishing the onboarding successfully.
  - `integrationReference` string — Optional integration reference.
  - `urlUuid` string — Url uuid key used in redis. Will be validated in start if qrPhishingResistance is ON.
  - `customFields` object — Used to send any additional information in key value pair format. Max fields: {maxEntries}, max key length: {keyMaxLength}, max value length: {valueMaxLength}

## Response `200`

OK

- StartResponse
  - `interviewId` string — Identifies the onboarding session that is initialized. Can be used for fetching data about that session in future calls.
  - `token` string — Internal JWT token used for the future subsequent calls. It is the value for X-Incode-Hardware-Id header in all other calls.
  - `interviewCode` string — This value is used for connecting to conference call.
  - `flowType` 'configuration' | 'flow' | 'workflow' — (only if configurationId is sent in request). Type of the flow used. Could be flow (in most cases), or legacy type configuration (not used anymore).
  - `idCaptureTimeout` integer — Number of seconds after which manual capture button should be shown to the user, while capturing ID when ID is detected.
  - `idDetectionTimeout` integer — Number of seconds after which manual capture button should be shown to the user, if ID is not detected.
  - `selfieCaptureTimeout` integer — Number of seconds after which manual capture button should be shown to the user, while capturing selfie.
  - `idCaptureRetries` integer — Number of ID captures after which user should be taken to next screen.
  - `selfieCaptureRetries` integer — Number of selfie captures after which user should be taken to next screen.
  - `curpValidationRetries` integer — Number of curp validations after which user should be taken to next screen. (only for Mexico)
  - `clientId` string — Customer specific clientId that corresponds to api key.
  - `env` string — Server environment. Could be one of: stage, demo, saas.
  - `existingSession` boolean — It's true if interviewId corresponds to an existing Onboarding Session.

## Other responses

- `400` — Custom error statuses: - 4026: Invalid uuid parameter - 4027: Invalid configurationId - 4028: Flow is not activated - 4081: Invalid parameters for validation - 4082: Start endpoint version forbidden in flow/workflow

---

[API](https://skmtc.net/incode/apis/incode-omni-api.md) · [All operations](https://skmtc.net/incode/apis/incode-omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/incode/incode-omni-api/versions/30cd6d926ea3/schema)