# service-start

Start the process for a video identification. It can be a live session with an operator or a self process, or a combination of both (in this case, a selection method should be discussed in advance with Namirial).
At the end of the process, or in case of errors, the page will be redirected to the `redirectUrl` (if specified) passing a `LiveIDPlusResult` POST parameter, containing the JSON result message in the same format specified in the [Call closing section](./../../../get-started/call-closing).
There are two ways to integrate LiveID+:
- **standalone mode**: the call is launched in a new browser tab and provides a server-side callback and a rediderct URL for client-side callbacks;
- **embedded mode**: the call is launched within an HTML iframe directly in the client procedure, allowing for client-side callbacks (in form of window.postMessage) as described in the [network and media test and call status check [Client side events section](./../../../get-started/events) and [Call closing section](./../../../get-started/call-closing)).

In case of embedded mode, the iframe must have `allow` property set to include geolocation, camera, and microphone access, as following:
`allow="geolocation; camera; microphone"`
If this API is used to start a single video identification process, the `id_process parameter` is mandatory.
If LiveID+ should automatically perform a check to decide whether to use a live process or a self process, the `id_process_live` and `id_process_self` are mandatory. The procedure to determine which process to choose has to be discussed with Namirial in the set up phase.
The `id_process` parameter and `id_process_self`, `id_process_live` couple are mutually exclusive.

Endpoint: POST /app/service-start
Version: 2.1.0

## Request fields (application/json):

  - `id_organization` (string)
    Identification code [CODE] of the calling organization.
*(Provided by Namirial during the platform setup)*

  - `external_id` (string)
    A custom ID to identify the call. It will be searchable in the reports (max 100 characters)

  - `redirectUrl` (string)
    The url where the browser should be redirected when the process is completed or in case of errors. Data will be passed as POST parameters as specified in the [Call closing section](./../../../get-started/call-closing)

  - `redirectMethod` (string)
    The HTTP method to use for the redirect.
    Enum: "GET", "POST"

  - `id_operator2Call` (string)
    ***Only for live processes***
Identification code of the operator to whom the call will be directly assigned.
***Please note***: if this parameter is set, the call will be automatically terminated with a KO if the operator doesn't answer, and it will not be assigned to any other operator available.
*(`id_operator2Call`, `email_operator2Call`, `extId_operator2Call` and `direct` parameters are mutually esclusive)*

  - `email_operator2Call` (string)
    ***Only for live processes***
Email of the operator to whom the call will be directly assigned.
***Please note***: if this parameter is set, the call will be automatically terminated with a KO if the operator doesn't answer, and it will not be assigned to any other operator available.
*(`id_operator2Call`, `email_operator2Call`, `extId_operator2Call` and `direct` parameters are mutually esclusive)*

  - `extId_operator2Call` (string)
    ***Only for live processes***
External ID of the operator to whom the call will be directly assigned.
***Please note***: if this parameter is set, the call will be automatically terminated with a KO if the operator doesn't answer, and it will not be assigned to any other operator available
*(`id_operator2Call`, `email_operator2Call`, `extId_operator2Call` and `direct` parameters are mutually esclusive)*

  - `direct` (string)
    ***Only for live processes***
Unique token sent to customer for calling a specified operator.
***Please note***: if this parameter is set, the call will be automatically terminated with a KO if the operator doesn't answer, and it will not be assigned to any other operator available
*(`id_operator2Call`, `email_operator2Call`, `extId_operator2Call` and `direct` parameters are mutually esclusive)*

  - `opInfo` (string)
    ***Only for live processes***
Useful information to show to Operator before answering the call (max length: 100 chars).

  - `skipAVrecTest` (boolean)
    *Only for live processes*
If set to `true`, compatibility test will skip the audio/video recording customer's check.

  - `disableRTCTest` (boolean)
    *Only for live processes*
If set to `true`, compatibility test will skip the WebRTC check.
It's suggested to set to `true` this property ONLY for processes that doesn't need a video registration.

  - `json` (object)
    JSON object containing all the configuration parameters for starting a call

  - `json.lang` (string, required)
    The ISO 639-1 Code of the language that will be used in the call (ex. "en", "it", ...)
    Example: en

  - `json.liveid_email` (string, required)
    email of the caller

  - `json.liveid_name` (string, required)
    name of the caller

  - `json.liveid_surname` (string, required)
    surname of the caller

  - `json.liveid_servercallback` (object)
    Configuration of an endpoint to call as a server callback at the end of the process
**For security reasons, the endpoint must be https and has to be approved by Namirial in advance**
Any request for new endpoints can be sent to liveidplus.support@namirial.com, specifying the organization code.
One or more email addresses can be registered to receive alerts about the server callbacks of a process using the [v2/registerAlertEmail](./../v2/registeralertemail) API.

  - `json.liveid_servercallback.url` (string, required)
    The URL to call at the end of the process.

  - `json.liveid_servercallback.otherParams` (object)
    A JSON object containing key-value pairs with additional parameters to be included in the POST request to the callback endpoint.

  - `json.liveid_servercallback.headers` (object)
    A JSON object containing key-value pairs of custom HTTP headers to send with the callback request (e.g. for authentication). Header names such as Host, Content-Length, Transfer-Encoding and Connection are ignored.

  - `json.liveid_priorityQueueLevel` (number)
    Sets a priority level (0 to 5, higher number means higher priority) in queue

  - `json.data` (object, required)
    a JSON representing the configuration of all the data fields for the process. The schema of each field is shown by the following "example_field"

  - `json.data.example_field` (object)

  - `json.data.example_field.datatype` (string, required)
    The data type of the field. It could be set to any of these HTML input element "type" attribute
    Enum: "checkbox", "date", "email", "month", "number", "tel", "text", "time", "url"

  - `json.data.example_field.label` (string, required)
    The label to show

  - `json.data.example_field.value` (string, required)
    The value of the field

  - `json.data.example_field.display` (string)
    If set to "none" the field will not be shown in the data visualization modules.
If set to "operator" the field will be visible only to the operator
    Enum: "none", "operator"

  - `json.data.example_field.order` (number)
    The numeric order in which to show the fields

  - `json.data.example_field.disabled` (boolean)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.maxlength` (number)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.max` (number)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.min` (number)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.pattern` (string)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.placeholder` (string)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.readonly` (boolean)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.required` (boolean)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.size` (number)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.step` (number)
    HTML input attribute for validation and more (see HTML input attributes)

  - `json.data.example_field.title` (string)
    HTML input attribute for validation and more (see HTML input attributes)

  - `id_process` (string, required)
    Unique identifier of the identification process that will be performed.
*(Provided by Namirial during the platform setup)*
*(This parameter is mutually exclusive with `id_process_live` and `id_process_self`)*

  - `id_process_self` (string, required)
    Unique identifier of the self identification process that will be performed.
*(Provided by Namirial during the platform setup)*
*(This parameter is mutually exclusive with `id_process`)*

  - `id_process_live` (string, required)
    Unique identifier of the live identification process that will be performed.
*(Provided by Namirial during the platform setup)*
*(This parameter is mutually exclusive with `id_process`)*

## Response 200:

  - `200` (unknown)
    Success

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 409:

  - `409` (unknown)
    Conflict

## Response 500:

  - `500` (unknown)
    Internal Server Error

