Create a new Incode onboarding session

Considerations

• You must include a flowId from a previously created Incode Flow when you start an onboarding session. This ID links the new session to a specific flow. That Flow's configurations and thresholds are used when the verifications are executed by the Incode APIs.
• Onboarding Sessions must be created in your application back end (never directly from the front-end application) using the Incode Omni API, specifically the /omni/start endpoint.
• You must create a new onboarding session every time an onboarding attempt is executed, even if it is related to the same user. This requirement preserves session integrity and improves performance analytics.

Session creation

The following diagram shows the initial steps that happen your application, both front and back end. Once your application requests a session start, the Omni API is invoked with the /omni/start endpoint.

The /omni/start endpoint

This endpoint is responsible for creating new Incode sessions. It returns a JSON response that contains metadata about the newly created session.

Check the start onboarding documentation for a complete reference of the endpoint's inputs and output.

/omni/start requests

This request uses the following header values and body key/value pairs:

Headers

JSON Request Body

curl --location '{user.DEMO_URL}omni/start' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'api-version: 1.0' \
--header 'x-api-key: <<APIKEY>>' \
--data '{
	"countryCode": "ALL",
    "configurationId": "65283accd410a1dd7e965479",
    "externalCustomerId": "someuser0001",
    "redirectionUrl": "http://example.com/"
}'

const params = {
  configurationId: <<flowId>,
  countryCode: "ALL",
  language: "en-US",
  //externalCustomerId: "someuser0001", //The Id if the user in your system
  //redirectionUrl: "http://example.com/", //The url where the user will be redirected at the end of the onboarding
  
};

const headers = {
  accept: 'application/json',
  'content-type': 'application/json',
  'x-api-key': '<<APIKEY>>',
  'api-version': '1.0'
};

const options = {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(params)
};

const response = await fetch('{user.DEMO_URL}omni/start', options);

const {token, interviewId} = response.json();

Handling the /omni/start response

Your application back-end must process the response, which returns multiple values. The following values are specifically needed for your web application.

The interviewId

A unique interviewId string (or Session ID) is assigned when a new session is created. Store each interviewId you create in your application back end.

The session token

The Web SDK needs a valid session token to communicate with the Incode API. The /omni/start response returns a new token value each time you create a new session. This JSON Web Token is used to call the Omni APIs required as part of the onboarding process. Learn more about Session Tokens here ↗.

Send back only the token and the interviewId to the front end. These are the only keys to the omni/start response, and the SDKs need these values to work with the Incode Omni API.