Search
K

Compare User Information

Partners are able to automatically compare the information returned by an ID authority with the information we read from a user-submitted document, such as a passport.
This comparison is sequence-agnostic: partners can combine Enhanced KYC or Biometric KYC and Document Verification in any order they choose.
By calling our compare_user_info endpoint, partners need not rely on human review, and can have an extra assurance that their user’s KYC information checks out.
Request Type: Post

Request Body

Name
Type
Description
source_sdk
string
The integration option you are using. For rest api send the value as "rest_api"
source_sdk_version
string
The version of the integration option you are using
partner_id
string
Your partner id can be found on the side navigation panel of the Smile ID partner portal
timestamp
string
The outgoing signature to authenticate the request from you to Smile ID
signature
string
The timestamp used to calculate the signature in ISO date/time format
user_id
string
The user ID of an existing user who has successful Biometric KYC and Document Verification jobs with the same id.
country
string
The country of issuance of the ID, this should be the same as the one you used while running both the Biometric KYC and Document Verification jobs.
id_type
string
The type of ID or document, this should be the same as the one you used while running both the Biometric KYC and Document Verification jobs.

Sample Request Body

{
"source_sdk": "rest_api",
"source_sdk_version": "1.0.0",
"partner_id": "002",
"timestamp": "2021-05-18 15:14:43 -0700",
"signature": "V0Ti...",
"user_id": "4fdjlkfsec0-6477-4083-b1b6-3d6fa6230a71",
"country": "NG",
"id_type": "PASSPORT"
}

Response

Name
Type
Description
Return Values
SmileJobID
string
The Smile internal reference number for the job
PartnerParams
object
A JSON object containing the job tracking parameters you sent with the request
PartnerParams.user_id
string
A value generated by you, so you can track users on your end. This value must be unique, any string and can follow your identifier convention
PartnerParams.job_id
string
A unique value generated by Smile ID specifically for this user’s job
PartnerParams.job_type
int
The type of job you want to perform. This will be set to 9.
ResultText
string
Textual value of match outcome
“Partial Match”
“Exact Match”
“No Match”
ResultCode
string
Numeric value of match
1020=Exact Match, 1021=Partial Match,
1022 = No Match
Find list of potential error codes below.
Actions
object
A JSON object containing the details of the individual field comparisons
Actions.Return_Personal_Info
string
This key confirms if we sent the personal information retrieved from the ID authority sent to you
“Not Applicable”
Actions.Verify_ID_Number
string
The result of looking up the ID number in the ID authority database is returned in this key
“Verified”
Actions.Name
string
Result of comparing names on the ID card image and the names returned by the ID authority
“Exact Match”
“Partial Match”
“Transposed”
“No Match”
Actions.DOB
string
Result of comparing DOB on the ID card image and the names returned by the ID authority
“Exact Match”
“Partial Match”
“Transposed”
“No Match”
Actions.Gender
string
Result of comparing Gender on the ID card image and the names returned by the ID authority
“Exact Match”
“No Match”
Actions.PhoneNumber
string
Result of comparing Phone Number on the ID card image and the names returned by the ID authority
“Exact Match”
“No Match”
Actions.Address
string
Result of comparing Address on the ID card image and the names returned by the ID authority
“Exact Match”
“Partial Match”
“No Match”
Actions.ExpirationDate
string
Result of comparing Expiration Date on the ID card image and the names returned by the ID authority
“Exact Match”
“Partial Match”
“Transposed”
“No Match”
Actions.ID_Verification
string
Same as ResultText
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

Sample Response

{
"SmileJobID": "0000000407",
"PartnerParams": {
"user_id": "TEST_DEV_DOCV_USER_017",
"job_id": "83c949f6-a8dd-49cc-adf7-aa9dc6553aba",
"job_type": 9
},
"ResultText": "Partial Match",
"ResultCode": "1021",
"Actions": {
"Return_Personal_Info": "Not Applicable",
"Verify_ID_Number": "Verified",
"Name": "No Match",
"DOB": "Exact Match",
"Gender": "Exact Match",
"PhoneNumber": "Exact Match",
"Address": "No Match",
"ExpirationDate": "Exact Match",
"ID_Verification": "Partial Match"
},
"signature": "ntlu...",
"timestamp": "2022-05-24T18:43:42.536Z"
}

Evaluating the Response

If all the underlying fields are an exact match the overall result is an exact match. If at least one of the underlying fields is an exact match, partial match, or transposed then the overall result is a partial match. If all of the fields are no match then the entire result is no match. Here is an explanation of the matching rules:
Exact Match
The values are a case-insensitive exact match
Partial Match
For name values it is a partial match if the values are a levenshtein distance of <= 2 apart.
For date of birth and expiration date it is a partial match if any single component (Day, Month, Year) is within 1 digit of the returned value. If more than one component of date birth is off then it is no match.
Transposed
Two elements are transposed.
For example first name and last name or month of birth and date of birth
No Match
All other cases
We advise that you build a business logic that handles jobs that have an overall result of partial match

Error Codes

Code
Error
Description
Recommended Action
2421
You must perform both KYC and Document Verification for this user.
You sent a user_id that doesn’t have successful Biometric KYC and Document Verification jobs
Confirm that you sent the right user_id and retry
2205
You are not authorized to do that.
Your signature and/or timestamp is incorrect or you are using the signature and timestamp for a wrong environment
Follow the steps in troubleshooting authorisation issues guide
2413
<parameter> is missing
You didn’t send all the required parameters in the request body
Compare your request body with the sample request provided above

Result Codes

Code
Text
Description
Recommended Action
1020
Exact Match
All of the fields on the ID card image exactly match the ID info in the ID authority database.
Approve
1021
Partial Match
At least one of the fields on the ID card image partially/exactly matches the ID info in the ID authority database.
Custom business logic
1022
No Match
None of the fields on the ID card image partially/exactly match the ID info in the ID authority database.
Reject