Creating a new Incode Onboarding Session

Considerations

• You will need a flowId from a previously created Incode Flow.
• 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.

Session creation flow

Let’s take a look at the basic process for creating a new Incode Session and its usage with our SDKs.

The /omni/start endpoint.

This endpoint is responsible for creating new Incode sessions.

As you can see in the diagram, the /omni/start endpoint is requested immediately after the page is opened through a custom endpoint in your application backend.

The /omni/start returns a JSON response that contains metadata about the newly created Incode session.

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

/omni/start Requests examples:

Be aware of the headers and the request body needed for this request:

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

You must process the response in your application backend after creating a new Incode Onboarding Session.

The /omni/start response will return multiple values. For now, we will focus on the values 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 backend.

The session token

The Web SDK needs a valid session token to communicate with the Incode API. The /omni/start will return a new token each time you create a new session.

Send back only the token and the interviewId to the frontend

token and interviewId are the only keys to the omni/start response, and the SDKs need to work with the Incode Omni API.

Best Practices

Always use a configurationId

It is mandatory to use a configurationId when a session is created. This ID links the new onboarding session to that specific flow, and all the configurations set on that flow (thresholds) are used when the verifications are executed by the Incode APIs.

Create a new session for every onboarding attempt

It is mandatory to create a new onboarding session every time that an onboarding attempt it is executed even if it is related to the same user, it is required due the following.

• To preserve the session integrity.
• To get more performant analytics.

Onboarding Token

The Onboarding Token or Session Token is a JSON Web Token returned by the [omni/startAPI](start interview) endpoint when a new session is created. This token is used to call the Omni APIs required as part of the onboarding process. Learn more about Session Tokens here ↗.