Enhanced KYC
NOTE
Only available to licensed organisations.
Please contact [email protected] if you need access to this product.
The Enhanced KYC API allows you to query the Identity Information for an individual using their ID number from one of our supported ID Types. This API will return the personal information of the individual found in the database of the ID authority.
This API is available as both an Asynchronous API (recommended) which guarantees an eventual response regardless of ID authority availability and as a Synchronous API to be used in real time environments such as mobile applications which does not guarantee a response in the case that an ID authority is unavailable. For high volume applications the Asynchronous API is required. If you are using the Asynchronous API you must have a callback endpoint in your request where the response will be delivered. The urls for the endpoints are:
The size of the payload sent to your callback varies based on the size of image returned by the ID authority. We recommend your callback should accept payloads up to 1.5MB in size.
Asynchronous:
Environment | URL |
---|---|
Sandbox: | https://testapi.smileidentity.com/v1/async_id_verification |
Production: | https://api.smileidentity.com/v1/async_id_verification |
Synchronous:
Environment | URL |
---|---|
Sandbox: | https://testapi.smileidentity.com/v1/id_verification |
Production: | https://api.smileidentity.com/v1/id_verification |
The Enhanced KYC API has the following input parameters which should be contained in a JSON body object submitted to the endpoint
Request Type: Post
Name | Type | Required | Description |
partner_id | string | Yes | |
source_sdk | string | Yes | The integration option you are using. For rest api send the value as "rest_api" |
source_sdk_version | string | Yes | The version of the integration option you are using |
signature | string | Yes | The outgoing signature to authenticate the request from you to Smile ID |
timestamp | string | Yes | The timestamp used to calculate the signature in ISO date/time format |
country | string | Yes | |
id_type | string | Yes | |
id_number | string | Yes | |
callback_url | string | Yes for Async | Your callback url, results of jobs will be sent to the specified url. You can read more about callback urls here |
first_name | string | First Name | |
middle_name | string | No | Middle Name |
last_name | string | Last Name | |
dob | string | Date of Birth | |
phone_number | string | Phone Number | |
partner_params | object | Yes | A JSON object containing the partner parameters below as well as any additional key value pairs you wish to include for tracking which will be returned in the response |
{job_type | string | Yes | The type of job you want to perform. This will be set to 5. |
job_id | string | Yes | A value generated by you, so you can track jobs on your end. This value must be unique, can be any string and can follow your identifier convention |
user_id} | string | Yes | A value generated by you, so you can track users on your end. This value must be unique, can be any string and can follow your identifier convention. |
{
"source_sdk": "rest_api",
"source_sdk_version": "1.0.0",
"partner_id": "023",
"timestamp": "2021-08-12T17:57:00.614879",
"signature": "...",
"country": "NG",
"id_type": "DRIVERS_LICENSE",
"id_number": "ABC000000000",
"callback_url": "example.webhook.com"
"first_name": "Leo",
"middle_name": "Doe",
"last_name": "Joe",
"phone_number": "1234567890",
"dob": "2000-09-20",
"gender": "M",
"partner_params": {
"job_id": "3ba0e15e-1a56-4799-a94d-b0e084f50256",
"user_id": "4cb0f26-2b567-5800-b05e-c0f095g6036"
}
}
The Enhanced KYC API returns a set of top level values as well as a detailed set of actions that can be used for a more granular evaluation of the individual fields.
Name | Type | Description | Return Values |
SmileJobID | string | The Smile internal reference number for the job. Please include this when contacting support on a job. | |
PartnerParams.job_id | String | A unique reference defined by you to keep track of the job | |
PartnerParams.job_type | String | The type of job you performed | 5 |
PartnerParams.user_id | String | A unique reference defined by you to keep track of the user | |
ResultText | string | Textual value of the job outcome. Human readable value for the result. | |
ResultCode | string | Numeric value of the job outcome. | |
Actions | object | A JSON object containing the details of the individual field comparisons | |
Verify_ID_Number | string | The result of looking up the ID number in the ID authority database is returned in this key | "Verified" "Not Verified" "Not Done" "Issuer Unavailable" |
Return_Personal_Info | string | This key confirms if we sent the personal information retrieved from the ID authority sent to you | "Returned" "Not Returned" "Not Applicable" |
Country | string | Country where the ID was issued as supplied by you | |
IDType | string | ID type as supplied by you | |
IDNumber | string | ID number you ran a query for | |
ExpirationDate | string | Top level key - expiration date as retrieved from the ID authority database | |
FullName | string | Top level key - full name as retrieved from the ID authority database | |
DOB | string | Top level key - date of birth as retrieved from the ID authority database | |
PhoneNumber | string | Top level key - phone number as retrieved from the ID authority database | |
PhoneNumber2 | string | Second phone number of ID owner (when available) | |
Document | string | Photo of ID card on file in the ID authority database (when applicable) | |
Gender | string | Gender of ID owner | |
Address | string | Address of ID owner NOTE: this might not be the current address of the ID owner | |
Photo | string | Top level key - photo as retrieved from the ID authority database in base64 image | |
signature | string | The outgoing signature, you can use this to verify that the response is from Smile ID | |
timestamp | string | The outgoing timestamp in ISO date/time format, use this to calculate the outgoing Signature | |
Depending on the endpoint you hit (asynchronous or synchronous) the immediate response you get is different.
For the Asynchronous Endpoint
{
"success": true
}
For the Synchronous Endpoint (this is the same response sent to the callback of the asynchronous endpoint)
{
"JSONVersion":"1.0.0",
"SmileJobID":"0000000001",
"PartnerParams":{
"user_id":"T6yzdOezucdsPrY0QG9LYNDGOrC",
"job_id":"FS1kd1dd15JUpd87gTBDapvFxv0",
"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":"DRIVERS_LICENSE",
"IDNumber":"ABC000000000",
"ExpirationDate":"2021-08-15",
"FullName":"Leo Doe Joe",
"DOB":"2000-09-20",
"Photo":<BASE64 STRING>,
"signature": "...",
"timestamp":"2021-08-12T17:57:00.614879"
}
The Enhanced KYC product returns the personal information of users stored in the ID authority database. Each ID authority stores these personal information with different keys causing discrepancies in names of keys containing similar information. For the identity lookup response, we have filtered and standardised the personal information returned to top-level keys to simplify the use of our JSON response across all our supported ID types.
Result codes details what the current (or final) result of a job is. Result Codes for all jobs fall into one of three categories:
- 1.Approved (or Pass) This means that all applicable Actions passed and the overall job was approved.
- 2.Provisionally Approved This means that the job is awaiting a human review, or that a human review was inconclusive or that part of a job passed but another part was unable to be completed. You can treat these jobs as Approved or you handle them based on the Result Code. Please note a
Pure Provisional
result is a provisionally approved job, but one in which the image comparison Action was provisionally approved but the identity validation Action failed or could not return data. Also note, aPending Approval
result is a custom Strict setting where the user cannot progress in the system without a human review being completed on the Pending job. - 3.Rejected (or Fail) This means that one or more of the applicable Actions for job failed, and thus, the overall job was rejected according to Smile ID standards.
This means no further processing is possible on the job. General failures occur when a job could not be submitted due to a logical/technical issue. These jobs do not show up in the portal and do not have a Smile Job ID.
Code | Text | Description | Category |
---|---|---|---|
0001 | Data Invalid | | Rejected |
0903 | Zip Corrupt | The uploaded Zip file is corrupted. | Rejected |
2405 | Error - "You are not authorized to do that" * | An invalid signature was used to sign the request. | - |
2314 | Error - No Zip File Received | No Zip files was uploaded. | - |
2203 | Error - Invalid JSON | The info.json file in the Zip is not properly structured. Ensure all keys are present and properly named. | - |
2213 | Error - A required parameter is missing | Not all the required keys were submitted in the info.json or request payload. Please check request values for this product. | - |
2204 | Error - A parameter is of the wrong data type | - | |
2205 | Error - You are not authorized to do that. * | An invalid signature was used to sign the request. | - |
2220 | You have not completed your KYC. | - | |
2212 | Error - Invalid job type ** | An invalid value was inputted in the job_type key. Change the value to 5. | - |
Code | Text | Description | Category |
---|---|---|---|
1012 | Valid ID | | Approved |
1013 | Invalid ID | The ID info was not found in the ID authority database. | Rejected |
1014 | Error - Unsupported ID number format | - | |
1015 | Error - Queried Database Unavailable | The ID authority is unavailable. | - |
1016 | Error - Need to Activate Product | You do not have access to the ID Type. Please contact support for more information. | - |
2211 | (Mobile SDK Only) ID Validation Failed | | Rejected |
2212 | (Mobile SDK Only) Error - HTTP Request Failed | | - |
Last modified 2mo ago