drawing

T5-MBAP Developer Guide

Version 1.5
This document is intended for technical developer who will integrate T5-MBAP (Multi Biometric Authentication Platform). It describes the API along with interface and packet structure to be used by the clients communicating with the Tech5 T5-MBAP Server.

Disclaimers

The information contained in this document is the proprietary and exclusive property of Tech5 except as otherwise indicated. No part of this document, in whole or in part, may be reproduced, stored, transmitted, or used for design purposes without the prior written permission from Tech5.

The information contained in this document is subject to change without notice. The information in this document is provided for informational purposes only. Tech5 specifically disclaims all warranties, express or limited, including, but not limited, to the implied warranty of merchant-ability and fitness for a particular purpose, except as provided for in a separate software license agreement.

Privacy Information

This document may contain information of a sensitive nature. This information should not be given to individuals other than those who are involved in the T5-MBAP development or integration.

Contact : support@tech5-sa.com

1. Overview

1.1 Introduction

This document discusses the api Interface and packet structure to be used by the client communicating with the T5 MBAP Restful web service for Authentication and Verification. Biometric data face/finger/iris must be sent along with unique ID to get verify result. Optionally MBAP also facilitates biometric to biometric verification.

2. Client Interface

This Section explains the request and response structures that the client builds to communicate with MBAP Authentication. All the communication will be in JSON.

Request URL, Request and Response structure

MBAP Supports three types of request

Overview of Transaction types and typical sequence

ClientClientSDKMBAP Master1. Images2. TemplatesTemplates created using SDK can beused for enrollment& verification in MBAP3. Enroll(Images/Templates)If images are sent for enrollment, master creates templates using TC4. Insert Templates in cache5. Enroll Response6. Authenticate ID (Images/Templates)If images are sent for identification, master creates templates using TC7. Retrieve gallery templates from DB8. Match probe and gallery templates9. Authentication Response10. Verify Biometrics (Images/Templates)If images are sent for identification, master creates templates using TC11. Match Templates12. Verification ResponseClientClientSDKMBAP Master

Reqeust Data structures for biometric modalities :
Following data structures are common to all the request types. Data relevant to particular request should be sent.

public class Request {
    public string transactionId;
    public string transactionSource;
    public string encounter_id;
    public string faceThreshold;
    public string fingerThreshold;
    public string irisThreshold;
    public List<biometrics> biometrics;
    private FaceCoordinates faceCords;
}
public class biometrics {
    public string position { get; set; }
    public string image { get; set; }
    public string template { get; set; }
    public string type { get; set; }
}
public class FaceCoordinates {
	public int X;
	public int Y;
	public int Width;
	public int Height;
}

JSON Request structure description:

Position Codes Table

Position Code
Face “F”
RIGHT_IRIS “1”
LEFT_IRIS “2”
RIGHT_THUMB “1”
RIGHT_INDEX “2”
RIGHT_MIDDLE “3”
RIGHT_RING “4”
RIGHT_LITTLE “5”
LEFT_THUMB “6”
LEFT_INDEX “7”
LEFT_MIDDLE “8”
LEFT_RING “9”
LEFT_LITTLE “10”

Enrollment Request

This request type is used for enrolling records to the MBAP database which can then further be used for authentication using ID transaction types. MBAP will store the ID of the person and corresponding biometric templates in the DB. For enrollment, images or templates can be sent and what ever sent is stored and thus available for future use.

URL: http://xxx.xxx.xxx.xxxx:portnumber/IDAuthService/1.0/enroll
Method: POST
Consumes: Application/JSON
Produces: Application/JSON
Example: http://10.103.0.115:9090/IDAuthService/1.0/enroll

Request

Unique ID for the person and corresponding biometrics in the form of images or templates should be sent.

Sample Enollment JSON Request using images. Note: tech5 templates can also be sent instead of images

{
  "transactionId": "7095e951-57e7-47b9-8093-dd2847247600",
  "transactionSource": "Phase2 TestTool",
  "encounter_id": "51515151515151",
  "biometrics": [
       {
	      "position": "F",
	      "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIB",
	      "template": null,
	      "type": "Face",
	      "faceX": 0,
	      "faceY": 0,
	      "faceWidth": 0,
	      "faceHeight": 0
	    },
       {
          "position": "2",
	      "image": "AAAADGpQICANCocKAAAAFGZ0eXBqcDIgAAAAAGpw",
	      "template": null,
	      "type": "Iris"
	    },    
	    {
	      "position": "1",
	      "image": "AAAADGpQICANCocKAAAAFGZ0eXBqcDIgAAAAAGpw",
	      "template": null,
	      "type": "Iris"
	    }, 
	    {
	      "position": "7",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNTE2C",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "10",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNDk0C",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "8",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNTAyC",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "9",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNTExC",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "6",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNDgwC",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "2",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNTE0C",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "5",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNTAyC",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "3",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNDgyC",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "4",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNDg3C",
	      "template": null,
	      "type": "Finger"
	    },
	    {
	      "position": "1",
	      "image": "/6D/qAB5TklTVF9DT00gOQpQSVhfV0lEVEggNDgwC",
	      "template": null,
	      "type": "Finger"
	    }
	  ]
	}

