Onboarding allows the online identification process to be carried out with the support of specialized operators, implementing all the steps required by the Know-Your-Customer regulations.

Generally, there are two types of certified onboarding identification methods:

• Self-Service, with the certified recognition types using the SPID/CIE/CNS and AI services provided with computer vision and speech recognition algorithms

• Assisted, available to carry out de visu recognition or certified video conferencing with a trained operator

Every procedure is 100% paperless. The Onboarding service together with Signing allows you to sign contracts with legal value by issuing electronic signature certificates.

Onboarding provides multiple roles, according to the request privileges:

• manager, in charge of creating, editing and disabling operators, as well as collecting data and achieving the completion of recognition processes

• approver, in charge of collecting data for and approving assisted recognition processes

• operator, in charge of collecting data for recognition practices.

In Onboarding platform is possible to accomplish many recognition processes, the most used are:

• SPID/CIE/CNS/FEQ certified recognition: the user can be recognized thanks to his certified digital identity without the need to upload any identity document

• AI certified identification: processes based on Artificial Intelligence in order to automatically check user identity, collected data and uploaded documents; the algorithms verify the identity through biometric comparison and proof of life ensuring regulatory compliance (AML, KyC and Adequate Verification) of the entire process

• DeVisu Identification: an operator who meets the customer to be recognized in person will fill out a pre-set/custom form to register the user without the need for prints or scans, from entering the request to verifying the document

• Recognition with certified videoconferencing: the procedure is similar to that listed in the previous point with the difference that the client can be called remotely.

The environments to integrate Onboarding via API are different according to the purpose.

API environments and WEB environments follow the same semantics described in the previous paragraph.

Access to the WEB environment, even in the case of API integration, is recommended to retrieve useful data for the correct configuration of the onboarding request creation payload.

This tutorial shows you how to be getting started with Onboarding API, by creating your first identification request.

To use the Onboarding API, it is important that you understand the basics of RESTful web services and JSON representations.

Before you begin

