Core Libraries
You can integrate our Core Libraries in three steps:
Download and install the relevant Smile Identity library based on your server language.
Once installed, instantiate the Web API function to establish the connection to Smile Identity.
Call our submit_job function with the correct parameters required to complete a job
You can download the relevant Smile Identity library (smile-identity-core) based on your server language from the links below
Each library has a WebApi class. By instantiating an object from this class you can establish a connection with Smile Identity. All jobs are then submitted to this connection. You only have to do this once
require 'smile-identity-core'...connection = SmileIdentityCore::WebApi.new(partner_id, default_callback, api_key, sid_server)
let WebApi = require('smile-identity-core/src/web-api.js');const connection = new WebApi(partner_id, default_callback, api_key, sid_server);
WebApi connection = new WebApi(partner_id, callback_url, api_key, sid_server);//Ensure you are using the DECODED version of RSA public key
Call the constructor using the parameters below:
Parameter | Required | Data Type | Description |
partner_id | yes |
| You can find your partner ID in the api_access section of the documentation when logged into the developer portal. Please include the leading zero's. |
default_callback | yes |
| The Web API returns the immediate machine result of your query. If the machine result is not final and a human review needs to be performed, setting up a callback on your server will provide all results to your system. If you wish to have a custom URL for each job you can specify one in the submit_job function. |
api_key | yes |
| Your API is a base 64 encoded RSA key. You can find and generate your API key through the portal after signup. Please note: for the java implementation please use the decoded version of RSA public key. Copy as a string between the begin and end public key. |
sid_server | yes |
| An int that selects which server to use: 0 selects the sandbox server and 1 selects the production server. |
response = connection.submit_job(partner_params, images, id_info, options);
const response = connection.submit_job(partner_params, image_details, id_info, options);
String response = connection.submit_job(partnerParameters.get(), imageParameters.get(), idInfo.get(), options.get());
Build out the parameters(some of which are JSON objects) to complete a Smile Identity job request. In the case of Java, use our classes to build out the dictionaries.
The partner_params JSON is copied into every communication between the systems. This way you know exactly to what job and user each result is pertaining.
Parameter | Required | Data Type | Description |
user_id | yes | String | The user_id is a unique number identifying the user. It must be the same for every job submitted for that user. The user_id can be of any length. |
job_id | yes | String | The job_id is a unique number identifying a single job. Job numbers cannot be reused. The job_id can be of any length and can be any alphanumeric string. |
job_type | yes | String | There are four job types: Enroll with ID, Authenticate, Enroll without ID and Update Enrolled Image. |
some optional key | no | String | You may add more optional parameters as you require. You may choose any key, value attributes as long as they are of type String. |
Images is an array containing one or more entries. It contains the following keys:
Parameter | Required | Data Type | Description |
image_type_id | yes | Integer | It can be 0, 1, 2 or 3. The description of each Integer can be found in the table below. |
image | yes | String | For image types 0 and 1, this specifies the path to the image. For image types 2 and 3 it contains the base64 encoded image. |
Use the following chart to declare the image_type_id:
image_type_id | Indicates |
0 | selfie in png or jpg format |
1 | id card in png or jpg format |
2 | selfie in png or jpg format base64 encoded |
3 | id card in png or jpg format base64 encoded |
Best practices for images
Show your users an example of best practices for quality selfie images.
Keep your image file size between 75kb and 150kb, (ideal file size is 100kb)
Use a max resolution of 480X640
This JSON is required to check the validity of the ID number and to query the relevant Government ID Authority for the image associated with that ID number. This image is compared to the Selfie. This is only used in Job Type 1 and only when the ID number needs to be looked up. Set entered ="true"or"false"based on whether you have id info to populate.
Parameter | Required | Data Type | Description |
first_name | yes | String | required |
last_name | yes | String | required |
middle_name | yes | String | can be an empty string when not applicable |
country | yes | String | use the country code from the table below |
id_type | yes | String | use the id_type from the table below |
id_number | yes | String | must be in the correct format |
dob | no | String | must be in the format YYYY-MM-DD. DOB is only required for PASSPORT, VOTER_ID, DRIVERS_LICENSE, NATIONAL_ID, TIN, and CAC. |
entered | yes | String | needs to always be populated with a string (note not a boolean) of either "true" or "false" |
This JSON is required to specify more options for the call.
Parameter | Required | Data Type | Description |
optional_callback | required | String | It overrides the default_callback setup in the initialize call. Should you specify and optional callback, the Smile Identity server will send results to this callback and not the default callback |
return_job_status | required | Boolean | If true the library polls the job_status endpoint and returns the machine result. If false the library returns immediately. |
return_history | required | Boolean | If true the job_status endpoint returns the job history. Only useful when return_job_status is true. |
return_image_links | required | Boolean | If true the job_status endpoint returns the selfie and/or id image links. Only useful when return_job_status is true. |
Call our submit_job function using the parameters you built out in Step 3.
This will submit data to our systems using your parameters for that specific job.
The response will be in the form of a callback that you can setup or a polling mechanism that you can choose to receive the job status. You can set the callback url here(link).
Once the submit function is called it with the necessary parameters, it will then transmit the data to the Smile Identity server. It is mandatory to get your response either via the callback or the return_job_status.
Example Job_status response(when you’ve chosen to poll the job status endpoint):
Example Callback response(if you’ve added a default_callback or optional_callback parameter):
The response also contains actions performed. See Actions
