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.
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:
/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)
- Oas file url https://console.openapi.com/oas/en/videoid.openapi.json
- Fork or import with Postman
- Production domain videoid.openapi.com
- Sandbox domain test.videoid.openapi.com
- Production Scopes 4
-
Sandbox Scopes 4
- GET test.videoid.openapi.com/IT-identity-verifications
- POST test.videoid.openapi.com/IT-selfie
- POST test.videoid.openapi.com/IT-live
- POST test.videoid.openapi.com/IT-automatic