FAQ

HomeKnowledge BaseFAQ

Biometric Match Native Integration API v3

115 views /  0 like /  / admin/

Quick Links:

  • Download Postman Collection

  • API Docs

Getting Started:

  1. Account: First you need to get an account. Contact our sales team at partners@chekin.io and they will create an account for you with an email and password.
  2. Token: Use your email & password to get a token using our API:
    Copy Code 
    					
    

    POST https://a.chekin.io/api/v3/token/

{
	"email": "your@user",
	"password": "yourpassword"
}
Response:
{
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiN2JkMzU4NzEyYzJiNDY3ODllM2Y3ZjY1Y2UyM2FlYjgiLCJ1c2VybmFtZSI6Im1hcmlhbm9AY2hla2luLmlvIiwiZXhwIjoxNTcxMjU2OTA2LCJvcmlnX2lhdCI6MTU3MTI1MzMwNiwiaXNfb2NyX2VuYWJsZSI6ZmFsc2UsImZhY2VfZXh0IjpmYWxzZSwib2NyX3ZpeiI6ZmFsc2UsIm9jcl9iYXJjb2RlcyI6ZmFsc2V9.yEYTAeTs3omjqyX4nkWyIogmWcANn-XkUTz2k220Hlg"
}

    The token expires within 1 hour, and you will need to refresh it.

  3. Headers: Add these headers in all your following requests:
    • Content-Type application/json
    • Authorization JWT {{your token}}

Use Case #1: Verify guests identity comparing a photo of the guest with the photo present in his ID card / Passport. We show also a possible UX implementation as an example.

  1. Ask the user to take a picture of their ID, at the side containing the photo.
    When the user press “capture”, then a picture is taken and saved as a base64 encoded image. Then call the BIomatch API sending the picture.

    Copy Code 
    					
    

    POST https://a.chekin.io/api/v3/biomatch/identification/
{
   "picture_file":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQAB..."
}

	Response:
	{
    "id": "d0abc1c11e2240539eb15c9953b7ed50", // Save this id for later usage
    "picture_file": "https://link-to-the-stored-picture..",
    "status": "NEW",  // Picture was received and will be processed soon
    "is_face_detected": false
}

    The picture will be processed asynchronously as a transaction. You need to save the id returned in the first call and check check the status between 3-5 seconds later. Once status in COM (Complete) you can check if the face was detected.

    You should show some popup or spinner while the image is being processed:

  2. Check if the face was detected:
    Copy Code 
    					
    GET https://a.chekin.io/api/v3/biomatch/identification/d0abc1c11e2240539eb15c9953b7ed50/

Response:
{
    "id": "d0abc1c11e2240539eb15c9953b7ed50", 
    "picture_file": "https://link-to-the-stored-picture..",
    "status": "COM", // Picture was processed > check is_face_detected
    "is_face_detected": true // The face was detected and saved
}

    If status is complete (COM) then the image processing has finished. Otherwise, is status is still in Progress (PRO) you need to check again a few seconds later. Once status is complete you must check field is_face_detected. If is_face_detected is true it means the face of the person in the ID was detected and saved. Then you can save the id and continue with the next step. Else show an error message and ask the user to try again, repeating steps 1-2.

  3. If the ID was processed successfully, then you can ask the user to take a selfie:

    When the user press “capture”, then a picture is taken and saved as a base64 encoded image. Then call the Biomatch API sending the photo of the guest.

    Copy Code 
    					
    

    POST https://a.chekin.io/api/v3/biomatch/person/
{
   "picture_file":"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQAB..."
}

Response:
{
    "id": "287e2fb75cb445eaa0a4475494386978", // Save this id for later usage
    "picture_file": "https://link-to-the-stored-picture..",
    "status": "NEW", // Picture was received and will be processed soon
    "is_face_detected": false
}

    You can show again some popup or spinner while the image is being processed.

  4. Check if the face was detected:
    Copy Code 
    					
    GET https://a.chekin.io/api/v3/biomatch/person/287e2fb75cb445eaa0a4475494386978/

Response:
{
    "id": "287e2fb75cb445eaa0a4475494386978",
    "picture_file": "https://link-to-the-stored-picture..",
    "status": "COM", // Picture was processed > check is_face_detected
    "is_face_detected": true // The face was detected and saved
}

    Again, if status is COM and is_face_detected is true , then it’s a valid photo, the face of the guest was detected and we can move onto the next step. Else show an error message and ask the user to try again, repeating steps 3-4.

  5. Compare faces
    Copy Code 
    					
    

    POST https://a.chekin.io/api/v3/biomatch/compare/
	{
    "identification_picture": "d0abc1c11e2240539eb15c9953b7ed50", // ID photo
    "person_picture": "287e2fb75cb445eaa0a4475494386978" // Guest photo
}

	Response:
	{
    "id": "ab013e8beba44448b0dcb04e15a9f335",
    "identification_picture": "d0abc1c1-1e22-4053-9eb1-5c9953b7ed50",
    "person_picture": "287e2fb7-5cb4-45ea-a0a4-475494386978",
    "status": "NEW", // Request received and coparison will start soon
    "distance": null,
    "is_match": false
}

    You can show some different popup or spinner while the image is being processed.

  6. Check comparison results
    Copy Code 
    					
    GET https://a.chekin.io/api/v3/biomatch/compare/ab013e8beba44448b0dcb04e15a9f335/

Response:
{
    "id": "ab013e8beba44448b0dcb04e15a9f335",
    "identification_picture": "d0abc1c1-1e22-4053-9eb1-5c9953b7ed50",
    "person_picture": "287e2fb7-5cb4-45ea-a0a4-475494386978",
    "status": "COM",// Comparison finished > check distance and is_match
    "distance": 0.517852206523871,// Distance is in a valid range
    "is_match": true // The faces in both pictures do match.
}

    The faces on the two pictures are compared with an algorithm to determine how different they are. A distance value is calculated where 0 means they are equal and 1 means they are very different. If the distance is greater than 0.35 and smaller than 0.60, then it’s considered a match and the field is_match will be true. A smaller than 0.35 usually mean that the guest probably sent the same picture two times, which is not considered a valid match.

    If the faces doesn’t match (is_match == false) then you can show an error and ask the user to restart the process again from step 1.

See also:

Related Articles