# Integration

The LiveID+ service provides several integration features:

1. inbound integration (start of video identification call) for synchronous calls;
2. outbound integration (client-side video identification status callback and server-side fully customizable callback) for synchronous calls;
3. asynchronous calls;
4. other useful features.


It is highly recommended to use the **asynchronous calls method** as it provides better control of the call flow.

br
## Inbound Integration

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`](/products/liveidplus/enterprise/developer-documentation/api-definition/app/servicestart) API description.

### Integration Modes

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`.


#### Embedded Mode Setup

If you choose to use embedded mode, the iframe must have the `allow` property set to include geolocation, camera, and microphone access:


```html
<iframe src="..." allow="geolocation; camera; microphone"></iframe>
```

### Starting a Call

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):**


```json
{
  "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](#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 |


#### Optional Parameters

| 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.

#### Self + Live Process Combination

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`.

br
## Outbound Integration

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:

1. **client-side callback**: served on client side using the HTML iframe postMessage API;
2. **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`);
3. **server-side callback**: in the form of POST requests to a specified HTTPS endpoint.


#### Client-Side Callback

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):**


```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;
    }
});
```

#### Redirect Parameter

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`).

#### Server-Side Callback

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](mailto:liveidplus.support@namirial.com).

**Server callback payload:**


```json
{
  "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](/it/products/liveidplus/enterprise/get-started/events) and [Call closing](/it/products/liveidplus/enterprise/get-started/call-closing) sections.



## Useful Service APIs

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.



## Third-party integration

- LiveID+ Calendly Integration (example)
- LiveID+ eSignAnyWhere third-party API integration