Create a Session
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.
/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:
/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 |
Handling the /omni/start
response
/omni/start
responseNow 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
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
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 the interviewId
to the frontendtoken
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.
Updated 4 months ago
Congrats! Now you know how to create and handle new onboarding sessions.