The callback mechanism allows for asynchronous job requests and responses. While the job_status API can be polled to get a result, a better method is to set up a callback url and let the system POST a JSON response. This is especially recommended for SDK implementations because the result will go directly back to your server and avoid client side security issues.

Jobs can take different times to process. While most jobs take only a few seconds, jobs that require human review can take longer. The callback mechanism allows you to make a job request and receive all results without polling.

The partner params structure is passed back with every callback. We suggest using the job_id parameter to connect job requests and job results. You can also set optional keys in the partner params structure to aid in this connection.

The callback url can be specified in 3 ways: The first is to set the default_callback parameter in the initialization of the WebAPI module you are using. This will be used for each job submitted unless overridden by the second way to specify the callback url by setting the optional_callback parameter in the options structure passed to the submit_job function.

The third way is used for SDK implementations. Contact [email protected] to have this callback set in the system for you.

NOTE: the sandbox and the production servers can have seperate callbacks or both set to the same url.

There are two types of callbacks: all jobs return the default callback structure. A job that also contains a request to lookup an ID number from a government issuer will send the second type with the detailed information for that ID number.

Example Default Callback JSON

"Actions": {
"Human_Review_Compare": "Not Applicable",
"Human_Review_Liveness_Check": "Not Applicable",
"Human_Review_Update_Selfie": "Not Applicable",
"Liveness_Check": "Not Applicable",
"Register_Selfie": "Approved",
"Return_Personal_Info": "Returned",
"Selfie_Provided": "Passed",
"Selfie_To_ID_Authority_Compare": "Completed",
"Selfie_To_ID_Card_Compare": "Not Applicable",
"Selfie_To_Registered_Selfie_Compare": "Not Applicable",
"Update_Registered_Selfie_On_File": "Not Applicable",
"Verify_ID_Number": "Verified"
"ConfidenceValue": "99",
"PartnerParams": {
"job_id": "e1234267-a45f-411f-a828-9623a9cf2e18",
"job_type": "1",
"more_optional_info": "There can be as much or as little or no optional info",
"optional_info": "Partner can put whatever they want as long as it is a string",
"user_id": "123123123-175c-444b-b286-e1b52b7773c4"
"ResultCode": "0810",
"ResultText": "Enroll User",
"SmileJobID": "0000003087",
"Source": "WebAPI - ruby",
"sec_key": "...",
"timestamp": "2020-01-14T07:43:39.980Z"

Example ID Information Callback JSON

Each ID issuer returns different FullData structures!

"Actions": {
"Return_Personal_Info": "Returned",
"Verify_ID_Number": "Verified"
"Country": "NG",
"DOB": "1989-09-20",
"ExpirationDate": "Not Available",
"FullData": {
"birthcountry": "nigeria",
"birthdate": "20-09-1900",
"birthlga": "****",
"birthstate": "***",
"centralID": "****",
"educationallevel": "****",
"email": "[email protected]",
"emplymentstatus": "****",
"firstname": "****",
"gender": "m",
"heigth": "****",
"maritalstatus": "****",
"message": "Results Found",
"middlename": "****",
"nin": "****",
"nspokenlang": "****",
"ospokenlang": "****",
"othername": "****",
"photo": "<Base64 Encoded Image if available>",
"pmiddlename": "****",
"profession": "****",
"psurname": "****",
"residence_AdressLine1": "****",
"residence_Town": "****",
"residence_lga": "****",
"residence_state": "****",
"residencestatus": "****",
"self_origin_lga": "****",
"self_origin_place": "****",
"self_origin_state": "****",
"success": true,
"surname": "Doe",
"telephoneno": "0987654321",
"title": "mr",
"trackingId": "abcdefghijk"
"FullName": "John Doe",
"IDNumber": "1234567890",
"IDType": "NIN",
"PartnerParams": {
"job_id": "e1234267-a45f-411f-a828-9623a9cf2e18",
"job_type": "1",
"more_optional_info": "There can be as much or as little or no optional info",
"optional_info": "Partner can put whatever they want as long as it is a string",
"user_id": "123123123-175c-444b-b286-e1b52b7773c4"
"Photo": "<Base64 Encoded Image if available>",
"ResultCode": "1012",
"ResultText": "ID Number Validated",
"SmileJobID": "0000003087",
"sec_key": "...",
"timestamp": "2020-01-14T07:43:29.299Z"


To be sure the requests being received are, in fact, from Smile Identity there are 2 ways this can be done

  1. Verifying the incoming sec_key parameter in the request body of the result

  2. Whitelisting our originating IP address (see below):