The LiveID+ service provides several integration features:
- inbound integration (start of video identification call) for synchronous calls;
- outbound integration (client-side video identification status callback and server-side fully customizable callback) for synchronous calls;
- asynchronous calls;
- other useful features.
It is highly recommended to use the asynchronous calls method as it provides better control of the call flow.
The inbound integration feature allows organizations to start a video identification call from their own web application. This feature is useful for organizations that want to integrate video identification into their existing workflows.
All the details can be found in the app/service-start API description.
There are two modes in which the video identification call can be initiated:
- Standalone mode: The call is launched in a new browser tab. Supports server-side callbacks and redirect URL for client-side callbacks.
- Embedded mode: The call is launched within an HTML iframe directly in the client page, allowing for real-time client-side callbacks via
window.postMessage.
If you choose to use embedded mode, the iframe must have the allow property set to include geolocation, camera, and microphone access:
<iframe src="..." allow="geolocation; camera; microphone"></iframe>To start a video identification, submit a POST request to app/service-start with the following required parameters:
| Parameter | Type | Description |
|---|---|---|
id_organization | string | Organization code (provided by Namirial during setup) |
id_process | string (UUID) | Process identifier (provided by Namirial during setup) |
json | object (Base64) | UTF-8 Base64 encoded JSON containing customer data and configuration |
The json parameter must be a UTF-8 Base64 encoded JSON object following the ServiceStartJson schema. It contains customer information, callback configuration, and custom data fields.
Example json structure (before Base64 encoding):
{
"lang": "en",
"liveid_email": "john.doe@example.com",
"liveid_name": "John",
"liveid_surname": "Doe",
"liveid_servercallback": {
"url": "https://your-system.com/callback",
"otherParams": {
"custom_reference": "REF-12345"
}
},
"liveid_priorityQueueLevel": 0,
"data": {
"fiscal_code": {
"datatype": "text",
"label": "Fiscal Code",
"value": "RSSMRA85M01H501Z",
"order": 1,
"readonly": true
},
"birth_date": {
"datatype": "date",
"label": "Date of Birth",
"value": "1985-08-01",
"order": 2
}
}
}The required fields are: lang, liveid_email, liveid_name, liveid_surname, and data.
The data object contains custom data fields where each field has the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
datatype | string | Yes | HTML input type: text, date, email, number, tel, checkbox, month, time, url |
label | string | Yes | Display label for the field |
value | string | Yes | Value of the field |
display | string | No | "none" to hide the field, "operator" for operator-only visibility |
order | number | No | Display order of the field |
disabled, readonly, required, maxlength, max, min, pattern, placeholder, size, step, title | various | No | Standard HTML input attributes for validation |
The liveid_servercallback object configures the server-side callback endpoint (see Outbound Integration):
| Property | Type | Required | Description |
|---|---|---|---|
url | string (URI) | Yes | HTTPS endpoint to call at the end of the process (must be pre-approved by Namirial) |
otherParams | object | No | Additional key-value pairs to include in the callback POST request |
headers | object | No | Additional HTTP headers to include in the callback request |
| Parameter | Type | Description |
|---|---|---|
external_id | string | Custom ID to identify the call in reports (max 100 characters) |
redirectUrl | string (URI) | URL where the browser redirects at end of process |
redirectMethod | string | HTTP method for the redirect: GET or POST (default: POST) |
id_operator2Call | string (UUID) | Route call to a specific operator by LiveID+ ID |
email_operator2Call | string (email) | Route call to a specific operator by email |
extId_operator2Call | string | Route call to a specific operator by external ID |
direct | string (JWT) | Unique token for calling a specified operator |
opInfo | string | Information to show the operator before answering (max 100 chars) |
skipAVrecTest | boolean | Skip audio/video recording check in compatibility test |
disableRTCTest | boolean | Skip WebRTC check (only for processes without video registration) |
Note: id_operator2Call, email_operator2Call, extId_operator2Call, and direct are mutually exclusive. When any of these is set, the call is terminated if the specified operator does not answer — it is not reassigned to another operator.
Instead of specifying a single id_process, you can use id_process_live and id_process_self together to let LiveID+ automatically determine whether to start a live or self-identification process based on preconfigured criteria. These two parameters are mutually exclusive with id_process.
When a video identification call is initiated, the LiveID+ service provides the ability to receive status updates about the call.
The application can receive the status updates in three ways:
- client-side callback: served on client side using the HTML iframe postMessage API;
- redirect parameter: when a redirect URL is provided, the LiveID+ client will redirect the user to the specified URL passing the result as a parameter (GET or POST, configurable via
redirectMethod); - server-side callback: in the form of POST requests to a specified HTTPS endpoint.
In case of an embedded integration (via HTML iframe), LiveID+ sends postMessage events to the main integrator's page to report the results of network and media tests, as well as the status of an active call.
These messages originate from the LiveID+ client platform and can be received by the parent page hosting the iframe.
To handle these messages, a message event listener must be registered on the client page.
Example (JavaScript):
window.addEventListener("message", function (event) {
switch(event.data.event) {
case 'close':
// Handle close event
break;
case 'error':
// Handle error event
break;
case 'WEBRTCTEST_OK':
// Compatibility test passed
break;
case 'WEBRTCTEST_KO':
// Compatibility test failed
break;
case 'WEBRTCTEST_CALLANSWERED':
// Operator answered, event.data.idConf contains conference ID
break;
case 'WEBRTCTEST_CALLNOTANSWERED':
// No operator answered, event.data.retry indicates retry attempt
break;
case 'WEBRTCTEST_CALLCANCELLED':
// Customer cancelled the call
break;
// ...
case 'status_call':
// Real-time call status update
break;
default:
// Handle other cases
break;
}
});If a redirectUrl is provided in the app/service-start method, the LiveID+ client will redirect the user to the specified URL, passing the JSON result in a LiveIDPlusResult parameter. The HTTP method used for the redirect can be configured via the redirectMethod parameter (GET or POST, defaults to POST).
If a liveid_servercallback parameter is specified in the json object when starting a call, LiveID+ sends a POST request to the specified URL for call closing status events and errors.
For security reasons, the server callback domain must be HTTPS and pre-approved by the LiveID+ team. To ask for approval, please contact the LiveID+ support team at liveidplus.support@namirial.com.
Server callback payload:
{
"closeStatus": "N",
"otherParams": { },
"idConference": "conference-uuid"
}The closeStatus values are: N (successfully completed), S (suspended), A (aborted), K (system error).
It is possible to register an email address to receive notifications when server-side callbacks fail. This can be done by using the v2/registerAlertEmail API.
More details on the events messages can be found in the Events and Call closing sections.
LiveID+ provides a set of utility APIs that can help integrators manage the call experience:
| API | Method | Description |
|---|---|---|
/api/service/getAvailableOperators | POST | Get the number of operators currently available for an organization |
/api/service/getQueue | POST | Get the number of people in queue for a specified process |
/api/service/availableLanguages | POST | Get the languages spoken by an organization's operators |
/api/service/getDailyWaitingTimes | POST | Get average daily waiting times (last week and last 60 minutes) |
All these APIs require the orgCode (or id_process for getQueue) parameter.