Request a Check

{checks} API is used to request a check for one or multiple report types.

There are multiple scenarios or combinations that can be used based on the process requirement.

Use Cases

Document verification (using only FRONT, or FRONT and BACK sources)
Address verification
AML watchlist verification
Custom watchlist verification
Document verification + Face matching
Document verification + Face matchhing + Address Verification
Document verification + Face matchhing + Address Verification + AML watchlist

📘
About checks
Checks are excuted in asynchronous mode. It means an inmediate "in_progress" response will be prompted by the API.
Client application could implement a query status pulling periodically until the returned check status is "complete"; or implement a webhook for receiving check status updates.
Generally, a check is completed within the first 2~3 minutes (it depends on the proofs size and type/amount of reports requested on the same transaction)

Check Request

KYC Check

Document & Selfie Check example

Auth-Service API

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

KYC API

curl --location --request POST '{{baseUrl}}/kyc/checks' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--header 'X-Callback-URL: {{callbackUrl}}' \
--data-raw '{
    "entityReference": "361",
    "requiredReports": [
        {
            "reportType": "document",
            "sources": [
            		{
                			"sourceId":203,
                			"sourceType" : "DOCUMENT"
            		},
            		{
                			"sourceId":204,
                			"sourceType" : "DOCUMENT"
            		},
                {
                			"sourceId":104,
                			"sourceType" : "FACE"
            		}
            					]
        }
    ],
    "userConsent": true
}'

{
    "creationDate": "2022-06-22T20:37:43.129Z",
    "checkId": 261,
    "entityId": "361",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ]
        }
    ],
    "status": "in_progress",
    "result": null,
    "resultDetails": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ],
            "reportId": 261,
            "subResult": null
        }
    ]
}

curl --location --request GET '{{baseUrl}}/checks/{{checkId}}/' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \

{
    "creationDate": "2022-06-22T20:37:43.129Z",
    "checkId": 261,
    "entityId": "361",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ]
        }
    ],
    "status": "complete",
    "result": "passed",
    "resultDetails": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ],
            "reportId": 261,
            "subResult": "passed"
        }
    ]
}

Check Callback

curl --location --request PUT '{{callbackUrl}}' \
--header 'x-timestamp: 2022-08-26T19:01:07.609285Z' \
--header 'x-signature: vUddkOuHWdue42gWQxPNO6ZN8h1WmfarhBK4OaUHsYlsPvOzSal08IT2zMJsmbKaOpneHEHE9Lm70d/XpIWG5VglSqA2TX2orpt/qpaIn59yzfUEoEdN8nAVVfspbLadW5VHkDlavhyuWFVPlnridWdl9rjsxg6B44to7NurpFVn4wSSCHbtBqL8IePld3N2AUg/N/7tI6Dk4nWxsB835lbXhGSztXCNozlqOBE5KQslsIWYy0ciZZ8YqHpmXPisy6v0nKA+Ke7QModCRtXtad8WhR/oz+G7cHPtHwZRGF4SCveB2lyD85WyGzCfX9TLhiAs80T51Zj033OQRr0K9Q==' \
--header 'x-saltlength: 20'\
--header 'content-type: application/json' \
--header 'content-length: 2948' \

--data-raw '{
    "creationDate": "2022-06-22T20:37:43.129Z",
    "checkId": 261,
    "entityId": "361",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ]
        }
    ],
    "status": "complete",
    "result": "passed",
    "resultDetails": [
        {
            "reportType": "document_ocr",
            "sources": [
                {
                    "sourceId": 203,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 204,
                    "sourceType": "DOCUMENT"
                },
                {
                    "sourceId": 104,
                    "sourceType": "FACE"
                }
            ],
            "reportId": 261,
            "subResult": "passed"
        }
    ]
}'

Address proof Check example

Auth-Service API

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

KYC API

curl --location --request POST '{{baseUrl}}/kyc/checks' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityReference": "1000",
    "requiredReports": [
        {
            "reportType": "address",
            "sources": [{
                "sourceId":3,
                "sourceType" : "DOCUMENT"
            }
            ]
        }
    ],
    "userConsent": true
}'

{
    "creationDate": "2021-12-21T16:09:00.4Z",
    "checkId": 369,
    "entityId": "1000",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "address",
            "sources": [
                {
                    "sourceId": 3,
                    "sourceType": "DOCUMENT"
                }
            ]
        }
    ],
    "status": "in_progress",
    "result": null,
    "resultDetails": [
        {
            "reportType": "address",
            "sources": [
                {
                    "sourceId": 3,
                    "sourceType": "DOCUMENT"
                }
            ],
            "reportId": 375,
            "subResult": null
        }
    ]
}

curl --location --request GET '{{baseUrl}}/checks/{{checkId}}/' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \

