Video Id

  1. Home
  2. API Library
  3. Video Id
Video Identification in Automatic or Operator-assisted Mode

The perfect solution for digital onboarding activities, compliant verification, and remote contract processes.

All the knowledge you need

Here you can find some advice to consider to approach this API. If you prefer, we provide code samples, OAS3 documentation, the ability to try the API live via the Swagger UI or import the entire collection into Postman. We also offer a Sandbox environment where you can experiment with all kinds of requests completely free of charge.

Useful tips to start with Video Id

Get the token in the appropriate section before you start.

Use the the online tool or generate it via API. Set the expire date, a usefull name and now add a bunch of scopes to limit the possible actions your token can do.
Read more on oauth API Manage my tokens

Choose the type of video recognition and get the link

Request the type of video recognition based on your needs:
/automatic,  /selfie,  /live,  In the payload of your request, fill in the sections:
  • "user"
    It can be set to NULL if the user needs to be recognized from scratch or configured for identity verification, for example: 
                {
              "firstName": "Franco",
              "lastName": "Rossi",
              "gender": "M",
              "birthCountry": "Italy",
              "birthDate": "1977-11-06",
              "birthPlace": "Rome",
              "taxCode": "RSSMRA02D16A662G"
            }
  • "healthCard"
    Determines whether to acquire the health card photos. If "required" is set to true, an additional check ("checkExpire") can be activated to verify the expiration of the acquired health card. For example: 
    { "required": true, "checkExpire": true }
  • "phoneNumber"
    Verify and/or acquire the user's phone number certified by an OTP code sent automatically by the system. For example: 
    { "required": true, "editable": false, "number": "123456789"}
    Setting editable to true allows changing the phone number during video recognition.
  • "policy"
    Through this parameter, the client specifies the link to the privacy policy. This link will be used as an external link on the consent acceptance page. For example: 
    { "url": "https://www.company.it/privacy-policy/" }
  • "output"
    Determines whether the acquired documentation will be rendered in a single PDF file or an archive containing individual separate graphic files will be returned. For example: 
    { "imagesAsPdf": false }
  • "layout"
    Configures the video recognition interface by customizing its UI. For example: 
    {
            "title": "Video ID",
            "logo": "https://www.website.it/logo.png",
            "favicon": "https://www.website.it/favicon.png",
            "backgroundColor": "#cecece",
            "textColor": "#000000",
            "footer": "Company Spa, VAT 11111111111"
          }
  • "callback"
    Configures your webhook to receive asynchronous updates on the procedure. For example: 
    {
            "url": "https://mycallback.site/",
            "method": "POST",
            "field": "data",
            "headers": {
              "session_id": "oiwejdf89453urf945jfg"
            }
          }

Review the response

The response will contain, in addition to the status of the process and its "id," also a "link". It should be sent to the user who needs to perform the video recognition. For example: 
{
        "data": {
          "id": "aaaaaaaa-1111-2222-dddd-123456789",
          "link": "https://sit-openapi.certid.it/aaaaaaaa-1111-2222-dddd-12345678",
          "message": "The link for the automated Video Identification service.",
          "status": "running",
          "owner": "[email protected]"
        },
        "success": true,
        "message": "",
        "error": null
      }

Wait for the video recognition to be complete and get the result

If you have set the "callback," once the video recognition is complete, you will receive an HTTP request on your webhook. At this point, if the "completed" status is equal to "true," you can proceed to download the verification details, including the documents produced during recognition: 
{
        "_id": "28b3a20e-ffcc-4245-843a-563e9ff5f31b",
        "callback": {
          "url": "https://webhook.site/ab91d3f3-c246-498a-9af5-828bf13dd8ef",
          "method": "POST",
          "field": "data",
          "headers": {
            "session_id": "oiwejdf89453urf945jfg"
          },
          "data": {}
        },
        "link": "https://openapi.certid.it/28b3a20e-ffcc-4245-843a-563ddff5f31b",
        "status": "ok",
        "completed": true,
        "owner": "[email protected]",
        "creationTimestamp": 1706283108,
        "lastUpdateTimestamp": 1706283108,
        "reason": null
      }

If you haven't set the "callback," you can still check the status of your request at the endpoint: /IT-identity-verifications/{id}