Response

Upon successful execution following response will be sent. Error code will be send in case if there is an error (please refer to error code table at the end).
Sample JSON Response for enrollment request.

{
    "errorCode":1000,
    "errorMessage":"SUCCESS"
}

Authentication using ID

This request type is used for verification using ID. In this request the user can send the ID of the person to be verified and associate biometrics (image or template). MBAP will compare the biometrics passed in the request with the biometrics stored in the DB corresponding to that ID. If the matching score is above the passed threshold a true response will be sent. This serves as a central authentication system.

URL: http://xxx.xxx.xxx.xxxx):portnumber/IDAuthService/1.0/verifyWithId
Method: POST
Consumes: Application/JSON
Produces: Application/JSON
Example: http://10.103.0.115:9090/IDAuthService/1.0/verifyWithId

Request

ID of the person and biometrics in the form of images or templates
Sample JSON Authentication Request structure using Face and Iris using Image:

{
  "transactionId": "1d62526c-d4cd-48f7-9a3a-905dad4c2b2222d",
  "encounter_id": "1000000000000009",
  "transactionSource": "MBAP Test Tool",
  "faceThreshold": "6",
  "fingerThreshold": "0.6",
  "irisThreshold": "0.5",
  "biometrics": [
    {
      "position": "F",
      "image": "rAkAAAEAAAAAAABJADE0AAAAAAAAlwkAAEkC9AH0ATQ0BEYAFBQRD",
      "template": null, 
      "type": "Face"
    },
    {
      "position": "1",
      "image": "kjasdbhHDGGDLDNNrAkAAAEAAAAAAABJADE0AAAAAAAAlwkAAEkC9",
      "template": null,
      "type": "Iris"
    }
  ]
}

Sample JSON Authentication Request structure using Iris and Finger Image:

{
  "transactionId": "1d62526c-d4cd-48f7-9a3a-905dad4c2b2222d",
  "encounter_id": "1000000000000009",
  "transactionSource": "MBAP Test Tool",
  "faceThreshold": "6",
  "fingerThreshold": "0.6",
  "irisThreshold": "0.5",
  "biometrics": [
    {
      "position": "1",
      "image": "rAkAAAEAAAAAAABJADE0AAAAAAAA",
      "template": null, 
      "type": "Iris"
    },
    {
      "position": "2",
      "image": "kjasdbhHDGGDLDNNrAkAAAEAAAAA",
      "template": null,
      "type": "Finger"
    }
  ]
}

Sample JSON Authentication Request structure using Face and Finger Image:

{
  "transactionId": "1d62526c-d4cd-48f7-9a3a-905dad4c2b2222d",
  "encounter_id": "1000000000000009",
  "transactionSource": "MBAP Test Tool",
  "faceThreshold": "6",
  "fingerThreshold": "0.6",
  "irisThreshold": "0.5",
  "biometrics": [
    {
      "position": "F",
      "image": "rAkAAAEAAAAAAABJADE0AAAAAAAAA",
      "template": null, 
      "type": "Face"
    },
    {
      "position": "2",
      "image": "kjasdbhHDGGDLDNNrAkAAAEAAAAAA",
      "template": null,
      "type": "Finger"
    }
  ]
}

Sample JSON Authentication Request structure using Face and Iris templates:

{
  "transactionId": "1d62526c-d4cd-48f7-9a3a-905dad4c2b2222d",
  "encounter_id": "1000000000000009",
  "transactionSource": "MBAP Test Tool",
  "faceThreshold": "6",
  "fingerThreshold": "0.6",
  "irisThreshold": "0.5",
  "biometrics": [
    {
      "position": "F",
      "image": null,
      "template":"rAkAAAEAAAAAAABJADE0AAAAAAAA",
      "type": "Face"
    },
    {
      "position": "1",
      "image": null,
      "template": "kjasdbhHDGGDLDNNrAkAAAEAAAA",
      "type": "Iris"
    }
  ]
}

Response

Response Data structures for biometric modalities :

public class AuthResponse
{
    public string transactionId { get; set; }
    public string transactionSource { get; set; }
    public string ErrorCode { get; set; }
    public string ErrorMessage { get; set; }
    public string VerificationResult { get; set; }      
}

JSON structure description:

Sample JSON AuthResponse

