Usage

Get Started with Web API

You can integrate Web API in four steps:

  1. Download and install the relevant Smile Identity library based on your server language.

  2. Once installed, instantiate the Web API function to establish the connection to Smile Identity.

  3. Call our submit_job function with the correct parameters required to complete a job

Let’s go through these steps in detail:

1. Download

You can download the relevant Smile Identity library (smile-identity-core) based on your server language from the links below

Language

Library Name

Download Link

Examples

Ruby

smile-identity-core

View on Rubygems

Ruby

Javascript

smile-identity-core

View on NPM

Javascript

Java

smile-identity-core

View on Maven

In Progress

PHP

smile-identity-core

Github

In Progress

Python

smile-identity-core

In Progress

In Progress

2. Instantiate

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

Ruby
Javascript
Python
Java
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

string

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

string

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

string

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

integer

An int that selects which server to use: 0 selects the sandbox server and 1 selects the production server.

3. Submit

Ruby
Javascript
Python
Java
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.

partner_params[required]

  • 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[required]

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

id_info[required]

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"

options[required] 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.

  1. 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).

Response

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