Latest version: V3
\nProtocols: HTTPS
\nProduction:
\nBase address: https://verifid.ondato.com
\nSwagger: https://verifid.ondato.com/swagger/index.html
\nBack-office: https://bo.ondato.com
\nSandbox:
\nBase address: https://sandbox-verifid.ondato.com
\nAPI Swagger: https://sandbox-verifid.ondato.com/swagger/index.html
\nBack-office: https://sandbox-bo.ondato.com
\nVerifId customer identification API is used for KYC process.
\nThe API provides third party applications with information belonging to the third party customer documents:
\nDocument data:
\nFirst name
Middle name
Last name
Document number
Date of issue
Date of expiration
Date of birth
Personal identity code
Address
Nationality
Country
Gender
Document type
Also this service compares persons face with the face in the provided document.
\nThis API is closely linked with the Ondato Back-office. Once the VerifID service processes document data clients can view those identifications inside Ondato Back-office. Clients can also double check identification details (cross check) and manually reject or edit document data and then verify the identification.
\nService short guide:
\nClient authorizes its app with Ondato service and gets access token in response
Client starts new identification session and a unique identificationId is returned
Client uploads his customers photo or video together with his customer document files or uploads NFC data
Client calls /verification/ endpoint and gets processed rule statuses if the client is happy with the result then it proceeds to next step, if not - calls again 3rd-4th steps
Client calls /completion/ endpoint so that no more new media files can be uploaded and the identification can be visible in BO. Additional registries are processed in this step
VerifID services processes the data and puts identification details in Ondato Back-office
Client double checks the identification details and cross-checks the identification
When identification details are updated client gets webhook HTTPS message to his provided URL address
This API is available in the following environments:
\nSandbox(test)
Production
*Note that in the sandbox environment all of the identification data is removed after 24 hours since the identification was started
\nWebhooks are user-defined HTTP callbacks. They are usually triggered by some event.
\nOndato provides webhooks to alert you of changes in the status of customer identification. These are POST requests to your server that are sent as soon as an event occurs. The body of the request contains details of the identification status.
All identification status changes trigger webhook notifications, even for those that complete instantly. If the document data will be changed manually from BO then webhook notification will also be triggered.
\nWebhook endpoints can be registered through the Ondato BO or VeridId API. To help you diagnose or to understand webhook issues, a log of your webhook requests is also available under your dashboard’s Webhook Logs and through the API endpoint.
\nUpon receiving a webhook notification, you should acknowledge success by responding with an HTTP 200 success status code. Otherwise, we will attempt to resend the notification up to 3 times every 10 minutes.
The following events will trigger a message to registered webhooks:
\nPROCESSED - Webhook is triggered when new identification is processed
CROSS_CHECKED - Webhook is triggered when identification is cross checked / approved in Ondato BO
UPDATED - Webhook is triggered when document data is updated in Ondato BO
REJECTED - Webhook is triggered when identification is rejected in Ondato BO
Each webhook URL is associated with a unique identification ID. When providing the URL you need to specify the place where our services will put the identification ID.
\nFor example:
\nhttps://mycompany.com/ondato_webhook/`{identification-id}`/receive
\nhttps://demo.com/ondato_webhook?identification=`{identification-id}`
\nhttps://demo.com/ondato_webhook?status=xxx&identification=`{identification-id}`¶m=abc
\nThen the {identification-id} will be replaced with a unique identification ID from our API services:
\nhttps://demo.com/ondato_webhook/`12345e24a362476cbc263872bd8ea254`/receive
\nhttps://demo.com/ondato_webhook?identification=`12345e24a362476cbc263872bd8ea254`
\nhttps://demo.com/ondato_webhook?status=xxx&identification=`12345e24a362476cbc263872bd8ea254`¶m=abc
\nFor security reasons webhooks sent to your application will be signed using unique per application generated signature. Verifying the request signature on your server prevents attackers from imitating valid webhooks. The signature will be stored in a X-API-KEY header.
Example response body:
\nHeader:Content-Type: application/jsonX-API-KEY: 6CC494A4-1BDE-4093-A0BD-8756B0BFDECA
Body:
\n{\n \"Id\":\"0BA5FDC0-A505-4CCC-CD3B-08D6FEFE2503\",\n \"RequestStatus\":\"AUTO_FINISH\",\n \"IsCrossChecked\":true,\n \"RejectionReason\":null,\n \"Event\":\"PROCESSED\"\n}\n\nBasic BASE64(ApplicationId:Secret)Creates new empty identification. Additional request data is optional.
\nReturns unique identificationId
\nThis must be called after auth and before each new identification
\nIf you get 415 Unsupported Media Type error make sure you are passing Content-Type: application/json
Rquired
\n","value":null},{"key":"Check2DLiveness","value":"{{Check2DLiveness}}","type":"text"},{"key":"IsEtalon","value":"{{IsEtalon}}","type":"text"}]},"url":"{{hostname}}/v3/media/:identification-id/face","description":"Scans uploaded image photo or video.
\nIs called after start api.
\nMax file size: 4MB
\nAccepted mime type: image/jpeg, image/jpg, image/png, image/gif
\n","urlObject":{"path":["v3","media",":identification-id","face"],"host":["{{hostname}}"],"query":[],"variable":[{"type":"string","value":"{{identification-id}}","key":"identification-id"}]}},"response":[{"id":"23e575e2-2ba0-4cf0-b0b7-7a076b13b9ec","name":"500 Internal Server Error","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","value":"{{File}}","type":"text"}]},"url":{"raw":"{{hostname}}/v3/media/:identification-id/face","host":["{{hostname}}"],"path":["v3","media",":identification-id","face"],"variable":[{"key":"identification-id","value":"{{identification-id}}"}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"type\": \"https://tools.ietf.org/html/rfc7235#section-3.1\",\n \"title\": \"Internal Server Error\",\n \"status\": 500,\n \"traceId\": \"0HLNB3PVRIUR0:00000002\"\n}"},{"id":"36d99668-4fab-4de2-a9d6-0be0d1861c24","name":"401 Unauthorized","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","value":"{{File}}","type":"text"}]},"url":{"raw":"{{hostname}}/v3/media/:identification-id/face","host":["{{hostname}}"],"path":["v3","media",":identification-id","face"],"variable":[{"key":"identification-id","value":"{{identification-id}}"}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"type\": \"https://tools.ietf.org/html/rfc7235#section-3.1\",\n \"title\": \"Unauthorized\",\n \"status\": 401,\n \"traceId\": \"0HLNB3PVRIUR0:00000002\"\n}"},{"id":"5a4c4b07-0f89-42d1-8009-df52c68e1e0b","name":"413 Request Entity Too Large","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","type":"text","value":"{{File}}"}]},"url":{"raw":"{{hostname}}/v3/media/:identification-id/face","host":["{{hostname}}"],"path":["v3","media",":identification-id","face"],"variable":[{"key":"identification-id","value":"{{identification-id}}"}]}},"status":"Request Entity Too Large","code":413,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":null},{"id":"7619036c-5678-47d6-997e-08098e224ff6","name":"200 OK","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","value":"{{File}}","type":"text"}]},"url":{"raw":"{{hostname}}/v3/media/:identification-id/face","host":["{{hostname}}"],"path":["v3","media",":identification-id","face"],"variable":[{"key":"identification-id","value":"{{identification-id}}"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"success\": false,\r\n \"error\": \"MULTIPLE_FACES\"\r\n}"},{"id":"b233242b-c915-418d-ac0a-5c9dd1ae8e89","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","value":"{{File}}","type":"text"}]},"url":{"raw":"{{hostname}}/v3/media/:identification-id/face","host":["{{hostname}}"],"path":["v3","media",":identification-id","face"],"variable":[{"key":"identification-id","value":""}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"\"Identification does not exist.\""}],"_postman_id":"f0565203-4738-49ff-9830-39588426b062"},{"name":"Upload document files","id":"e9e6c7df-a20c-4e31-8d5c-adcb899e8439","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"warning":"This is a duplicate header and will be overridden by the Content-Type header generated by Postman.","key":"Content-Type","value":"multipart/form-data"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"formdata","formdata":[{"key":"File","type":"file","description":"Required
\n","value":null},{"key":"DocumentType","type":"text","value":"{{DocumentType}}","description":"Required
\n"},{"key":"SideType","type":"text","value":"{{SideType}}","description":"Required
\n"},{"key":"DocumentCountry","type":"text","value":"{{DocumentCountry}}"}]},"url":"{{hostname}}/v3/media/:identification-id/document","description":"You need to call this method 2 times for each document side (FRONT and BACK)
\nAccepted mime type: image/jpeg, image/jpg, image/png
\nPassport cover side type: FRONT - is not mandatory
\nPassport page with photo side type: BACK
\nTo get document types which can by uploaded by user use endpoint
\nGET \"v3/application/document-types\"
\nPossible DocumentTypes:
\nID_CARD = 1,
PASSPORT = 2,
RESIDENCE_PERMIT = 3,
DRIVER_LICENSE = 4,
INTERNAL_PASSPORT = 5,
SOCIAL_ID = 6,
PROOF_OF_ADDRESS = 8
Verifies document scan results.
\nIs called in the end after face and document scan.
Completes identification and processes registries.
\nNo media files can be uploaded to current identification and verification can't be called.
This api shows the current request status and returns isCrossChecked status together with document data if available.
isCrossChecked means that identity verification is reviewed by human.
isPep means that person is found in Politically exposed person list.
Method returns:
\nemailAddressString2.firstNameString3.middleNameString4.lastNameString5.personalIdentityCodeString6.phoneNumberString7.dateOfBirthDatefirstNameString2.middleNameString3.lastNameString4.personalIdentityCodeString5.dateOfBirthDate6.nationalityString7.genderString8.addressString9.countryString10.documentNumberString11.documentTypeEnum12.dateOfIssueDate13.dateOfExpirationDateUNKNOWN;ID_CARD;PASSPORT;RESIDENCE_PERMIT;DRIVER_LICENSE;INTERNAL_PASSPORT;SOCIAL_ID;PROOF_OF_ADDRESSReturns media file URLs associated with the given identificationId.
\nURL for media files are valid for 1 minute.
\nURL for media files do not require any Authorization header.
Removes identification with all data.
\nAfter this identification data can't be recovered.
Returns array of document types which can be used together with /media/ endpoints
Returns webhook history data
\n","urlObject":{"path":["v3","webhooks","history",":year",":month",":day"],"host":["{{hostname}}"],"query":[],"variable":[{"type":"string","value":"2019","key":"year"},{"type":"string","value":"7","key":"month"},{"type":"string","value":"2","key":"day"}]}},"response":[{"id":"03be7792-f6f3-4fa2-b564-35301f8337d0","name":"500 Internal Server Error","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"url":"{{hostname}}/v3/application/settings"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"type\": \"https://tools.ietf.org/html/rfc7235#section-3.1\",\n \"title\": \"Internal Server Error\",\n \"status\": 500,\n \"traceId\": \"0HLNB3PVRIUR0:00000002\"\n}"},{"id":"77153acf-ce44-4892-a1a8-2f4ff00c67fa","name":"400 Bad Request","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"url":{"raw":"{{hostname}}/v3/webhooks/history/:year/:month/:day","host":["{{hostname}}"],"path":["v3","webhooks","history",":year",":month",":day"],"variable":[{"key":"year","value":"2019"},{"key":"month","value":"7"},{"key":"day","value":"2"}]}},"status":"Bad Request","code":400,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"\"Invalid date.\""},{"id":"af13e0db-269c-49c5-b287-b1e17b4ad6bd","name":"200 OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"url":"{{hostname}}/v3/application/settings"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\r\n \"date\": \"2019-07-02T00:00:00+00:00\",\r\n \"list\": [\r\n {\r\n \"identification\": \"41f16be109ac49219afc0065c74171b0\",\r\n \"id\": \"f1d03a8a-75a1-41c1-a412-5da87ddc2128\",\r\n \"created\": \"2019-07-02T19:30:12.8644764+00:00\",\r\n \"event\": \"PROCESSED\",\r\n \"sent\": \"2019-07-02T19:30:12.8644774+00:00\",\r\n \"retries\": 0,\r\n \"status\": \"OK\",\r\n \"url\": \"https://demo.ondato.com/receive-webhook/41f16be109ac49219afc0065c74171b0\",\r\n \"finished\": true\r\n },\r\n {\r\n \"identification\": \"41f16be109ac49219afc0065c74171b0\",\r\n \"id\": \"bf8b2922-4d89-4710-9010-ae17b8327950\",\r\n \"created\": \"2019-07-02T19:30:12.8644794+00:00\",\r\n \"event\": \"UPDATED\",\r\n \"sent\": \"2019-07-02T19:30:12.8644804+00:00\",\r\n \"retries\": 0,\r\n \"status\": \"OK\",\r\n \"url\": \"https://demo.ondato.com/receive-webhook/41f16be109ac49219afc0065c74171b0\",\r\n \"finished\": true\r\n },\r\n {\r\n \"identification\": \"41f16be109ac49219afc0065c74171b0\",\r\n \"id\": \"82f4f3bf-594d-4fb2-ad33-e3d476a8a3de\",\r\n \"created\": \"2019-07-02T19:30:12.8644818+00:00\",\r\n \"event\": \"CROSS_CHECKED\",\r\n \"sent\": \"2019-07-02T19:30:12.8644828+00:00\",\r\n \"retries\": 0,\r\n \"status\": \"OK\",\r\n \"url\": \"https://demo.ondato.com/receive-webhook/41f16be109ac49219afc0065c74171b0\",\r\n \"finished\": true\r\n }\r\n ]\r\n}"},{"id":"c7da8c3b-5de0-41c2-8267-03933d5f6884","name":"401 Unauthorized","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"url":"{{hostname}}/v3/application/settings"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":null,"cookie":[],"responseTime":null,"body":"{\n \"type\": \"https://tools.ietf.org/html/rfc7235#section-3.1\",\n \"title\": \"Unauthorized\",\n \"status\": 401,\n \"traceId\": \"0HLNB3PVRIUR0:00000002\"\n}"}],"_postman_id":"6261a6c2-0310-4593-843c-5c00f14a7dec"}],"id":"305b3742-2f54-4582-8d1d-e2eaf4353bac","description":"Changes from previous version:
\nEnum naming changed to all caps with snake case
Various models naming changes
New endpoint - identifications/verification
New endpoint - identifications/completion
New endpoint - application/document-types
New endpoint - application/settings