{
    "creationDate": "2021-12-21T16:09:00.4Z",
    "checkId": 369,
    "entityId": "1000",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "address",
            "sources": [
                {
                    "sourceId": 3,
                    "sourceType": "DOCUMENT"
                }
            ]
        }
    ],
    "status": "complete",
    "result": "passed",
    "resultDetails": [
        {
            "reportType": "address",
            "sources": [
                {
                    "sourceId": 3,
                    "sourceType": "DOCUMENT"
                }
            ],
            "reportId": 375,
            "subResult": "passed"
        }
    ]
}

AML Check example

Auth-Service API

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

KYC API

curl --location --request POST '{{baseUrl}}/kyc/checks' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityReference": "1000",
    "requiredReports": [
        {
            "reportType": "aml_watchlist",
        }
    ],
    "userConsent": true
}'

{
    "creationDate": "2021-12-21T12:57:52.368Z",
    "checkId": 370,
    "entityId": "1000",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "whatchlist_aml",
            "sources": []
        }
    ],
    "status": "in_progress",
    "result": null,
    "resultDetails": [
        {
            "reportType": "whatchlist_aml",
            "sources": [],
            "reportId": 376,
            "subResult": null
        }
    ]
}

curl --location --request GET '{{baseUrl}}/checks/{{checkId}}/' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \

{
    "creationDate": "2021-12-21T12:57:52.368Z",
    "checkId": 370,
    "entityId": "1000",
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "whatchlist_aml",
            "sources": []
        }
    ],
    "status": "complete",
    "result": "passed",
    "resultDetails": [
        {
            "reportType": "whatchlist_aml",
            "sources": [],
            "reportId": 376,
            "subResult": "passed"
        }
    ]
}

Custom Watchlist Check Example

Custom Watchlist feature allows clients to manage their own lists and perform checks against those lists.

Custom list structure

The lists are managed from the the Business Portal.

Field	Mandatory	Example
listName	true	BLACKLIST
reason	true	Fraud Risk
firstName1	true	Juan
firstName2	false
firstName3	false
lastName1	true	Perez
lastName2	false
lastName3	false
gender	true	M
idType	false
idNumber	false
dateOfBirth	true	1983-10-07
nationality	true	AR
entityType	true	NATURAL

Auth-Service API

curl --location --request POST 'https://{{baseUrl}}/auth-service/1.0/protocol/openid-connect/token' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

{
    "access_token": "{{access_token}}",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "{{refresh_token}}",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "{{session_state}}",
    "scope": "profile email"
}

#### KYC API

KYC API - Profile check against custom lists

curl --location --request POST '{{baseUrl}}/kyc/checks' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "entityReference": null,
    "requiredReports": [
        {
            "reportType": "watchlist_custom",
            "filterFields": {
                "firstName1": "J", 
                "firstName2":"",  
                "firstName3":"",   
                "lastName1":"Perez",  
                "lastName2":"", 
                "lastName3":"", 
                "gender":"M",    
                "idNumber":"", 
                "dateOfBirth":"1983-10-07",   
                "nationality":"AR", 
                "entityType":"NATURAL" 
                } 
        } 
    ],   
    "userConsent": true
}'

{
    "creationDate": "2022-10-28T14:41:52.037Z",
    "checkId": 344,
    "entityId": null,
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "watchlist_custom",
            "sources": [],
            "filterFields": {
                "firstName1": "J",
                "firstName2": "",
                "firstName3": "",
                "lastName1": "Perez",
                "lastName2": "",
                "lastName3": "",
                "gender": "M",
                "idNumber": "",
                "idType": "NATIONALID",
                "dateOfBirth": "1983-10-07",
                "nationality": "AR",
                "entityType": "NATURAL"
            }
        }
    ],
    "status": "complete",
    "result": "declined",
    "resultDetails": [
        {
            "reportType": "watchlist_custom",
            "sources": [],
            "reportId": 344,
            "filterFields": {
                "firstName1": "J",
                "firstName2": "",
                "firstName3": "",
                "lastName1": "Perez",
                "lastName2": "",
                "lastName3": "",
                "gender": "M",
                "idNumber": "",
                "idType": "NATIONALID",
                "dateOfBirth": "1983-10-07",
                "nationality": "AR",
                "entityType": "NATURAL"
            },
            "subResult": "declined"
        }
    ]
}

