Real ID numbers can only be used on the production environment. To gain access to the production environment please complete the steps outlined in the section Submit Your Company KYC. Then follow the simple steps outlined in the section Change your API Keys.
Below we also provide ID test data that allows you to run an unlimited number of tests. The test data will have the same JSON structure that a paid call in production would return, including the FullData
section of the response.
The test ID data is flexible. The ID data format matches each id_type’s true corresponding format, but the final digit determines what response is received.
Test data is only available for use in the Sandbox. If test data is used in Production an error will be returned with ResultCode 1014 and the ResultText as "Unsupported ID number format".
Country | Country Code | id_type | Format |
Ghana | GH | DRIVERS_LICENSE | B0000000 |
Ghana | GH | PASSPORT | G0000000 |
Ghana | GH | SSNIT | C000000000000 |
Ghana | GH | VOTER_ID | 0000000000 |
Kenya | KE | ALIEN_CARD | 000000 |
Kenya | KE | NATIONAL_ID | 00000000 |
Kenya | KE | PASSPORT | A00000000 |
Nigeria | NG | BVN | 00000000000 |
Nigeria | NG | NIN | 00000000000 |
Nigeria | NG | NIN_SLIP | 00000000000 |
Nigeria | NG | DRIVERS_LICENSE | ABC000000000 |
Nigeria | NG | VOTER_ID | 0000000000000000000 |
Nigeria | NG | NATIONAL_ID | 0000000000 |
Nigeria | NG | TIN | 00000000-0000 |
Nigeria | NG | CAC | 0000000 |
South Africa | ZA | NATIONAL_ID | 0000000000000 |
South Africa | ZA | NATIONAL_ID_NO_PHOTO | 0000000000000 |
To test various outcomes, change the final digit of the id_number to attain the desired outcome.
There are four Simulated Results to test in your integration:
Final Digit | Simulated Result | Result Code |
0 | Success w/ meta-data return | 1012 |
1 | Failure, no record found | 1013 |
2 | Invalid ID number format | 1014 |
3 | Database unavailable/unknown network issue | 1015 |
4 | Success w/ custom meta-data return | 1012 |
Most of the options using test data will return the same meta data and image every time you access them. In order to test your business logic built around the evaluation of the data we return, or testing our facial recognition outcomes, you will need to specify what is being returned by the api call. To use this feature, first run a test where the final digit of the test id number is 0 in order to learn which values you would like to replace. Check the FullData
section of the response to see which keys correspond to the values you would like to replace. Then send another request where the final digit of the ID number is 4, and in the partner_params
section of the request, add those keys with the values you would like to be returned.
Example request:
{"sec_key": "dv1hmt2IpnhFn5jy|zgkod8hk+lZh","partner_params": {"user_id": "1","job_id": "1","job_type": 5},"id_number": "00000000000","country": "NG","id_type": "BVN","timestamp": 1579641236,"partner_id": "002"}
Example response:
{"JSONVersion": "1.0.0","SmileJobID": "0000000001","PartnerParams": {"user_id": "887ceeea-e9fd-4f96-aa58-d4b12d0b5f98","job_id": "985c594e-7e67-4f2e-a6e0-3be127dbb6a0","job_type": 5},"ResultType": "ID Verification","ResultText": "ID Number Validated","ResultCode": "1012","IsFinalResult": "true","Actions": {"Verify_ID_Number": "Verified","Return_Personal_Info": "Returned"},"Country": "NG","IDType": "BVN","IDNumber": "00000000000","ExpirationDate": "Not Available","FullName": "Doe Joe Leo","DOB": "2000-01-20","Photo": <base 64 string>,"PhoneNumber": "12345678900","Gender": "Male","Address": "10, Workbox, Ojora Close, Victoria Island, Lagos, Victoria Island, Lagos State","FullData": {"watchListed": "No","enrollmentBranch": "...","stateOfOrigin": "Lagos State","stateOfResidence": "Lagos State","Gender": "Male","title": " ","nin": "00000000000","nameOnCard": "Doe Joe Leo","LevelOfAccount": "Level 2 - Medium Level Accounts","registrationDate": "","email": "...","DateOfBirth": "20-January-2000","FirstName": "Doe","PhoneNumber2": "","PhoneNumber1": "12345678900","MiddleName": "Joe","ImageBase64": <base 64 string>,"lgaOfResidence": "Victoria Island","nationality": "Nigeria","lgaOfOrigin": "...","residentialAddress": "10, Workbox, Ojora Close, Victoria Island, Lagos","enrollmentBank": "000","BVN": "00000000000","LastName": "Leo","maritalStatus": "Single","success": true},"Source": "ID API","sec_key": "pgVQGn0bs9lcZXK|bO+1x4gG8XKLy","timestamp": 1593727494844}
Find the relevant keys for the values you want to change. In this example I want to specify the name and photo to be returned.
Example request:
{"sec_key": "dv1hmt2IpnhFn5jyzg|kod8hk+lZhxe","partner_params": {"user_id": "887ceeea-e9fd-4f96-aa58-d4b12d0b5f98","job_id": "985c594e-7e67-4f2e-a6e0-3be127dbb6a0","job_type": 5,"FirstName": "SMILE","MiddleName": "IDENTITY","LastName": "EMPLOYEE","ImageBase64": <Your base64 image>},"id_number": "00000000004","country": "NG","id_type": "BVN","timestamp": 1579641236,"partner_id": "002"}
Example response:
{"JSONVersion": "1.0.0","SmileJobID": "0000000001","PartnerParams": {"user_id": "1","job_id": "1","job_type": 5,"FirstName": "SMILE","MiddleName": "IDENTITY","LastName": "EMPLOYEE","ImageBase64": <Your base64 image>},"ResultType": "ID Verification","ResultText": "ID Number Validated","ResultCode": "1012","IsFinalResult": "true","Actions": {"Verify_ID_Number": "Verified","Return_Personal_Info": "Returned"},"Country": "NG","IDType": "BVN","IDNumber": "00000000004","ExpirationDate": "Not Available","FullName": "SMILE IDENTITY EMPLOYEE","DOB": "2000-01-20","Photo": <Your base64 image>,"PhoneNumber": "12345678900","Gender": "Male","Address": "10, Workbox, Ojora Close, Victoria Island, Lagos, Victoria Island, Lagos State","FullData": {"watchListed": "No","enrollmentBranch": "...","stateOfOrigin": "Lagos State","stateOfResidence": "Lagos State","Gender": "Male","title": " ","nin": "00000000000","nameOnCard": "Doe Joe Leo","LevelOfAccount": "Level 2 - Medium Level Accounts","registrationDate": "","email": "...","DateOfBirth": "20-January-2000","FirstName": "SMILE","PhoneNumber2": "","PhoneNumber1": "12345678900","MiddleName": "IDENTITY","ImageBase64": <Your base64 image>,"lgaOfResidence": "Victoria Island","nationality": "Nigeria","lgaOfOrigin": "...","residentialAddress": "10, Workbox, Ojora Close, Victoria Island, Lagos","enrollmentBank": "000","BVN": "00000000000","LastName": "EMPLOYEE","maritalStatus": "Single","success": true},"Source": "ID API","sec_key": "ubIDmC1SvfJ+Tlx1X|3FPYsqCOHh","timestamp": 1593729211112}
Note: not all possible outcomes are included in these Simulated Results — For example, using an ID from a country we don’t support would result in an "Unsupported ID Type and/or Country” result. A full list of possible ID API result codes can be found below and in the Result Codes section.
ID Validation Result Codes:
Code | Description |
1012 | Success |
1013 | Invalid ID |
1014 | Unsupported ID Type, Country, or ID Number Format |
1015 | Error - Queried Database Unavailable |
1016 | Product Activation Required |