Integrating IDScan
Integrating the IDScan
1. Prerequisites
1.1 Obtain authentication keys
There are two keys you need for authentication: API key and a SDK key. Both will be shared separately.
APIkey is used to communicate with the API (e.g. to fetch images or application data) and SDKkey to generate a JWT that is needed to initiate the IDScan.
1.2. Create the container where you want to display the IDScan
Add the <div> where you want to display the IDScan modal.
<body>
<div id='checkin-component'></div> // name used for container in 2.3
</body>
</html>
2. Trigger the IDScan
For added security we recommend that you generate and include a short-lived JSON Web Token (JWT) every time you initialize the SDK.
It's possible to use your sdkKey as authentication, but this option should only be used during integration.
2.1. Generate JWT
curl -H "X-SDK-Key: [KEY]" -H "Content-Type: application/json" -X POST https://[PARTNER].getid.ee/sdk/v2/token\`
2.2. Setting up the basic SDK config object
const config = {
apiUrl: 'https://[PARTNER].getid.ee', // URL to your env
jwt: jwtToken, // jwt token from step 2.1. , it's also possible to use sdkKey instead of jwt
containerId: 'checkin-component', // name of the container created in 2.2
flowName: '[FLOW]', // flow name
locale: 'en', // pre-selected ui language
};
2.3. Initiate the IDScan
You render the modal by initiating the config object specified in 2.2.
Normally this is done on the click of a button or on page load.
window.getidWebSdk.init(config);
2.4. Handle the application
When the user has gone through all verification steps, an application is created in your Checkin.com back-office.
At this point a callback is triggered in the front-end. This callback can be captured via onComplete.
The data contained within this callback may not be final because the processing of the application may still be in progress, but by storing the applicationId you can then collect the final data via the API (see next section).
const config = {
apiUrl: 'https://[PARTNER].getid.ee',
jwt: jwtToken,
containerId: 'checkin-component',
flowName: '[FLOW]',
locale: 'en',
onComplete( data ) { // catch when an application has been successfully completed
console.log("All was good")
console.log( data.applicationId );
},
};
3. Fetch results from API
The API allows you to retrieve the full application data and the results from all performed checks.
Request and response format
You should use a Content-Type: application/json header with all requests. Responses return JSON with a consistent structure.
Authentication
The API uses token-based authentication. API tokens must be included in the header of all requests made to the API.
curl --location 'https://[PARTNER].getid.ee/api/v1/application/{ApplicationID} \
--header 'X-API-Key: {YourAPIKey}' \
--header 'Content-Type: application/json' \
--data ''
{
"id": "645cae276a9ba02a2daa09ff",
"application": {
"fields": [],
"documents": [
{
"issuingCountry": "unknown",
"documentType": "unknown",
"files": [
{
"id": "645cae2c6a9ba02a2daa1021",
"kind": "front",
"mediaType": "image/jpeg",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/17f70.....jpeg?t=168....442"
},
{
"id": "645cae2c6a9ba02a2daa1022",
"kind": "back",
"mediaType": "image/jpeg",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/fb133......jpeg?t=1683796112029&s=4fb...b247"
}
]
}
],
"selfie": {
"files": []
}
},
"processingState": "done",
"verificationTypes": [
"data-extraction"
],
"metadata": {
"platform": "web",
"sdkVersion": "v7.1.0",
"labels": {
"detectionModel": "https://cdn.getid.cloud/gecko/doc-detector/v15_4_10/uint8/model.json"
},
"ipAddress": "85.253.24.175",
"country": "SWE",
"city": "Stockholm",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
"savedRequestId": "0092b2d23215236b9e1c876efabadb8ab9b67eb8ebc29edf0ed27e1cadc2c3ed",
"createdAt": "2023-05-11T08:58:15.605Z",
"serverVersion": "v1.4.0",
"livenessSchemaVersion": "0.5",
"locale": "en",
"flowName": "[FLOW]"
},
"additionalFiles": [],
"overallResult": {
"status": "approved",
"comments": [
{
"service": "doc-check",
"status": "approved",
"comment": "No issues found."
}
],
"concerns": [],
"validationDate": "2023-05-11T08:58:19.562Z"
},
"servicesResults": {
"docCheck": {
"serviceType": "doc-check",
"verifier": "Doc-checker",
"comment": "No issues found.",
"processingState": "done",
"status": "approved",
"extracted": {
"ocr": [
{
"category": "Document number",
"content": "SPECI2021",
"contentType": "string"
},
{
"category": "Date of expiry",
"content": "2031-08-02",
"contentType": "date"
}
],
"mrz": [
{
"category": "Issue country",
"content": "NLD",
"contentType": "country",
"valid": true
},
{
"category": "Document number",
"content": "SPECI2021",
"contentType": "string",
"valid": true
}
],
"nfc": [],
"images": [
{
"kind": "front",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/d73c......jpeg?t=1683796112030&s=659....b53"
},
{
"kind": "back",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/d2132.....jpeg?t=1683796112030&s=3d33...4ed"
},
{
"kind": "barcode",
"uri": "https:/[PARTNER].getid.ee/files/proxy/images/3dcb.....jpeg?t=1683796112030&s=a6a02...2c4"
},
{
"kind": "portrait",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/c9d2....jpeg?t=1683796112031&s=70da61...1a8"
},
{
"kind": "signature",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/e000....jpeg?t=1683796112031&s=e2359d...627"
},
{
"kind": "ghost-portrait",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/84ae....jpeg?t=1683796112031&s=25f472...f55"
},
{
"kind": "mrz",
"uri": "https://[PARTNER].getid.ee/files/proxy/images/13f4....jpeg?t=1683796112031&s=1708b1...9f7"
}
]
},
"documentDataChecking": [
{
"equal": true,
"valid": true,
"category": "Document number",
"conflicts": [],
"message": "Value is ok",
"status": "approved",
"ocr": "SPECI2021",
"mrz": "SPECI2021",
"nfc": "",
"barcode": ""
},
{
"equal": true,
"valid": true,
"category": "Date of expiry",
"conflicts": [],
"message": "Value is ok",
"status": "approved",
"ocr": "2031-08-02",
"mrz": "2031-08-02",
"nfc": "",
"barcode": ""
}
],
"dataExtractionConsistency": {
"group": "dataExtractionConsistency",
"description": "Consistency and validity of extracted data",
"considers": [
{
"name": "documentValidation",
"type": "clear",
"status": "approved",
"description": "Data extracted from the document is consistent and valid."
}
]
},
"documentPhotoQuality": {
"group": "documentPhotoQuality",
"description": "Document photo quality",
"considers": [
{
"name": "supportedDocument",
"type": "clear",
"status": "approved",
"description": "Document is supported for check."
}
]
}
}
},
"archivePolicy": {},
"logs": [
{
"action": "application_created",
"time": "2023-05-11T08:58:15.982Z",
"user": "System",
"comment": "The application is created"
},
{
"action": "verifications_completed",
"time": "2023-05-11T08:58:19.767Z",
"user": "System",
"comment": "Verification(s) are completed"
},
{
"action": "application_processed",
"time": "2023-05-11T08:58:20.406Z",
"user": "System",
"comment": "The application is processed"
}
],
"responseCode": 200
}
Download collected documents via the API
The URL for downloading can be taken from different places in a response:
- Application->documents->files - Document pictures
- servicesResults->docCheck->extracted->images - Document pictures and Security elements
curl --location 'https://[PARTNER].getid.ee/files/proxy/images/13f4eeb0a573bf6c15cf2954c87a7f6fb7a872d279dbe249f2e1f009c712f8b0.jpeg?t=1683797273107&s=f2988897cb74c858f76c89d81cdb95268adcbdb0de935b3bb145249c1a24c878' \
--header 'x-sdk-key: {SDKKey}' \
--header 'Content-Type: application/json'
Updated 6 months ago