Journey Sessions (API v2)
The go-to solution for using journey sessions in your application
Verification of Identity documents is essential for on-boarding processes and KYC compliance. It allows you to confirm the identity of an individual, ensuring that they are who they claim to be. This is vital for preventing identity fraud and building trust with your customers.
As a developer looking to integrate Datakeen's journeys into your application you can generate unique session links that you can send to your end customers in order for them to capture their documents and carry out a biometric check. Results are then available by API.
Please note that contrary to Off the Shelf APIs the host URL for IDify sessions is https://app-v3.datakeen.co
I. Create sessions by API
1. Retrieve a new token (POST)
In order to retrieve a token you must make a POST call on the /auth endpoint. The token is valid 24h.
The username is your app-v3 e-mail address, and the password is your app-v3 password.
POST Request
curl --location 'https://app-v3.datakeen.co/backend/api/v1/auth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username={username or email}' \
--data-urlencode 'password={password}'const axios = require('axios');
const qs = require('qs');
let data = qs.stringify({
'username': 'username',
'password': 'password'
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://app-v3.datakeen.co/backend/api/v1/auth',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});
import requests
url = "https://app-v3.datakeen.co/backend/api/v1/auth"
payload = 'username=example%40example.com&password=password'
headers = {
'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)POST Answer
The POST answer is the following :
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2M2RhNzU4NGVmNWViYTAwMTIzNDRjOTciLCJmdWxsTmFtZSI6IkFkbWluIE9ueSIsImVtYWlsIjoiYWRtaW5AZGF0YWtlZW4uY29tIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzI2NzM1MzUzLCJleHAiOjE3MjY4MjE3NTN9.PcdqdPstUO9ByVhkTuYRidmB-m-44M25SKykKs-FmKQ",
"userId": "642bce5fd1faa5174a669cb8"
}2. Retrieve journeys (GET)
Journeys are the different steps your customer goes through.
If you have more than one journey (previously called "templates") for your customers. For example :
- Journey #1 : verify identity document and biometrics
- Journey #2 : verify rent documents
You can retrieve journey ids with the following call :
You must add a header with Authorization: Bearer {token} to be authorized
GET Request
curl --location 'https://app-v3.datakeen.co/backend/api/v1/journeys'
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {token}'const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://app-v3.datakeen.co/backend/api/v1/journeys',
headers: {
'Authorization': 'Bearer {{token}}'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});import requests
url = "https://app-v3.datakeen.co/backend/api/v1/journeys"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)GET Answer
{
"total": 2,
"journeys": [
{
"id": "69160da587107ed9783a4bc3",
"name": "Identity verification with face match",
"description": "Verify your customers identity",
"version": 2,
"languages": [
"en"
],
"groupId": "6628c9ff69b0540011c9e71c",
"platforms": {
"mobile": true,
"desktop": true,
"back_office": true
},
"showQRCode": false,
"created_at": "2025-11-13T16:56:05.328Z",
"updated_at": "2025-11-13T16:56:05.328Z"
},
{
"id": "6916030387107ed9783a4b94",
"name": "Rent document verificaiton",
"description": "Verfiy your customers rent documents",
"version": 2,
"languages": [
"en"
],
"groupId": "6628c9ff69b0540011c9e71c",
"platforms": {
"mobile": true,
"desktop": true,
"back_office": true
},
"showQRCode": false,
"created_at": "2025-11-13T16:10:43.184Z",
"updated_at": "2025-11-13T16:10:43.184Z"
},
]
}The following fields are returned:
- id : Unique identifier of the journey
- name: Name of the journey
- description : Detailed description of the journey purpose and steps
- version : Version number of the journey
- languages : Array of supported language codes (e.g., ["en"], ["fr", "en"])
- platforms : Platforms that are allowed to be used by the customer or by employees (for back_office)
- showQRCode: Are customers shown a QR code in order to switch to mobile from desktop (True/False)
- created_at: Date of creation timestamp
- updated_at: Date of modification timestamp
3. Create a new journey session (POST)
A session corresponds to the verification of one client. Each session is single-use and comes with an expiration time of 1 hour. Once the expiration time has passed, your end users cannot session, and a new session must be created.
In order to retrieve a new session link (unique URL) you must make a POST call on the /session endpoint.
In option you can provide the following information : "journeyId", "firstName", "lastName", "birthDate", "callbackURL", "webhookURL" and are detailed below :
POST Request
- journeyId [OPTIONAL] : STRING - the unique identifier of the template (see the get templates results)
- userInput : OBJECT - object with the following :
- firstName [OPTIONAL] : STRING - the first name of the person to verify
- lastName [OPTIONAL] : STRING - the last name of the person to verify
- birthDate [OPTIONAL] : STRING - the birth date of the person to verify ('MM/DD/YYYY' format)
- callbackURL [OPTIONAL] : STRING - a URL to redirect the user when the session is over
Authentication
You must add a header with Authorization: Bearer {token} to be authorized
curl --location 'https://app-v3.datakeen.co/backend/api/v1/session' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {token}' \
--data-urlencode 'journeyId=69122467f13e5b09e52b5241' \
--data-urlencode 'callbackURL=https://google.com' \
--data-urlencode 'userId=68eccc23f668aa4c492bf93a' \
--data-urlencode 'userInput%5BfirstName%5D=JEAN' \
--data-urlencode 'userInput%5BlastName%5D=DUPONT' \
--data-urlencode 'userInput%5BbirthDate%5D=01/31/1980'const axios = require('axios');
const qs = require('qs');
let data = qs.stringify({
'journeyId': '69122467f13e5b09e52b5241',
'callbackURL': 'https://google.com',
'userId': '68eccc23f668aa4c492bf93a',
'userInput[firstName]': 'JEAN',
'userInput[lastName]': 'DUPONT',
'userInput[birthDate]': '01/31/1980'
});
let config = {
method: 'post',
maxBodyLength: Infinity,
url: 'https://app-v3.datakeen.co/backend/api/v1/session',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Bearer {{token}}'
},
data : data
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});import requests
url = "https://app-v3.datakeen.co/backend/api/v1/session"
payload = 'journeyId=69122467f13e5b09e52b5241&callbackURL=https%3A%2F%2Fgoogle.com&userId=68eccc23f668aa4c492bf93a&userInput%5BfirstName%5D=JEAN&userInput%5BlastName%5D=DUPONT&userInput%5BbirthDate%5D=01%2F31%2F1980'
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Authorization': 'Bearer {{token}}'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)POST Answer
{
"id": "ff907a0bd4f023372fa143fe",
"userId": "68eccc23f668aa4c492bf93a",
"token": "31971500-dedd-4500-aba0-a166658a0e9c",
"expireTime": 1763116608083,
"status": "created",
"result": {},
"userInput": {
"firstName": "JEAN",
"lastName": "DUPONT",
"birthDate": "01/31/1990"
},
"callbackURL": "https://google.com",
"mobile": true,
"createdAt": "2025-11-14T09:36:48.084Z",
"updatedAt": "2025-11-14T09:36:48.084Z",
"journeyId": "69122467f13e5b09e52b5241",
"sessionURL": "https://app-v3.datakeen.co/session/ff907a0bd4f023372fa143fe"
}You will receive a link to access the session : sessionURL, along with an id.
4. Get the result of a session by sessionId (GET)
You can retrieved the result of a past session with it's id.
You must add a header with Authorization: Bearer {token} to be authorized
GET Request
curl --location 'https://app-v3.datakeen.co/backend/api/v1/session/{{sessionId}}' \
--header 'Authorization: Bearer {{token}}'const axios = require('axios');
let config = {
method: 'get',
maxBodyLength: Infinity,
url: 'https://app-v3.datakeen.co/backend/api/v1/session/{{sessionId}}',
headers: {
'Authorization': 'Bearer {{token}}'
}
};
axios.request(config)
.then((response) => {
console.log(JSON.stringify(response.data));
})
.catch((error) => {
console.log(error);
});import requests
url = "https://app-v3.datakeen.co/backend/api/v1/session/{{sessionId}}"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)GET Answer
The list of codes for the documents are the following :
| Code | Code Name | Description |
|---|---|---|
| 1.0 | ai_approved | The document has been fully verified by the AI, it is valid and conform |
| 2.2 | readability | The document could not be processed: Could not read textual information |
| 2.4 | missingMRZ | The document could not be processed: The MRZ could not be found |
| 2.5 | missingPart | The document could not be processed: One side of the document is missing |
| 2.6 | noIdFound | The document could not be processed: Could not find any ID |
| 3.0 | expired | The document has expired |
| 4.0 | toVerify | We could not process all the controls on the given document, please review its authenticity |
| 5.0 | suspicious | At least one element on the document is suspected to be fraudulent |
| 7.0 | owner | The owner of the document does not match the user input |
| 8.0 | specimen | The document has been found in our specimen database |
You will find below an example of an API answer :
{
"id": "4c3c90bcefb881d17e0ceb67",
"userId": "642bce5fd1faa5174a669cb8",
"token": "a4197791-2530-48d0-92a9-4b5465eee8b5",
"expireTime": 1763197530202,
"status": "ended",
"result": {
"status": "ai_approved",
"node": [
{
"id": "node-controle-jdi-1762185123875-198",
"status": "ai_approved"
},
{
"id": "node-controle-jdi-1762185543313-127",
"status": "ai_approved"
}
]
},
"landingPage": null,
"withSelfie": null,
"groupId": null,
"userInput": {
"firstName": "GAEL",
"lastName": "BONNARDOT",
"birthDate": "09/25/1990",
"countryCode": "FR"
},
"callbackURL": "https://google.com",
"webhookURL": "",
"contactInfo": {},
"userAgent": [],
"mobile": true,
"createdAt": "2025-11-14T09:05:30.203Z",
"updatedAt": "2025-11-14T09:09:11.601Z",
"group": null,
"documents": [
{
"userInput": null,
"id": "6916f15a471a1a526f4b87c6",
"analysisId": "6916f152471a1a526f4b87c3",
"entityId": "6916f15a471a1a526f4b87c5",
"sessionId": "4c3c90bcefb881d17e0ceb67",
"nodeId": null,
"origin": "",
"status": "ai_approved",
"statusComment": "",
"code": "1.0",
"codeName": "conform",
"codeDescription": "The document has been fully verified by the AI, it is valid and conform",
"type": "national_id_card_fr_2003",
"pages": [],
"extractedInformations": {
"address": {
"value": "1 BVD DES CAPUCINES"
},
"birthCountry": {
"value": "FR"
},
"birthDate": {
"value": "25.09.1990"
},
"birthDepartment": {
"value": "75"
},
"birthPlace": {
"value": "PARIS E ARRONDISSEMENT"
},
"countryCode": {
"value": "FR"
},
"deliveryDate": {
"value": "01.04.2021"
},
"deliveryDateMRZ": {
"value": "04.2021"
},
"deliveryDepartmentMRZ": {
"value": "94"
},
"expiryDate": {
"value": "31.03.2036"
},
"firstName": {
"value": "JEAN"
},
"firstName1": {
"value": "JEAN"
},
"firstName2": {
"value": ""
},
"firstName3": {
"value": ""
},
"firstNameMRZ": {
"value": "JEAN"
},
"fullName": {
"value": "JEAN DUPONT"
},
"gender": {
"value": "M"
},
"genderMRZ": {
"value": "M"
},
"idNumber": {
"value": "210494150108"
},
"idNumberMRZ": {
"value": "210494150108"
},
"lastName": {
"value": "DUPONT"
},
"lastNameMRZ": {
"value": "DUPONT"
},
"mrz": {
"value": "IDFRADUPONT<<<<<<<<<<<<<<<<094033\n2104941501083JEAN<<<<<<<<<<9009257M7"
},
"nationality": {
"value": "FR"
},
"nationalityMRZ": {
"value": "FRA"
},
"spouseName": {
"value": ""
}
},
"metadata": [
{
"author": null,
"created_date": null,
"creator": null,
"dpiX": 309,
"dpiY": 292,
"file": "id_card_back.jpg",
"keywords": null,
"modified_date": null,
"producer": null,
"subject": null,
"title": null
},
{
"author": null,
"created_date": null,
"creator": null,
"dpiX": 309,
"dpiY": 292,
"file": "id_card_front.jpg",
"keywords": null,
"modified_date": null,
"producer": null,
"subject": null,
"title": null
}
],
"controls": {},
"controlCategories": {
"dataCoherency": {
"controls": {
"countryCodeConformity": {
"value": true
},
"durationValidity": {
"value": true
},
"matchDeliveryDateMRZ": {
"value": true
},
"matchFirstNameMRZ": {
"value": true
},
"matchGenderMRZ": {
"value": true
},
"matchIdNumberMRZ": {
"value": true
},
"matchLastNameMRZ": {
"value": true
},
"matchNationalityMRZ": {
"value": true
},
"mrzConformity": {
"value": true
},
"notExpired": {
"value": true
},
"notSpecimen": {
"value": true
}
},
"status": true
},
"input": {
"controls": {
"matchBirthDate": {
"value": true
},
"matchFirstName": {
"value": true
},
"matchFullName": {
"value": true
},
"matchLastName": {
"value": true
}
},
"status": true
},
"metadata": {
"controls": {
"notMultipleVersions": {
"value": null
},
"notSuspectedSoftware": {
"value": null
}
},
"status": null
},
"visual": {
"controls": {
"initialsIsPresent": {
"value": true
},
"mrzVisualConformity": {
"value": true
},
"noBrightSpot": {
"value": true
},
"photoIsPresent": {
"value": true
},
"rfSymbolIsPresent": {
"value": true
},
"stampIsPresent": {
"value": true
},
"waveIsPresent": {
"value": true
}
},
"status": true
}
},
"name": "JEAN_DUPONT_d4614971.pdf",
"path": "JEAN_DUPONT_d4614971.pdf",
"creationOrigin": "api",
"createdAt": "2025-11-14T09:07:38.474Z",
"updatedAt": "2025-11-14T09:07:38.474Z"
},
{
"userInput": null,
"id": "6916f196471a1a526f4b87cc",
"analysisId": "6916f18b471a1a526f4b87ca",
"entityId": "6916f15a471a1a526f4b87c5",
"sessionId": "4c3c90bcefb881d17e0ceb67",
"nodeId": null,
"origin": "",
"status": "ai_approved",
"statusComment": "",
"code": "1.0",
"codeName": "conform",
"codeDescription": "The document has been fully verified by the AI, it is valid and conform",
"type": "driver-license",
"pages": [],
"extractedInformations": {
"birthDate": {
"confidence": 0.8,
"value": "25-09-1990"
},
"birthPlace": {
"confidence": 0.8,
"value": "paris 20"
},
"deliveryDate": {
"confidence": 0.8,
"value": "15-06-2023"
},
"expiryDate": {
"confidence": 0.8,
"value": "15-06-2038"
},
"firstName": {
"confidence": 1,
"value": "JEAN"
},
"fullName": {
"confidence": 1,
"value": "JEAN DUPONT"
},
"issuingAuthority": {
"confidence": 0.8,
"value": "prefet 94"
},
"lastName": {
"confidence": 1,
"value": "DUPONT"
},
"licenseNumber": {
"confidence": 0.8,
"value": "23am35374"
},
"licenses": {
"confidence": 0.8,
"value": [
{
"additionalMentions": "",
"category": "am",
"dateOfExpiry": "",
"dateOfFirstIssue": "25-05-2023"
},
{
"additionalMentions": "",
"category": "a1",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "a2",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "a",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "78",
"category": "b1",
"dateOfExpiry": "",
"dateOfFirstIssue": "25-05-2023"
},
{
"additionalMentions": "78",
"category": "b",
"dateOfExpiry": "",
"dateOfFirstIssue": "25-05-2023"
},
{
"additionalMentions": "",
"category": "c1",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "c",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "d1",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "d",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "be",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "c1e",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "ce",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "d1e",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
},
{
"additionalMentions": "",
"category": "de",
"dateOfExpiry": "",
"dateOfFirstIssue": ""
}
]
},
"mrzData": {
"confidence": null,
"value": ""
},
"type": {
"confidence": 1,
"value": "driver_license_eu"
}
},
"metadata": [
{
"author": null,
"created_date": null,
"creator": null,
"file": "driver_license_back.jpg",
"keywords": null,
"modified_date": null,
"producer": null,
"subject": null,
"title": null
},
{
"author": null,
"created_date": null,
"creator": null,
"file": "driver_license_front.jpg",
"keywords": null,
"modified_date": null,
"producer": null,
"subject": null,
"title": null
}
],
"controls": {},
"controlCategories": {
"dataCoherency": {
"controls": {
"notExpired": {
"confidence": 0.8,
"value": true
}
},
"status": true
},
"input": {
"controls": {
"matchBirthDate": {
"confidence": 0.9,
"value": true
},
"matchFirstName": {
"confidence": 0.99,
"value": true
},
"matchFullName": {
"confidence": 0.99,
"value": true
},
"matchLastName": {
"confidence": 0.99,
"value": true
}
},
"status": true
},
"metadata": {
"controls": {
"notMultipleVersions": {
"confidence": null,
"value": null
},
"notSuspectedSoftware": {
"confidence": null,
"value": null
}
},
"status": null
},
"visual": {
"controls": {},
"status": true
}
},
"name": "JEAN_DUPONT_30005989.pdf",
"path": "JEAN_DUPONT_30005989.pdf",
"creationOrigin": "api",
"createdAt": "2025-11-14T09:08:38.390Z",
"updatedAt": "2025-11-14T09:08:38.390Z"
},
{
"status": "ai_approved",
"code": "1.0",
"type": "biometric analysis",
"createdAt": "2025-11-14T09:08:57.482Z",
"updatedAt": "2025-11-14T09:08:57.482Z"
}
],
"entities": [
{
"id": "6916f15a471a1a526f4b87c5",
"uuid": "8b75a14e-1d57-466c-8af6-ef4d4b03fef9",
"analysisId": "6916f152471a1a526f4b87c3",
"sessionId": "4c3c90bcefb881d17e0ceb67",
"status": "ai_approved",
"firstName": "JEAN",
"lastName": "DUPONT",
"documentTypes": [
"national_id_card_fr_2003",
"driver-license"
],
"numberOfDocuments": 2,
"massAnalysis": false,
"createdAt": "2025-11-14T09:07:38.464Z",
"updatedAt": "2025-11-14T09:08:38.404Z"
}
],
"journeyId": "69122467f13e5b09e52b5241"
}5. Get a document from a session (GET)
You can retrieve a document associated with a session by using the document ID and session ID.
You must add a header with Authorization: Bearer {token} to be authorized
GET Request
curl --location 'https://app-v3.datakeen.co/backend/api/v1/session/{sessionId}/document/{documentId}' \
--header 'Authorization: Bearer {token}'const axios = require("axios");
const getDocument = async (sessionId, documentId, token) => {
try {
const response = await axios.get(
`https://app-v3.datakeen.co/backend/api/v1/session/${sessionId}/document/${documentId}`,
{
headers: {
"Content-Type": "application/json",
Authorization: `Basic ${token}`,
},
}
);
return response.data;
} catch (error) {
console.error("Error fetching document:", error);
throw error;
}
};import requests
def get_document(session_id, document_id, token):
url = f"https://app-v3.datakeen.co/backend/api/v1/session/{session_id}/document/{document_id}"
headers = {
"Content-Type": "application/json",
"Authorization": f"Basic {token}"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
return response.json()GET Answer
You will receive a JSON response containing the document data in base64 format:
{
"status": 1,
"message": "Document found",
"data": {
"documentBase64": "base64EncodedString...",
"fileName": "document_filename.jpg",
"allFilesData": [
{
"base64": "base64EncodedString...",
"name": "document_filename.jpg"
}
]
}
}Response Fields
| Field | Description |
|---|---|
| documentBase64 | The base64-encoded content of the document, which you can decode to view or save the original document |
| fileName | The original filename of the document |
| allFilesData | An array containing all file data related to this document |
Possible Error Responses
| Status Code | Description |
|---|---|
| 401 | Unauthorized - Invalid or missing authentication token |
| 404 | Not Found - Session or document not found |
| 500 | Server Error - Error retrieving document from storage |
Updated 15 days ago