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:

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 full 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:

Header	Value
`api-version`	`"1.0"`
`x-api-key`	The API Key provided by Incode

JSON Request Body:

Key	Value
`configurationId`	The Incode Flow identifier for all your new sessions
`externalCustomerId`	Optional: Id that links the new onboarding session to this specific id, you will be able to query all the session related to this id on Incode Dashboard.
`redirectUrl`	Optional: when used in conjunction of `/omni/onboarding-url`, the webflow will redirect to this url at the end of the flow. You can also configure this on the dashboard

🦉

Start Onboarding Session

Open Recipe

Handling the `/omni/start` response

Now that you have created a new Incode Onboarding Session, you need to process the response in your application backend.

There are multiple values you will get from the /omni/start response. We will only focus on the values needed for for your web application for now.

The `interviewId`

A unique interviewId string (or session id) is assigned when a new session is created. Make sure you store each interviewId you create in your application backend.

The session `token`

To communicate with the Incode API the Web SDK needs a valid session token. 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 of the omni/start response 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 is used to link the new onboarding session to that specific flow, and all the configurations that are 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.