{
    "creationDate": "2022-11-09T12:21:40.236Z",
    "checkId": 461,
    "entityId": null,
    "userConsent": true,
    "requiredReports": [
        {
            "reportType": "watchlist_custom",
            "sources": [],
            "filterFields": {
                "firstName1": "Pedro",
                "firstName2": "",
                "firstName3": "",
                "lastName1": "Marmol",
                "lastName2": "",
                "lastName3": "",
                "gender": "M",
                "idNumber": "",
                "idType": null,
                "dateOfBirth": "1980-09-10",
                "nationality": "AR",
                "entityType": "NATURAL"
            }
        }
    ],
    "status": "complete",
    "result": "passed",
    "resultDetails": [
        {
            "reportType": "watchlist_custom",
            "sources": [],
            "reportId": 461,
            "filterFields": {
                "firstName1": "Pedro",
                "firstName2": "",
                "firstName3": "",
                "lastName1": "Marmol",
                "lastName2": "",
                "lastName3": "",
                "gender": "M",
                "idNumber": "",
                "idType": null,
                "dateOfBirth": "1980-09-10",
                "nationality": "AR",
                "entityType": "NATURAL"
            },
            "subResult": "passed"
        }
    ]
}

The check returns a synchronous response ("status": "complete") for custom (local) lists verifications.

If one or more records matches with the filter criteria (defined into the "filterFields" object), the check will prompt a "declined" result.

The report (reportId) can be retrieved toknow what are the records from the lists that matched with the check criteria,

curl --location --request GET '{{baseUrl}}/checks/{{checkId}}/reports/{reportId}' \
--header 'apikey: {{apikey}}' \
--header 'X-User-Bearer: Bearer {{access_token}}' \

{
    "creationDate": "2022-11-08T18:18:18.502Z",
    "checkId": 344,
    "entityId": null,
    "declinedReason": "AML screening failed. User found in custom list.",
    "declinedCodes": [
        "165"
    ],
    "resultSumary": {
        "reportType": "watchlist_custom",
        "sources": [],
        "reportId": 344,
        "filterFields": {
            "firstName1": "J",
            "firstName2": "",
            "firstName3": "",
            "lastName1": "Perez",
            "lastName2": "",
            "lastName3": "",
            "gender": "M",
            "idNumber": "",
            "idType": null,
            "dateOfBirth": "1983-10-07",
            "nationality": "AR",
            "entityType": "NATURAL"
        },
        "subResult": "declined"
    },
    "verificationData": {
        "hits": {
            "totalCount": 2,
            "matches": [
                {
                    "id": 1,
                    "creationDate": "2022-10-21",
                    "modificationDate": "2022-10-21",
                    "listName": "BLACKLIST",
                    "firstName1": "Juanma",
                    "firstName2": null,
                    "firstName3": null,
                    "lastName1": "Perez",
                    "lastName2": null,
                    "lastName3": null,
                    "gender": "M",
                    "idType": null,
                    "idNumber": null,
                    "dateOfBirth": "1983-10-07",
                    "nationality": "AR",
                    "entityType": "NATURAL",
                    "reason": "Debt not paid"
                },
                {
                    "id": 2,
                    "creationDate": "2022-10-27",
                    "modificationDate": "2022-10-27",
                    "listName": "RISK",
                    "firstName1": "Juan",
                    "firstName2": null,
                    "firstName3": null,
                    "lastName1": "Perez",
                    "lastName2": null,
                    "lastName3": null,
                    "gender": "M",
                    "idType": null,
                    "idNumber": null,
                    "dateOfBirth": "1983-10-07",
                    "nationality": "AR",
                    "entityType": "NATURAL",
                    "reason": "Risk scoring high"
                }
            ]
        }
    },
    "additionalData": null,
    "verificationResult": {
        "background_checks": 0
    }
}

{
    "creationDate": "2022-11-09T12:21:40.236Z",
    "checkId": 461,
    "entityId": null,
    "declinedReason": null,
    "declinedCodes": [],
    "resultSumary": {
        "reportType": "watchlist_custom",
        "sources": [],
        "reportId": 461,
        "filterFields": {
            "firstName1": "Pedro",
            "firstName2": "",
            "firstName3": "",
            "lastName1": "Marmol",
            "lastName2": "",
            "lastName3": "",
            "gender": "M",
            "idNumber": "",
            "idType": null,
            "dateOfBirth": "1980-09-10",
            "nationality": "AR",
            "entityType": "NATURAL"
        },
        "subResult": "passed"
    },
    "verificationData": {
        "hits": {
            "totalCount": 0,
            "matches": null
        }
    },
    "additionalData": null,
    "verificationResult": {
        "background_checks": 1
    }
}

Use Cases

📘About checks

Check Request

Document & Selfie Check example

Auth-Service API

KYC API

Check Callback

Address proof Check example

Auth-Service API

KYC API

AML Check example

Auth-Service API

KYC API

Custom Watchlist Check Example

Custom list structure

Auth-Service API

KYC API - Profile check against custom lists

📘
About checks