1. Choose the right environment to contact among SANDBOX, DEMO, LIVE (e.g. https://api.sandbox.onboardingtoday.com)

2. Choose your authentication type between X-API-KEY and JWT:

   • To use the X-API-KEY, you need to define the x-api-key HTTP header which contains the x-api-key value. The X-API-KEY token is static and has no expiration. The x-api-key value is sent to the Onboarding user with the email for the first access to the platform.

   • To use the JWT token, you need to obtain it by calling the API /auth (described below). Then, you need to use the Authorization HTTP header which contains the value Bearer then a blank space and the JWT token. JWT token has an expiration of 10 minutes, so it must be refreshed before, otherwise it has to be requested each time you call the Onboarding API.

3. Remember that, if the request has a body, another HTTP header is required: Content-Type, with application/json value.

4. (optional) Choose a webhook service to receive notifications from onboarding. The onboarding platform sends POST requests which contains useful data such as:

   • request identifier: data.id;

   • current status of the onboarding request: data.current_status;

Step 1 Create a request

Create a request using the Create new request API, necessarily defining:

1. the request type that is the identifier of the onboarding request

2. the domain to refer the onboarding request to (this data is provided with the activation of the service)

3. the user object (name, surname, tax identifier and e-mail address)

4. the notification_channel field the link to the chosen notification service.

Disclaimer: An Onboarding request can be also anonymized omitting user parameter just in case this scenario is supported by the request type.

Step 2 Get the request ticket

The response of the Create new request API will contain the request_ticket. That is the pre-authenticated link to access the onboarding process.

Otherwise, if you want to obtain the request ticket in other ways, you can call the Get an identification request API passing the request identifier.

Step 3 Complete the onboarding

The request ticket is sent to the user's e-mail address (if specified and supported by the onboarding request type).

Otherwise, the request ticket can be sent externally to the user (e.g., by redirecting the user journey to the onboarding link).

To test the workflow, complete yourself the process and check what happen at the end (on the set notification channel and calling a Get an identification request API on the request identifier).

In the API reference below, the following HTTP verbs are used.

Onboarding offers multiple types of workflows. An Onboarding request type is a unique process available on the platform and more than one request type can be associated with a single domain.

A request type represents the onboarding workflow which can be finalized for recognition only or spent to issue a digital identity certificate. Moreover, the recognition workflow could be spent by the customer (e.g., the authentication or the AI process) or by an operator (e.g., the KyC assisted by an operator).

To create an onboarding request, you need to specify the request type which is represented by a UUIDv4 string.

Disclaimer: Every single type must be activated on demand.

A request can have multiple statuses, which are described in table.

The succession of the states is described in the finite state machine below. Even if a request type does not provide one of the represented statuses (e.g., in a request finalized to the only recognition with no certificate issuance) the request goes through all the statuses without jumping over them (so, you could receive some skippable notifications).

Note: Draft state is passed only if your request type needs to use a plug-in. A plug-in is a component added to the standard flow of the request type that allows you to make additional operation as being compliant with AML standard.

Below is a table illustrating each state associated with an identification and FEA issuance process.

State semantic for identification process

State semantic for Digital Identity issuance process

You will receive notifications for each recognition/issuance process only if you have setted a notification channel when creating the request. In each notification you can see details about:

• id: identifier of the associated onboarding request

• action: which let you know what kind of operation was made (also automatically from the system)

• previous_status: which is and empty string for the first notification

• current_status: the status represented by the notification

• action_made_by: who has made the operation reported by the notification

• request_type: the type of the associated request

The webhook notifications received in order since the request was created are described below. You will receive as first notification the following that informs of the happened creation of the practice and the necessity of preliminary actions if provided by the chosen request type:

  {
    "message": "Identity request status changed",
    "notification_created": "<date>",
    "data": {
      "id": "<id>",
      "action": "create",
      "previous_status": "",
      "current_status": "draft",
      "timestamp": "<timestamp>",
      "action_made_by": {
        "fiscal_code": "<cf>",
        "role": "<role>",
        "organization_path": "onboarding"
      },
      "request_type": {
        ...
      },
      "metric_type": "REQUEST_EVENT"
    }
  }

Otherwise as first notification you will receive the following informing you of the creation of the request:

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "create",
    "previous_status": "",
    "current_status": "created",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

If you have recieved the draft status notification you will see as previous_status the draft in the body of the created request notification. After the data entry performed by the customer or by an operator, the request will be in the compiled status:

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "compile",
    "previous_status": "created",
    "current_status": "compiled",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

After the approval performed by an operator or by the AI algorithm (if provided by the request type):

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "approve",
    "previous_status": "compiled",
    "current_status": "approved",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

Once the request is in approved status, the process of recognition. Otherwise, an operator (or the AI algorithm) can reject a request. In this case you will receive a notification that shows the current_status valued as rejected.

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "reject",
    "previous_status": "compiled",
    "current_status": "rejected",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

Only if the request has got through the approved status, the user can enter the additional data (where necessary in case of certificate issuance).

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "issue",
    "previous_status": "approved",
    "current_status": "issued",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
    ...
    },
    "metric_type": "REQUEST_EVENT"
  }
} 

Once all procedures are over, the performed notification can be sent:

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "perform",
    "previous_status": "issued",
    "current_status": "performed",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

A request could be cancelled after an error or ticket expiration and you will receive a notification like this.

{
  "message": "Identity request status changed",
  "notification_created": "<date>",
  "data": {
    "id": "<id>",
    "action": "cancel",
    "previous_status": "previous_status",
    "current_status": "cancelled",
    "timestamp": "<timestamp>",
    "action_made_by": {
      "fiscal_code": "<cf>",
      "role": "<role>",
      "organization_path": "onboarding"
    },
    "failure_reason": "<reason>",
    "request_type": {
      ...
    },
    "metric_type": "REQUEST_EVENT"
  }
}

