Integration and Code Examples#
API retrieval of Personal Verification Link#
Te easiest way to get started it so generate a personal verification link via the API. This can be done by sending a POST request to the API endpoint. The response will contain a URL that can be used to start the verification process as a standalone action.
A personal Verification Link is a temporary, single-use tokenized link generated separately for each end-user. By default, it expires in 12 hours, but this duration can be customized in the Partner Portal → Settings → SDK Configuration.
cURL Example - Requesting a Generic Link:
The name parameter is the name of the flow you want to use. The X-API-Key is your API key. The response will contain a URL that can be used to start the verification process.
curl -H "X-API-Key: {YourAPIKey}" \
-H "Content-Type: application/json" \
-X POST "https://[yourEnvironment].dev.getid.dev/api/v1/tokenized-url?name=IDScan-doc-selfie-liveness"
It is also possible to add pre-filled personalized information to this creation, such as name and date of birth. This is called an Enriched Link and described later.
Integration of the WebSDK into your application#
This describes the integration of the WebSDK into your application. The native SDKs are integrated in a similar way and described later in this document.
1. Load the SDK#
Load the launcher by adding a script tag to your HTML page. The SDK is loaded asynchronously and will not block the page from loading. The current WebSDK version is v7 and will be added to window.getidWebSdk. You also need to add a container to your HTML where the SDK will be rendered once triggered.
<script src="https://cdn.getid.cloud/sdk/getid-web-sdk-launcher-v7.min.js"></script>
... ...
<body>
<div id="checkin-component"></div>
</body>
2. Authentication and creating a verification session#
Generate an IDScan authentication session token (jwt) by calling the API endpoint from your backend system. This needs to be done once for each unique verification session. For security the SDK-Key used must not be exposed to the client-side.
The API request needs to be a POST with the X-SDK-Key in the header of the call. Examples to generate a Session JWT token:
# Example curl
curl -H "X-SDK-Key: [APIKEY]" -H "Content-Type: application/json" -X POST https://[yourEnvironment].sb.getid.dev/sdk/v2/token
// Example fetch
const result = await fetch('https://[yourEnvironment].sb.getid.dev/sdk/v2/token', {
method: 'POST',
headers: {
'X-SDK-Key': 'APIKEY',
'Content-Type': 'application/json',
},
})
const sessionToken = (await result1.json()).token
3. Trigger and Start the verification#
The SDK is started by calling window.getidWebSdk.init with the configuration object. Do this as an action when you want to start the verification process and show the UI. The three callbacks are onComplete, onFail, and onTrackEvent.
const config = {
apiUrl: 'https://[yourEnvironment].sb.getid.dev', // url to your env
jwt: sessionToken, // the generated session jwtToken (from step 1 above)
containerId: 'checkin-component', // Html container to render in
flowName: 'ID-Selfie-Liveness', // Selected flow name (from the Dashboard)
locale: 'en', // set language
profile: [
// (optional) If you have pre-collected data you want to cross-reference with the collected documents
{ value: 'Joe', category: 'First name' },
{ value: 'Doe', category: 'Last name' },
{ value: '1990-01-20', category: 'Date of birth' },
],
metadata: { externalId: '123456' }, // (optional) if you have an internal identifier you can use externalId to easily link applications to your internal systems
onComplete: (data) => console.log('Completed', data.applicationId), // actions to perform if application was successfully completed
onFail: (data) => console.log('Failed', data.code, data.message), // actions to perform if something failed
onTrackEvent: (data) => console.log('Event', data), // Event Tracking to see steps and error messages
}
window.getidWebSdk.init(config)
4. Handle the result on client side#
When the verification UI has collected all data, the onComplete callback is triggered. Please note that the onComplete is triggered when all data is collected from the user, and no further user input is needed. This means that the state of the verification will still be processing and the final result is not yet decided. To know the result of the verification, you need to listen to the webhook or query the API.
There are two common options for waiting for the final result:
- Contiune the user journey in your application - Forward the user to the next page in your application, and then show the result when it is available at a later stage.
- Wait for the result - Show a loading screen or other information, and wait for the result to be available. (normally available within seconds)
Send the data.applicationId to your backend to link the awaiting webhook results, or retrieve the personal details of the verification results using the API.
onComplete: (data) => {
const applicationId = data.applicationId
console.log('Verification completed, refference:', applicationId)
// - Send the applicationId to backend listen for webhook results
// - Await for backend webhook results on this applicationId
// - Redirect to the next step in your application
}
5. Handling the Result on Server Side#
Handling the result, including downloading data is described in Handling the Verification Result.