Overview
The Cloudcheck IDscan API service enables a reporting entity to automatically generate URLs for Cloudcheck IDscan.
You (as reporting entity) send basic request data to the Cloudcheck IDscan API via a secure URL, and a URL is returned for you to provide to your customer.
Initiate
| Path | /idscan/initiate/ | Method | POST |
|---|
Initiates an IDscan session. A URL will be returned by this API that you direct your customer to, so that they can complete the IDscan process.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details to be verified. |
Request
The details to be verified must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
Example
{
"reference": "IDscan reference 101",
"callback": "https://www.mycompany.com/id-complete",
"notificationUrl": "https://www.mycompany.com/id-notify?id=yourUniqueId",
"webhookUrl": "https://www.mycompany.com/idscan-webhook",
"verificationReference": "dac9d987-4007-4dd9-b5a6-cf547232836c"
}
We recommend that you provide a unique reference for this request.
A call will be made to the optional notificationUrl once the user completed the IDscan process, which can be used as a trigger in your code. This URL code should include a unique parameter that you can use to identify the request that it relates to. You must include the protocol at the start of the URL (https:// or http://).
A call will be made to the webhookUrl whenever the IDscan request changes. The results API can then be called to fetch the current information for this request. You must include the protocol at the start of the URL (https:// or http://). We call this webhook using the POST method, passing a json payload that looks like this:
{ "requestType": "IDSCAN", "eventType": "STATUS_CHANGE", "reference": "<reference>"}
where: <reference> is the reference or token used to fetch the results using an API call. Note that this webhook functionality may be extended in the future, e.g. different event types and fields may be added.
The optional callback is the URL that you want to user to be redirected to once they have finished the IDscan process. You must include the protocol at the start of the URL (https:// or http://).
Supply an optional verificationReference to link an existing verification to this IDscan request. A verification reference should be linked to a maximum of one IDscan request.
Response
The response JSON contains the outcome of the request.
Example
{ "result": "success", "link": "https://api.cloudcheck.co.nz/idscan/Dy0bG0ukM4d9bZKXP2l1HJEvfONPinV9jKRZKqFfjc3RQTQp/", "token": "Dy0bG0ukM4d9bZKXP2l1HJEvfONPinV9jKRZKqFfjc3RQTQp"}
If the call is successful you will receive a link that you redirect your end user to, in order for them to perform the IDscan process. A token is also returned, which is used by the other Cloudcheck IDscan APIs, to retrieve the results.
Once the IDscan check is completed, Cloudcheck will redirect the customer to the callback URL parameter provided in the request call above or to a generic completion page if no callback is provided.
This call will include the following URL parameters:
| Parameter | Required | Description |
|---|---|---|
token |
Yes | A token used to retrieve results of the IDscan request. |
idscanReference |
Yes | A unique reference used to identify the request. |
Results
| Path | /idscan/result/ | Method | GET |
|---|
Using the token returned in the IDscan Initiate API, the reporting entity can retrieve the results of an IDscan request. Note that details entered by the customer can be retrieved for 7 days following a successful request. After this time, Cloudcheck disposes of all personal data, but the general process complete/pass/fail details remain available.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
token |
true | The token returned in the response to the IDscan Initiate API. |
Response
Example
{ "idscan": { "reference": "IDscan reference 101", "idscanReference": "zab9d987-4007-4dd9-b5a6-cf547232836c", "token": "fu3FlX7jrCRWvR1Gy0BCFmb6iEYeaRoYlKgFVsWEQxg2HnzS", "ipAddresses": [ "10.1.10.254" ], "device": { "type": "Other", "os": "Windows 10", "browser": "Edge 103" }, "createdDate": "2022-05-06 12:02", "completed": false, "url": "...", "completedDate": "2022-05-07 16:12", "status": "PASS", "matchPercentage": 80, "reviewDecision": "ACCEPT", "reviewNotes": "This looks ok, he's wearing glasses and changed his hair style", "reviewedBy": "API", "whenReviewed": "2013-05-06 15:14", "cleansed": true, "cleansedStatus": "Images have been removed in accordance with the Data Retention Policy", "images": [ { "type": "Selfie Photo", "stepName": "Selfie Photo", "role": "SelfiePhoto", "url": "https://supermodel-verifidentity-dev.s3.amazonaws.com/resized/idscan/6/64/images/IDDocument-WhiteImage/afe101ac-d238-4913-b0f2-f16870ab86d2-0-600-0-600.png?k=280565adf1", "whenCaptured": "2013-05-06 12:04" }, ... ], "recognizedDocuments": [ { "number": "...", "documentType": "NZ_DRIVER_LICENCE", "imageRecognized": "Photo Identification", "imageUrl": "...", "familyName": "...", "givenName": "...", "issueCountry": "", "middleName": "", "dateOfBirth": "yyyy-MM-dd", "version": "394", "mrzResult": "...", "dateExpires": "yyyy-MM-dd", "dateIssued": "yyyy-MM-dd", "gender": "M or F" }, ... ], "resultBreakdown": { "highLevelResult": "Passed", "documentAssessment": { "Document Back Side Type Check": "Pass", "Document Support": "Pass", .. }, "liveness": { "Accumulative Liveness Result": "Pass", ... } }, "processedDocuments": [ { "documentCategory": "Driving License", "documentSide": "Front", "documentName": "Australia - Driving License - Front - 2014", "issuingCountryCode": "AUS", "issuingCountryName": "Australia", "issuingStateName": "New South Wales", "isValidated": "true", "digitalTamperingValidator": "Passed", "highLevelResult": "Passed", "faceMatchConfidenceScore": "0.789739668369293", "extractedFields": { "CardNumber": "2 000 007 007", "ExpiryDate": "2014-10-03", ... } } ] }}
The status field can have the following values:
| Status | Description |
|---|---|
| PENDING | The end user has not completed the IDscan process. |
| PASS | We successfully verified the user in IDscan. |
| MATCH_REVIEW | The process was completed by the end user, and the result was a Match, but there are potential issues for you to review. |
| NEEDS_REVIEW | The user successfully completed the IDscan process, however there are some findings in the result that need your review. |
| FAIL | We failed to verify the user in IDscan. |
| ABANDONED | The end user did not complete the IDscan process before the link expired. |
| CANCELLED | The end user cancelled the IDscan process. |
Result PDF
| Path | /idscan/pdf/ | Method | GET |
|---|
Once the IDscan process is complete, you can optionally download a Cloudcheck generated PDF of the results.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
token |
true | The token returned in the response to the IDscan Initiate API. |
Response
This method will either return a PDF file or a JSON object with an error message. You should check the response Content-Type to determine which you have received.
Review
| Path | /idscan/review/ | Method | POST |
|---|
Performs a review on an IDscan request.
When sending a review request to the IDscan API, you must include the following parameters as part of the call. Please note all these parameters must be included as form data, and not set into the POST body, which is not used. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details to be verified. |
Request
The decision and/or notes must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
The idscanToken and reviewDecision are mandatory.
Example
{ "idscanToken": "Dy0bG0ukM4d1bZK1P2l1HJEvfONPinV9jKRZKqFfjc3RQTQp", "reviewDecision": "ACCEPT", "reviewNotes": "It looks like the glasses and moustache caused the review."}
Response
The response JSON contains the idscanToken as well as a result element indicating whether the operation was successful.
Example
{ "idscan": { "idscanToken": "cab9d287-4007-4dd9-b5a6-cf547232836c", "result": "success" }}