{
    "errorCode": 1000,
    "errorMessage": "MATCH - Score[1.0]",
    "verificationResult": true,
    "transactionId": "1d62526c-d4cd-4fer8f7-9a3a-905dad4c2b2222d",
    "transactionSource": "MBAP Test Tool"
}

Verification using biometrics

This request type is used for matching two biometrics sets passed in the request. This is a stateless service and does not depend on the database. If the matching score is above the passed threshold the system will respond with a true.

URL: http://xxx.xxx.xxx.xxxx):portnumber/IDAuthService/1.0/verifyBiometrics
Method: POST
Consumes: Application/JSON
Produces: Application/JSON
Example: http://10.103.0.115:9090/IDAuthService/1.0/verifyBiometrics

Request

Sample JSON Finger verification request using biometric images

{
		"transactionId": "711c66e4-41cd-4d8f-85f7-94372gjja032b77",
		"transactionSource": "MBAP TestTool",
		"faceThreshold": 6,
		"fingerThreshold": 0.6,
		"irisThreshold": "0.5",
		"biometrics": [{
			"image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wbX/AFC/7x/",
			"template": null,
			"position": "1",
			"type": "Figner"
		},{
			
			"image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIB",
			"template":null,
			"position": "1",
			"type": "Finger"
		}]
	}

Sample JSON Face verification request using biometric templates

{
		"transactionId": "7sd11c66e4-41cd-4d8gfgf-85f7-94372gjja032b77",
		"transactionSource": "MBAP TestTool",
		"faceThreshold": 6,
		"fingerThreshold": 0.6,
		"irisThreshold": "0.5",
		"biometrics": [{
			"image": null,
			"template": "4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQI1e",
			"position": "1",
			"type": "Face"
		},{
			
			"image": null,
			"template":"4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQ",
			"position": "1",
			"type": "Face"
		}]
	}

Response

Sample JSON AuthResponse

{
    "errorCode": 1000,
    "errorMessage": "MATCH - Score[1.0]",
    "verificationResult": true,
    "transactionId": "1d62526c-d4cd-4fer8f7-9a3a-905dad4c2b2222d",
    "transactionSource": "MBAP Test Tool"
}

GetEncounterStatus using EncounterID

This request type is used for checking EncounterID is exist or not in MBAP cache against for each three modalities. If modality exists we will receive it as “true” or else “false”.

URL: http://xxx.xxx.xxx.xxxx):portnumber/IDAuthService/1.0/getEncounterStatus/EncounterID
Method: GET
Example: http://10.103.0.115:9090/IDAuthService/1.0/getEncounterStatus/9595833595

Request

http://facetcloud.tech5.tech:9090/IDAuthService/1.0/getEncounterStatus/9595833595

Response

     {"Face":"true","Finger":"true","Iris":"true"}

delete using EncounterID

This request type is used for deleting EncounterID which exist in MBAP cache against for all three modalities.

URL: http://xxx.xxx.xxx.xxxx):portnumber/IDAuthService/1.0/delete/EncounterID
Method: POST
Example: http://10.103.0.115:9090/IDAuthService/1.0/delete/9595833595

Request

http://facetcloud.tech5.tech:9090/IDAuthService/1.0/delete/9595833595

Response

     {"Face":"true","Finger":"true","Iris":"true"}

3. ERROR CODES

Following are the error code definitions:

Error Code Error Message
1000 SUCCESS
1001 ENCOUNTER ID NOT FOUND
1002 FINGER IMAGE TEMPLATE CREATE ERROR
1003 FACE IMAGE TEMPLATE CREATE ERROR
1004 FINGER IMAGE VERIFICATION ERROR
1005 FACE IMAGE VERIFICATION ERROR
1006 INTERNAL_SERVER_ERROR
1007 INVALID_POSITION_SPECIFIED
1008 INVALID_BIOMETRIC_TYPE
1009 IMAGE_OR_TEMPLATE_MISSING
1010 ENCOUNTER_ID IS MISSING
1011 MISSING BIOMETRIC DATA
1012 NO_FINGER_NODES
1013 NO_FACE_NODES
1014 INVALID_FINGER_IMAGE
1015 INVALID_FACE_IMAGE
1016 NIK_NOT_PRR
1017 IRIS_IMAGE_TEMPLATE_CREATE_ERROR
1018 INVALID_IRIS_IMAGE
1019 FINGER GALLERY TEMPLATE NOT FOUND
1020 ERROR WHILE INSERTING DEMOGS
1021 DEMOGRAPHICS MISSING
2001 FACE GALLERY TEMPLATE NOT FOUND
2002 IRIS_IMAGE_VERIFICATION_ERROR
2003 IRIS GALLERY TEMPLATE NOT FOUND