To get the procedure details, make a call to: /IT-identity-verifications/{id}/{type} where {id} is the procedure ID and {type} is one of the two options:
  • "data": returns structured data with information about the recognized subject: 
    {
            "firstName": "Franco",
            "lastName": "Rossi",
            "gender": "M",
            "birthCountry": "Italy",
            "birthDate": "1977-11-06",
            "birthPlace": "Rome",
            "taxCode": "RSSMRA02D16A662G",
            "documentType": "drive_license",
            "documentNumber": "1111111111",
            "documentDate": "2011-01-10",
            "documentExpiration": "2033-11-06",
            "healthCardExpiration": "2028-01-19",
            "healthCardID": "81111111111111111100"
          }
  • "archive": returns a zip package (Content Type: application/zip) containing files related to the procedure (video if present, images of the document and the subject)
.
API docs by Redocly

IDENTITY VERIFICATION (1.0.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

The Video Recognition service offers a streamlined and secure digital onboarding experience for users. This guided process allows users to access and authenticate themselves on the platform through positive identification supported by an advanced data verification system.

Through Video Recognition, users can provide the necessary information for onboarding. The system verifies identities in real-time, approving requests that meet predefined criteria. In cases of negative outcomes during the process, the system notifies the provider with detailed information regarding the cause of refusal, allowing for corrections or appropriate actions.

To facilitate integration and understanding of the service, a sandbox environment is available to test the functionality of Video Recognition. The sandbox link enables experimentation with various features and simulation of identification scenarios in a controlled environment.

This technical document illustrates the flow and different possible outcomes during the video identification process, including scenarios such as positive identifications, repeatable or definitive negative outcomes, and their corresponding communications to the Provider system.

First time here? Generate a new access token

IDENTITY VERIFICATION

List of your requests verifications

This method Show the list of requests made for video recognition.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array of objects (SuccessResponse)
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://videoid.openapi.com/IT-identity-verifications");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{}

Check status

This method shows you the specific request made for video recognition in order to check its status.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: AAAAAAA-9122-4ec9-b93b-8c63a301dc79

Request id

Responses

Response Schema: application/json
object (SuccessResponse)
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://videoid.openapi.com/IT-identity-verifications/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{}

To request the data

  • /data: Returns a JSON with all the data.
  • /archive: Returns a PDF or images of the documents based on the 'output' value set during the POST request with the value 'output': { 'imagesAsPdf': false }.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: AAAAAAA-9122-4ec9-b93b-8c63a301dc79

Request id

type
required
string
Example: data

/data or /archive

Responses

Response Schema:
object (SuccessResponse)
success
boolean
message
string
error
integer

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://videoid.openapi.com/IT-identity-verifications/%7Bid%7D/%7Btype%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Automatic video recognition

This service allows obtaining a link to access a platform for initiating Automatic Video Recognition. Users independently undergo the video recognition procedure at any time, following a defined process that involves document acquisition, facial photos, and a short video to confirm liveness. The platform performs automatic checks based on OCR algorithms, liveness checks, and face matching.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (Callback)
mail
required
string
required
string or object

user can be set with the required parameters to add data verification, otherwise it can be left as null.

required
object

By using this parameter, the client can indicate the willingness to acquire or not the photos of the health card. If set to true, it will be possible to activate an additional check to verify the expiration of the acquired health card. If 'required' is set to true, the second field, 'checkExpire,' becomes mandatory.

required
object

Through this parameter, the client can specify whether to verify and/or acquire the user's phone number certified by an OTP code sent automatically by the system. Examples below:

  • Verification and the ability for the user to edit the phone number: "phoneNumber":{ "required": true "editable": true "number": "3391122334" }

  • Verification without the user's ability to edit the phone number: "phoneNumber":{ "required": true "editable": false "number": "3391122334" }

  • Verification with user-input phone number (without user edit): "phoneNumber":{ "required": true "editable": false "number": null }

  • Request without phone number verification: "phoneNumber":{ "required": false "editable": false "number": null }

required
object

Through this parameter, the client specifies the link to the privacy policy. This link will be used as an external link on the consent acceptance page.

required
object

Through this parameter, the client specifies their preferences regarding the format of the identity document photos acquired by the system.

Request example with output in a single PDF: "output": { "imagesAsPdf": true } csharp Copy code Request example with output in separate files: "output": { "imagesAsPdf": false }

required
object

Through this parameter, the client can specify various preferences useful for the characterization of the web layout. The following elements can be specified:

  • Title: The title displayed on the web layout. - Logo: The URL to the logo image to be displayed. - Favicon: The URL to the favicon image to be displayed. - Background Color: The preferred background color for the layout. - Text Color: The preferred text color to be used. - Footer: Additional information or text to be displayed at the footer of the layout.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string

Callbacks

Request samples

Content type
application/json
{
  • "callback": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: State changes are notified through callback APIs.
Content type
application/json
{}

Selfie video recognition

This service allows obtaining a link to access a platform for initiating Automatic Video Recognition. The user performs a video recognition at any time, following a guided procedure that involves recording a short video and capturing documents. The validation of the entered data will be carried out later by back office operators.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (Callback)
mail
required
string
required
string or object

user can be set with the required parameters to add data verification, otherwise it can be left as null.

required
object

By using this parameter, the client can indicate the willingness to acquire or not the photos of the health card. If set to true, it will be possible to activate an additional check to verify the expiration of the acquired health card. If 'required' is set to true, the second field, 'checkExpire,' becomes mandatory.

required
object

Through this parameter, the client can specify whether to verify and/or acquire the user's phone number certified by an OTP code sent automatically by the system. Examples below:

  • Verification and the ability for the user to edit the phone number: "phoneNumber":{ "required": true "editable": true "number": "3391122334" }

  • Verification without the user's ability to edit the phone number: "phoneNumber":{ "required": true "editable": false "number": "3391122334" }

  • Verification with user-input phone number (without user edit): "phoneNumber":{ "required": true "editable": false "number": null }

  • Request without phone number verification: "phoneNumber":{ "required": false "editable": false "number": null }

required
object

Through this parameter, the client specifies the link to the privacy policy. This link will be used as an external link on the consent acceptance page.

required
object

Through this parameter, the client specifies their preferences regarding the format of the identity document photos acquired by the system.

Request example with output in a single PDF: "output": { "imagesAsPdf": true } csharp Copy code Request example with output in separate files: "output": { "imagesAsPdf": false }

required
object

Through this parameter, the client can specify various preferences useful for the characterization of the web layout. The following elements can be specified:

  • Title: The title displayed on the web layout. - Logo: The URL to the logo image to be displayed. - Favicon: The URL to the favicon image to be displayed. - Background Color: The preferred background color for the layout. - Text Color: The preferred text color to be used. - Footer: Additional information or text to be displayed at the footer of the layout.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string

Callbacks

Request samples

Content type
application/json
{
  • "callback": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: State changes are notified through callback APIs.
Content type
application/json
{}

Live video recognition

This service allows obtaining a link to access a platform for initiating Automatic Video Recognition. The user is supported in real-time by an operator throughout the video recognition procedure and verification of data accuracy.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (Callback)
mail
required
string
required
string or object

user can be set with the required parameters to add data verification, otherwise it can be left as null.

required
object

By using this parameter, the client can indicate the willingness to acquire or not the photos of the health card. If set to true, it will be possible to activate an additional check to verify the expiration of the acquired health card. If 'required' is set to true, the second field, 'checkExpire,' becomes mandatory.

required
object

Through this parameter, the client can specify whether to verify and/or acquire the user's phone number certified by an OTP code sent automatically by the system. Examples below:

  • Verification and the ability for the user to edit the phone number: "phoneNumber":{ "required": true "editable": true "number": "3391122334" }

  • Verification without the user's ability to edit the phone number: "phoneNumber":{ "required": true "editable": false "number": "3391122334" }

  • Verification with user-input phone number (without user edit): "phoneNumber":{ "required": true "editable": false "number": null }

  • Request without phone number verification: "phoneNumber":{ "required": false "editable": false "number": null }

required
object

Through this parameter, the client specifies the link to the privacy policy. This link will be used as an external link on the consent acceptance page.

required
object

Through this parameter, the client specifies their preferences regarding the format of the identity document photos acquired by the system.

Request example with output in a single PDF: "output": { "imagesAsPdf": true } csharp Copy code Request example with output in separate files: "output": { "imagesAsPdf": false }

required
object

Through this parameter, the client can specify various preferences useful for the characterization of the web layout. The following elements can be specified:

  • Title: The title displayed on the web layout. - Logo: The URL to the logo image to be displayed. - Favicon: The URL to the favicon image to be displayed. - Background Color: The preferred background color for the layout. - Text Color: The preferred text color to be used. - Footer: Additional information or text to be displayed at the footer of the layout.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string

Callbacks

Request samples

Content type
application/json
{
  • "callback": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: State changes are notified through callback APIs.
Content type
application/json
{}
Web Service Revision: 2.0.0