The request_ticket is a pre-authenticated URL to be provided to the user. Through this link, the user can access the frontend interface to perform the suitable recognition method (authentication, data-entry and so on).

The request ticket is generated at the same time as the creation of the request and can be retrieved in the request_ticket field in the response of Create an identification request API.

It is also possible to obtain the request_ticket from the Get an identification request API, passing the request identifier. The request ticket has a configurable duration that shows the expiration time of the ticket. When the ticket expires, the corresponding request goes into the 'Cancelled' status.

Note: a typical scenario of use of the ticket is the redirection: for example, the customer comes from another platform on which he previously chose to start an onboarding process. In this case, it is possible to exploit a type of request which does not include the functionality of sending emails from Onboarding.

The identification_proof is a pre-authorized link for downloading the proof of identification generated by Onboarding and signed (e.g., with a qualified electronic seal).

In case of recognition by video, the link allows to download the evidence collected during autonomous or operator-assisted video recognition.

It is possible to get the identification_proof by using the Get an identification request API on a request in status completed belonging to the proper request type. The link to download the identification proof expires after one hour and you can regenerate it by repeating the call to the Get an identification request API.

The API section having tag Authentication allows to:

• Perform login, simply passing the login credentials in response will return an access token, expendable to navigate the platform;

• Perform logout, simply sending a DELETE HTTP to the platform;

• Perform refresh-token, simply passing in a POST HTTP the access token;

• Perform password change, passing in a POST HTTP the username, the old and new password for the target user;

• Perform password change self-service, simply passing in a post request the username of the target user who receive a mail with instruction for changing his password.

The API section having tag Requests allows to:

• Create a request, allows you to define parameters like:

  • user, allows you to define the user to be recognised. The parameters defined in user field are used for some controls in identification process for example the fiscal_code is used in the SPID identification process to check that the parameters provided by the provider are those of the declared individual. The security control involves matching the declared fiscal code with the one received in the SPID provider's metadata. If you do not know the user's info, you may not fill in the field and create an anonymous request;

  • urlback, allows the entry of a url that will be contacted after a file enters the completed status. The platform will contact the defined link with status 10 (completed) and the request_id as query param;

  • notification_channels parameter values the list of channels on which the change of status of the request is intended to be communicated. Below is the example:

  • external_reference, can be used to introduce a constraint. If you have created a request with the external reference value, you can't create a new request with the same external reference. It could be useful if you need to bind the onboarding request with an external flow.

  • metadata field to pass subsidiary information for the request on which no search will be possible. It can be used to pass on the information needed to use LiveID, if included in the purchased package, or for some tracking metrics of interest to your company. Is in general a field, which allows you to customize your flow.

• Read one or more request by sending a GET HTTP

• Delete request, by sending the id of the target request in a DELETE HTTP

• Make an action, for example request compiled.

The API section having tag Requests types allows to:

• List all types for a specific provider, e.g. Types enabled for SPID provider

• List all types enabled for your organisation

• Modify filed of a specific request type

• Create new request type

• Retrieve information about a specific request type

• Delete a specific request type

The API section having tag Actions allows to:

• Make an action on a specific request

The API section having tag Users allows to:

• Create an operator;

• Send an email for setting password for first time;

• Get the operator list;

• Get info about one operator, is possible to know the if the operator is active or not, by exploring the boolean field enabled. Also exploring the field "role" is possible to know the role in a specific organization of this user;

• Modify data or setting of an operator, is possible to disable an user calling the API /operator/{cf}/{role}/{org-path} using a PATCH, defining in url the cf of the target user, the role and organization, and defining in body the field "enabled" valued as "false"

The API section having tag Manage password allows to:

• Resend email for first password changing;

• Change password for a specific user;

• Send email for password changing.