Developer guide
The Developer Guide provides comprehensive instructions and best practices for integrating with our platform.
Identomat is a service designed for verifying human identity and liveness over the Internet. This manual assumes that the integrating company (hereafter referred to as "the company") operates a web server (hereafter referred to as "the company server") at example.com and has a company_key
. The company_key
is a credential used for secure communication between the company server and the Identomat server (widget.identomat.com).
For enhanced security, companies have the option to implement HMAC authorization. The secret_key
serves as the encryption key used with HMAC.
Procedure
The procedure is straightforward and consists of the following steps:
Acquiring a session token
To acquire a session_token
, your backend must send a request to the begin/
endpoint with the following required parameters:
company_key
– Your unique company identifier.flags
– A JSON object specifying global settings for the identification process.steps
– An array defining the specific steps in the verification flow. Each step can include its own step-specific flags.
⚠️ The
session_token
has a default validity period of 15 minutes.
Endpoint:
https://widget.identomat.com/begin/
Method: POST
This endpoint, like others in our API, can be accessed using the HTTP POST method. Parameters may be provided in any of the following formats:
As URL query parameters
As URL-encoded form data
As a JSON object in the request body
Steps and Flags Structure
The flags
parameter defines global behavior for the entire identification session.
The steps
array allows full control of the verification process, enabling you to specify which steps to include (e.g., liveness
, identity-document
) and configure step-specific flags, such as "allow_face_upload": true
for the liveness
step.
To ensure compatibility between the old and new methods, both of which need to work together, you should use the 'skip_face'
and 'skip_document'
flags when using steps.
These flags prevent the 'identity-document' and 'liveness' steps from being duplicated if they already exist in the flow.
Using Configuration or Custom Steps
Sessions can be initiated in two ways:
By referencing a predefined configuration ID via the
config_id
parameter.By explicitly providing a custom combination of steps and flags in the request payload.
Redirecting to the Identomat Widget
To start a verification session, the company server must redirect the user’s browser to:
https://widget.identomat.com/?session_token={session_token_here}
Embedding in an Iframe
Alternatively, the widget can be embedded within an iframe:
<iframe
src="https://widget.identomat.com/?session_token={session_token_here}"
allow="camera">
</iframe>
Checking for a result
Once the identification process is completed:
If redirected, the user’s browser is sent back to the return URL specified in the configuration. A
session_token
parameter is appended to this URL.If embedded in an iframe, the process completion can be detected using JavaScript:
addEventListener('message', function (e) {
if (e.origin !== 'https://widget.identomat.com') return;
if (e.data !== 'DONE') return;
// Process completed, handle results here
});
Flags
Below is a list of all the general flags currently used by the system.
"skip_face"
Prevents the 'liveness'
from being duplicated if it already exists in the flow as a step.
false
<boolean>
'skip_document'
Prevents the 'identity-document'
from being duplicated if it already exists in the flow as a step.
false
<boolean>
"return_url"
The URL to redirect the user to after the identification process is complete.
If omitted, it indicates that the process is embedded in an iframe.
<string>
"language"
The language for the user interface.
Possible values:
"es", "ka", "uk", "ru", "uz", "it", "gr", "tr", "ro", "ar", "de", "pl", "hi", "bn", "az", "ja", "pt", "fr", "kk", "sv"
"en"
<string>
"skip_desktop"
Limits sessions to mobile devices. If the session is initiated on a desktop, a QR code will be displayed to transfer the session to a mobile device.
Possible values:
true
, false
false
<boolean>
"switch_device_url"
Specifies a custom URL to display in the QR code when the camera is not available or access is restricted.
If omitted or set to an empty string, no URL is applied.
<string>
"restrict_url_sharing"
Restrict sharing of the session URL to continue from another browser.
Note: If this flag is set to true, the QR code will not appear when camera access is denied or unavailable, unless the switch_device_url
flag is also present.
Possible values:
true
, false
false
<boolean>
"optional_continue_on_another_device"
Enables the option to switch to another device for continuation.
Possible values:
true
, false
false
<boolean>
"requireHdMedia"
When enabled, the Liveness and ID verification steps require an full HD camera (1080p or higher). If the user’s device does not meet this requirement, a QR code will be displayed, allowing them to continue the process on another device.
false
<boolean>
Steps
The steps
array defines the flow of the identification process. The steps
array is passed along with the company_key
and flags
.
Each step in the steps
array may include the following properties.
Type
: A type of the specific step.Key
: A unique identifier for the step. Keys are editable and can be configured as desired, provided they remain unique.Flags
: Specific flags that define the step's configuration.Title
: The title for the step is provided by client, displayed in the user interface.
Below is a list of all the types of steps available in our system.
KYB
Language
The Language step allows the user to choose the interface language.
Language step configurations:
Title:
Language
Type:
language
Key:
language
Array of
languages
"languages"
Possible values:
"en", "ka", "es", "uk", "gr", "it", "de", "ru", "uz", "ro", "tr", "ar", "pl", "bn", "hi", "hy", "az", "ja", "pt", "fr", "kk", "sv"
If the array is empty, all available languages will be shown.
<array>
Identity document verification
The Identity Document step involves users scanning or uploading photos of their ID documents.
Identity document step configurations:
Title:
ID verification
Type:
identity-document
Key:
identity-document
Flags:
disable_document_capture
allow_document_upload
document_types
document_countries
"disable_document_capture"
If true, users are unable to scan documents and must upload them instead.
Possible values:
true
, false
false
<boolean>
"allow_document_upload"
If true, users can choose between scanning or uploading their documents.
Possible values:
true
, false
false
<boolean>
"document_types"
A list of allowed document types.
Possible values:
"id", "passport", "driver_license", "residence_license"
If omitted or set to an empty array, all document types are allowed.
<array>
"document_countries"
Limits document scanning to specific issuer countries by codes. Possible values:
"USA", "DEU", "ITA"
, etc.
If omitted or set to an empty array, no restrictions are applied.
<array>
cURL example:
Example using cURL with return_url
& language
flags and an identity-document
verification step:
Liveness check
In the liveness check step, the user positions their face within the frame and follows the instructions.
Identomat offers two types of liveness check:
Passive liveness: A basic check where the user holds their head within an oval frame while the system captures a two-second video.
Active liveness: An advanced biometric check where the user performs specific actions to confirm their presence as a live person.
Liveness check step configurations:
Title:
Liveness
Type:
liveness
Key:
liveness
Flags:
liveness
allow_face_upload
"liveness"
If true, users will be required to perform active liveness checks. If false, users will undergo passive liveness checks.
Possible values:
true
, false
false
<boolean>
"allow_face_upload"
If true, users are allowed to upload a selfie. Note: If the "liveness" flag is set to true, the "allow_face_upload" flag will not be effective, as active liveness requires users to follow specific instructions.
false
<boolean>
cURL example:
Example using cURL with document_countries
& language
flags and identity-document
verification & active liveness
steps:
Proof of address
The proof of address step includes verification of proof of address and analysis of other type of documents.
Proof of address step configurations:
Title:
Proof of address
Type:
general-document
Key:
select_general_document
Flags:
general_document_types
"general_document_types"
A list of allowed document types.
Possible values:
"bank_statement", "utility_bill", "yellow_slip", "drivers_license", "vehicle_registration_certificate"
If omitted or set to an empty array, all general document types are allowed.
<array>
cURL example:
Example using cURL with optional_continue_on_another_device
& language
flags and liveness
& general-document
steps:
Selfie with ID
In the Selfie with ID step, users are required to hold their document in their hands so that both their face and the document are visible.
Selfie with ID step configurations:
Title:
Selfie with ID
Type:
face-document
Key:
capture_face_document
Flags:
allow_face_doc_upload
require_face_document
"allow_face_doc_upload"
If true, users are allowed to upload an image of themselves holding a document in their hand.
Possible values:
true
, false
false
<boolean>
"require_face_document"
If true, users are allowed to capture themselves holding a document in their hand.
Possible values:
true
, false
false
<boolean>
cURL example:
Example using cURL with restrict_url_sharing
& language
flags and face-document
step:
Video call
In the Video Call step, the user is connected with an operator to perform a manual verification process. The video call may include all other Identomat verification steps.
Identomat offers two types of video call:
One-on-one: Involves a secure video call between a customer and a verification operator
Multi-user call: Enables the verification of multiple customers within a single session. Each user can follow their own customized workflow tailored to the specific business process.
Video call step configurations:
Title:
Video call
Type:
video-call
Key:
video-call
Array of
steps
resetSteps:
true/false
(optional)hideCameraOption:
true/false
(optional)nameRequired:
true/false
(optional)multiple_participans:
true/false
(optional)
"steps"
The steps
array includes all identification steps listed here, except for the language
step and the operator_questionnaire
, which must be listed outside the video call steps array.
empty array [ ]
<array>
"resetSteps"
If a user disconnects and rejoins the call, all previous verification data is cleared for security reasons. The operator must restart the verification process to ensure the user's identity.
Possible values:
true
, false
false
<boolean>
"hideCameraOption"
Enabling this will hide the camera icon, preventing users from turning off the camera. Possible values:
true
, false
false
<boolean>
"nameRequired"
If enabled, participants are required to provide their names to join the call. Possible values:
true
, false
false
<boolean>
"multiple_participants"
true, allows video call sessions to include multiple participants instead of just one.
Possible values:
true
, false
false
<boolean>
cURL example:
Example using cURL with return_url
& language
flags and video-call
with identity-document
step:
Phone number
Phone number verification allows users to verify their phone number using an OTP code.
Phone number step may include:
Verification of the user's phone number using an OTP code.
Collection of the user's phone number.
Phone number step configurations:
Type:
phone-number
Key:
phone_number
Flags:
require_phone_number_check
require_phone_number
"require_phone_number_check"
If true, users are required to verify their phone number using an OTP code sent to them.
Possible values:
true
, false
false
<boolean>
"require_phone_number"
If true, users are required to submit their phone number without verification.
Possible values:
true
, false
false
<boolean>
cURL example:
Example using cURL with return_url
& language
flags and phone-number
step:
Email
Email step allows users to verify their email using an OTP code.
Email step may include:
Verification of the user's email using an OTP code.
Collection of the user's email.
Email step configurations:
Type:
email
Key:
require_email
Flags:
require_email_check
require_email
"require_email_check"
If true, users are required to verify their email using an OTP code sent to them.
Possible values:
true
, false
false
<boolean>
"require_email"
If true, users are required to submit their email address without verification.
Possible values:
true
, false
false
<boolean>
cURL example:
Example using cURL with return_url
& language
flags and phone-number
step:
Geolocation
The Geolocation step allows the user to grant permission for location access. This enables the system to retrieve the user's geolocation data, including coordinates and address.
Geolocation step configurations:
Type:
geolocation
Key:
require_geolocation
Flags:
require_geolocation
"require_geolocation"
If true, users must grant permission for location access to proceed.
Possible values:
true
, false
true
<boolean>
cURL example:
Example using cURL with return_url
& language
flags and geolocation
step:
User questionnaire
The user questionnaire step allows you to collect custom user input as part of the verification flow. It supports various question types and provides multilingual support for titles and descriptions. All responses are saved to the verification session. This step has a slightly different structure compared to other steps.
User questionnaire step configurations:
type
Must be set to "user-questionnaire"
to define this step as a user questionnaire block.
key
A client-defined unique key for this questionnaire step. It must remain unique within a single session to avoid conflicts.
title
The main title of the questionnaire displayed on the user interface.
Must always be provided as an <object>
with language codes as keys (e.g., "en"
), even if only one language is used. This ensures consistency and supports future localization.
description
Text displayed beneath the title in the user interface, providing context or instructions.
Must always be an <object>
of language codes. Same format and rules as title
.
questions
An <array>
of question objects to be presented to the user.
Supported question types include:
string
: Text Input – The user enters a short text answer.multiple-choice
: : Checkboxes – Allows the user to select one or more options.options
: Radio – The user selects a single option from a list.dropdown
: Dropdown List – The user selects one or more options from a dropdown menu.file
: File Upload – Allows the user to upload a file as a response.
successButtonTitle
Defines the label of the confirmation button displayed at the end of the questionnaire.
Must also be an <object>
of language codes, even if only one language is used.
If any question is marked as "mandatory": true
, the button will remain disabled until all required questions are answered.
Questions
Each question in the questions
array supports a set of parameters that define how it behaves and appears to the user. Here's a breakdown of all supported properties:
type
Defines the question type.
Supported values:
string
– Short text inputmultiple-choice
– Checkbox (multiple selection)options
– Radio buttons (single selection)dropdown
– Dropdown menu (single or multi-select)file
– File upload
title
A multilingual <object>
representing the question label.
Example:
"title": {
"en": "What is your occupation?",
"fr": "Quelle est votre profession ?"
}
key
A unique identifier for the question within the same questionnaire. This is client-defined and used for referencing and data mapping.
mandatory
Indicates whether the question must be answered before the user can proceed.
Value:
true
orfalse
answer
Allows you to preset an answer for the user.
string
: A plain text string (e.g.,"John Doe"
).options
: A single option key (e.g.,"opt_a"
).multiple-choice
: An array of option keys (e.g.,["opt_a", "opt_c"]
).dropdown
: Not applicable.file
: Not applicable.
Note: End-users can modify pre-filled answers unless readOnly
is enabled.
readOnly
Displays the question in a non-editable state. Users can view the question and answer but cannot change it.
Value:
true
orfalse
showConditions
Defines a conditional display rule for the question, based on the answer to a previous question.
"showConditions": {
"questionKey": "employment-status",
"answer": "self-employed"
}
questionKey
Key of the controlling question.answer
Key of the answer (for radio/checkbox) or specific text (for string)
multiple
Specific to dropdown
type.
If true
, the user can select multiple values from the dropdown.
Value:
true
orfalse
Options
Options are used exclusively in multiple-choice
, options
and dropdown
type questions. They define the selectable choices that the user can pick from.
Each question that supports options must include the following parameter:
options
An <array>
of option objects for the question. Each object must include the following:
title
The text label for the option, shown to the user during the verification flow.
Must always be provided as an <object>
with language codes as keys, even if only one language is used.
This ensures consistency across multilingual flows.
Example:
{
"en": "Self-employed"
}
key
A unique identifier for the option within the questionnaire. This value is used for referencing in preset answers, conditions, and session data. It must be unique within the same questionnaire to avoid conflicts.
List of parameters with examples:
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the questionnaire shortly.
-
<string>
"key": "terms-and-conditions"
"title"
The title of the user questionnaire, displayed as the block title on the user's side. The title can be an <object>
containing different languages, allowing the title to be displayed in the selected language during the verification flow.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"description"
A description that appears below the title on the user's side. Similar to the title, the description can be an <object>
containing different languages, so that it can be displayed in the selected language during the verification flow.
-
<object>
"description": {
"es": "Tu descripción",
"en": "Your description"
}
"questions"
An <array>
of questions with the following types: string
, multiple-choice
, options
, dropdown
.
-
<array>
"questions": [
{
"type": "string",
"title": {
"es": "Tu título",
"en": "Your title"
}
"key": "question1",
"mandatory": true
},
{
"type": "multiple-choice",
"title": {
"es": "Tu título",
"en": "Your title"
},
"key": "question2",
"mandatory": false,
"options": [
{
"title": {
"es": "Tu título",
"en": "Your title"
},
"key": "option1"
},
{
"title": {
"es": "Tu título",
"en": "Your title"
},
"key": "option2"
}
]
}
]
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": false
"answer"
Allows to preset an answer for a question.
-
<string> or <array>
"answer": "option2"
"readOnly"
Displays the question but restricts interaction.
false
<boolean>
"readOnly": false
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
"successButtonTitle"
The title of the action button in the questionnaire. If the questions are mandatory, the button is deactivated until the user completes the questionnaire.
Confirm
<object>
"successButtonTitle": {
"es": "Tu título",
"en": "Your title"
}
cURL example:
Question type: Text input
Available parameters:
"type"
"string"
-
<string>
"type": "string"
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the question shortly.
-
<string>
"key": "your-address"
"title"
The title is an <object>
of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": true
"answer"
Allows to preset an answer for a question.
The answer is an <object>
of languages so that if the user changes the language during the verification flow, the prefilled answer can be displayed in different languages.
-
<object>
"answer": {
"en": "This is a prefilled answer",
"es":"Esta es una respuesta prellenada."
}
"readOnly"
Displays the question but restricts interaction.
false
<boolean>
"readOnly": true
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
Question type: Checkbox
Available parameters:
"type"
"multiple-choice"
-
<string>
"type": "multiple-choice"
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the question shortly.
-
<string>
"key": "check-two-answers"
"title"
The title is an <object>
of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"options"
An <array> of options for the question. Each option may have:
"title" : The title of an option. The title is an
<object>
containing different languages, allowing the option to be displayed in the selected language during the verification flow."key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.
-
<array>
"options": [
{
"title": {
"en": "Identity Document",
"es": "Documento de identidad"
},
"key": "identity-document"
},
{
"title": {
"en": "Proof of Address",
"es": "Comprobante de domicilio"
},
"key": "proof-of-address"
]
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": true
"answer"
Allows to preset an answer for a question.
The answer is an <array>
of option keys assigned to this question.
-
<array>
"answer": [
"option-1",
"option-2"
]
"readOnly"
Displays the question but restricts interaction.
false
<boolean>
"readOnly": true
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
Question type: Radio
Available parameters:
"type"
"options"
-
<string>
"type": "options"
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the question shortly.
-
<string>
"key": "choose-one-answer"
"title"
The title is an <object>
of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"options"
An <array> of options for the question. Each option may have:
"title" : The title of an option. The title is an
<object>
containing different languages, allowing the option to be displayed in the selected language during the verification flow."key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.
-
<array>
"options": [
{
"title": {
"en": "Identity Document",
"es": "Documento de identidad"
},
"key": "identity-document"
},
{
"title": {
"en": "Proof of Address",
"es": "Comprobante de domicilio"
},
"key": "proof-of-address"
]
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": true
"answer"
Allows to preset an answer for a question.
The answer is an <string>
of an option key assigned to this question.
-
<string>
"answer": "option-1"
"readOnly"
Displays the question but restricts interaction.
false
<boolean>
"readOnly": true
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
Question type: Dropdown
Available parameters:
"type"
"dropdown"
-
<string>
"type": "dropdown"
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the question shortly.
-
<string>
"key": "choose-from-list"
"title"
The title is an <object>
of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"options"
An <array> of options for the question. Each option may have:
"title" : The title of an option. The title is an
<object>
containing different languages, allowing the option to be displayed in the selected language during the verification flow."key": The key for the option, chosen by the client. It must remain unique within a single questionnaire.
-
<array>
"options": [
{
"title": {
"en": "Identity Document",
"es": "Documento de identidad"
},
"key": "identity-document"
},
{
"title": {
"en": "Proof of Address",
"es": "Comprobante de domicilio"
},
"key": "proof-of-address"
]
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": true
"multiple"
Specifies whether the question is single or multiple choice.
Possible values:
true
, false
false
<boolean>
"multiple": true
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
Question type: File upload
Available parameters:
"type"
"file"
-
<string>
"type": "file"
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the question shortly.
-
<string>
"key": "choose-from-list"
"title"
The title is an <object>
of languages so that if the user changes the language during the verification flow, the question can be displayed in different languages. There are no length or symbol restrictions.
-
<object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"description"
A description that appears below the title. Similar to the title, the description can be an <object>
containing different languages, so that it can be displayed in the selected language during the verification flow.
-
<object>
"description": {
"es": "Tu descripción",
"en": "Your description"
}
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": true
"fileTypes"
Specifies the types of files the user is allowed to upload.
Possible values:
pdf
, image
.
[ "pdf"
, "image"
]
<array>
"fileTypes": [
"pdf",
"image"
]
"filesMaxCount"
Specifies the maximum number of files the user is allowed to upload. Possible values: A number from 1 to 10.
10
<number>
"filesMaxCount": 5
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
Operator questionnaire
is part of the session and is designed to be filled out by the operator, either during or after the verification call. It allows operators to collect specific information or provide manual input. Its structure closely mirrors the user questionnaire, with the main difference being who completes the form.
Operator questionnaire step configurations:
type
Must be set to "operator-questionnaire"
to define this step as an operator-facing form.
key
A unique identifier for the operator questionnaire step. This key is defined by the client and must remain unique within a single session.
title
The name of the section as shown in the operator interface.
Must always be an <object>
with language codes as keys, even if only one language is used.
Example:
"title": {
"en": "Operator notes"
}
description
Text displayed under the title, used to give context or instructions to the operator.
Also must be provided as an <object>
of language codes.
questions
An <array>
of question objects that define the fields the operator will fill out.
Supported question types include:
string
: Text Input – Operator types a short answer as plain text.multiple-choice
: Checkboxes – Operator selects one or more values from a list.options.options
: Radio – Operator selects one option from a predefined set.dropdown
: Dropdown Menu – The operator selects one or more options from a dropdown list, depending on configuration.file
: File Upload – The operator uploads one or more files (e.g., documents or images) as part of the questionnaire.
Questions
Each question in the Operator Questionnaire must be defined as an object within the questions
array. The following parameters are supported for each question:
type
The type of question. Supported values are:
string
– Text Inputmultiple-choice
– Checkboxesoptions
– Radio Buttonsdropdown
– Dropdown Listfile
– File Upload
title
The question title as a string. There are no length or symbol restrictions. The title can also be an The label shown above the question.
Must always be provided as an <object>
of language codes (e.g., "en"
, "de"
), even if only one language is used.
Example:
"title": {
"en": "Reason for rejection"
}
key
A unique identifier for the question, defined by the client. It must be unique within the same questionnaire.
mandatory
Boolean. Indicates whether the question must be answered before submitting the questionnaire.
Default is false
.
answer
Allows you to preset an answer for the operator.
For
string
: A plain text string (e.g.,"Invalid ID"
).For
options
: A single option key (e.g.,"opt_a"
).For
multiple-choice
: An array of option keys (e.g.,["opt_a", "opt_c"]
).For
dropdown
: Not applicable.For
file
: Not applicable.
Note: Operators can modify pre-filled answers unless readOnly
is enabled.
readOnly
Displays the question in a non-editable state. Operators can view the question and answer but cannot change it.
showConditions
Defines a conditional display rule for the question, based on the answer to a previous question.
"showConditions": {
"questionKey": "employment-status",
"answer": "self-employed"
}
questionKey
Key of the controlling question.answer
Key of the answer (for radio/checkbox) or specific text (for string).
Options
Options are used exclusively in multiple-choice
, options
and dropdown
type questions. They define the selectable choices that the user can pick from.
Each question that supports options must include the following parameter:
options
An <array>
of option objects for the question. Each object must include the following:
title
The text label for the option, shown to the operator during in the verification session. Must always be provided as an <object>
with language codes as keys, even if only one language is used. This ensures consistency across multilingual flows.
{
"en": "ID card"
}
key
A unique identifier for the option within the questionnaire. This value is used for referencing in preset answers, conditions, and session data. It must be unique within the same questionnaire to avoid conflicts.
List of parameters with examples:
"key"
Keys are chosen by the client and must remain unique within a single session.
Recommended to use key describing the questionnaire shortly.
-
<string>
"key": "document-collection"
"title"
The title of the operator questionnaire, displayed as the tab name in the session. The title can be an <object>
containing different languages, allowing the title to be displayed in the selected language.
-
<string> or <object>
"title": {
"es": "Tu título",
"en": "Your title"
}
"description"
Similar to the title, the description can be an <object>
containing different languages, so that it can be displayed in the selected language.
-
<string> or <object>
"description": {
"es": "Tu descripción",
"en": "Your description"
}
"questions"
An <array>
of questions with the following types: string
, multiple-choice
and options
.
-
<array>
"questions": [
{
"type": "string",
"title": "Your title",
"key": "question1",
"mandatory": true
},
{
"type": "multiple-choice",
"title": "Your title",
"key": "question2",
"mandatory": false,
"options": [
{
"title": "Your title",
"key": "option1"
},
{
"title": "Your title",
"key": "option2"
}
]
}
]
"mandatory"
Specifies whether the question is required to be answered.
Possible values:
true
, false
false
<boolean>
"mandatory": false
"answer"
Allows to preset an answer for a question.
-
<string> or <array>
"answer": "option2"
"readOnly"
Displays the question but restricts interaction.
false
<boolean>
"readOnly": false
"showConditions"
This parameter may be used to set conditions for whether a question should be displayed.
-
<object>
"showConditions": {
"questionKey": "question1",
"answer": "option1"
}
cURL example:
Last updated
Was this helpful?