* Please note that this article is in regards to the BioStar 2 New Local API (different from the previous BioStar 2 Local API). If you'd like to learn more about the difference, please check out the following article: [BioStar 2 API] Difference Between BioStar 2 Local API Server and BioStar 2 New Local API *



This article will guide you through adding a fingerprint credential to a user via BioStar 2 API. 


This article also includes a sample code of a C# program that incorporates the API, and also an example of API call made via Postman, a program used for building & testing RESTful API calls. 



Before we get started


For introduction to BioStar 2 API, please check out the following article: [BioStar 2 API] How To Use BioStar 2 New Local API

To view other BioStar 2 APIs, please check out our Postman documentation that has information on all of the APIs: https://bs2api.biostar2.com/ 



Adding a fingerprint credential to a user via API can be done in 5 steps. 


1. Scanning fingerprint via a device

2. Verifying whether the fingerprint already exists in the server 

3. Scanning the same fingerprint via a device again 

4. Checking that the two fingerprint scans are the same finger

5. Adding the scanned fingerprint to a user's credentials 


Step 1. Scanning Fingerprint via a Device


The following API is used to scan a fingerprint. 


POST        /api/devices/:dev_id/scan_fingerprint


Before calling this API, you need to know the device id of the device that you are going to use to scan the fingerprint. 


[Path Variables] 


ParameterTypeRequiredDescription
dev_idNumberYID of the device which will be used to scan fingerprint.


[Body Parameters]


ParameterTypeRequiredDescription
enroll_qualityNumberNSet a fingerprint enrollment quality level. Any fingerprint which does not meet the quality requirement will not be enrolled.
raw_imageBooleanNSet this option to view the original image when a fingerprint is scanned.


Postman Example of Request : 


When you run the above API, the device will prompt for you to scan your fingerprint. 


If you have successfully scanned your fingerprint, you'll get a response back with the fingerprint template information.

If you do not get the fingerprint template information, please try again or try it with a different finger. 


Postman Example of Response:



Step 2. Verifying Whether the Fingerprint Already Exists in the Server


This API is used to verify duplicate fingerprint. 


POST                      /api/server_matching/identify_finger


[Body Parameters]


ParameterTypeRequiredDescription
templateBase64YTemplate of the fingerprint which will be validated.


 *  For the "template" parameter in this step, please use the "template0" field obtained from the response in Step 1. 


Postman Example of Request: 


If fingerprint already exists, it will return success (HTTP 200) and response will show the user that is currently using the fingerprint. 

If fingerprint doesn't exist in server, it will return server error (HTTP 500) with response showing message "Failed to identify fingerprint". 

When you are trying to add a new fingerprint to a user, please make sure to look for a failed response since that means that the fingerprint is not in the server and available to use for a user. 


Postman Example of Response : 


In this example, since we have received the 500 error and verified that there isn't a duplicate fingerprint in the server, we are good to continue! 



Step 3. Scanning the Same Fingerprint via a Device Again


Please repeat Step 1 with the same finger to obtain a second fingerprint scan that will be used in step 4 and 5. 




Step 4. Checking that the Two Fingerprint Scans are from the Same Finger


This API is used to compare 2 fingerprint scans to determine whether it's the same finger or not. 


POST             /api/devices/:dev_id/verify_fingerprint 


[Path Variables] 


ParameterTypeRequiredDescription
dev_idNumberYID of the device which will be used to scan fingerprint.


[Body Parameters] 


ParameterTypeRequiredDescription
template0Base64Y1st scan template of the fingerprint
template1Base64Y2nd scan template of the fingerprint
security_levelNumberNSet the verification security level. Higher number will have stricter requirement.


 * For "template0", please use the "template0" data you obtained from the API response in Step 1 (first scan of fingerprint). For "template1" parameter, please use the "template0" data you obtained from the API response in Step 3 (second scan of fingerprint).


Postman Example of Request :


After running the above API, it will return a HTTP 200 response code and show message result: true on success if the two fingerprint scans are from the same finger. It will return a HTTP 500 response code and show message result: false on failure if the two fingerprint scans are not from the same finger. 


Postman Example of Response :


In this example, we have successfully verified that the two fingerprint scans are from the same finger and we are good to continue!



Step 5. Adding the Scanned Fingerprints to a User's Credentials 


This API updates user information. 


PUT          /api/users/:id


[Path Variables] 


ParameterTypeRequiredDescription
idNumberYID of user you want to add the fingerprint credential to. 


In this article, I'll only show the body parameters that are related to updating the fingerprint credential of the user. 

You can add other parameters if you wish to change/update other user information to this API. 


[Body Parameters] 


ParameterTypeRequiredDescription
fingerprint_templatesArrayY
:finger_maskBooleanNSet to True to mark the fingerprint as a duress fingerprint. When threatened by someone to open the door, the user can authenticate using this fingerprint to send an alarm signal to BioStar 2.
:template0RawYFirst scanned template of the fingerprint.
:template1RawYSecond scanned template of the fingerprint.
:isNewBooleanNTrue for new fingerprint. 


 * Please use the same values you used in Step 4 for "template0" and "template1" parameters. 

 

"template0": "/9j/4AAQSkZJRgABAQEASABI…”

Good

"template0": "Base64: /9j/4AAQSkZJRgABAQEASABI…”

Bad

“fingerprint_templates”: []

Unregister fingerprints


 * Please note that the fingerprint data needs to be in Base64 format. You are recommended to use a fingerprint scanning device to scan your fingerprints since it automatically transforms the fingerprint template data to Base64 format which you can use it to insert it here directly. 

If you are converting the template to Base64 format yourself, please check and do NOT include "Base64 :" in your input for "template0" & "template1". 

 * If you have the "fingerprint_templates" array value as empty, it will unregister the current user fingerprint templates. 


Postman Example of Request :


Postman Example of Response : 


After successfully running the above API, you can verify in BioStar 2 that user "2" now has a fingerprint credential added and they can authenticate using the finger! 





C# Console App Example 


There are 2 steps to take to register fingerprint to a user. But, in the console, it is there is an additional step to choose the user which will receive the fingerprint registration.

  1. RegisterFingerPrint: Choose a user for fingerprint registration
  2. ScanFingerprint: Scan fingerprint via already chosen device(this step is taken 2 times in biostar 2)
  3. RegisterFingerPrintToUser: Register the scanned fingerprint to the user chosen.

[RegisterFingerPrint] 

static async void RegisterFingerPrint()

        {

            Console.WriteLine("*****RegisterFingerPrint Task Started******");

            if (sessionID == null)

            {

                Console.WriteLine("You must log in first!");

                return;

            }

 

            CookieContainer cookieContainer = new CookieContainer();

 

            HttpClientHandler handler = new HttpClientHandler();

            handler.CookieContainer = cookieContainer;

 

            HttpClient client = new HttpClient(handler);

 

            client.DefaultRequestHeaders.Add("bs-session-id", sessionID);

            cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID));

            ListUsers();

            Console.WriteLine("Select User ID for Fingerprint Registration...");

            string userID = Console.ReadLine();

            //HttpResponseMessage httpResponse = await client.GetAsync("https://127.0.0.1/api/users");

            HttpResponseMessage httpResponse = client.GetAsync("https://127.0.0.1/api/users").Result;

 

 

            if (httpResponse.IsSuccessStatusCode == true)

            {

                string httpResponseBody = await httpResponse.Content.ReadAsStringAsync();

                //Console.WriteLine(httpResponseBody);

                Console.WriteLine("Registering FINGERPRINTS to the USER(" + userID + ")");

                ScanFingerprint(userID);

 

            }

            else

            {

                Console.WriteLine("Retrieving User List Failed");

                Console.WriteLine(httpResponse.ToString());

            }

        }

 

[ScanFingerprint]

  • This step is taken 2 times in BioStar 2. You should actually run this method 2 times to have 2 different templates. But, in the methods in console application, it is only done once. The same template value goes into template0 and template1.  

static async void ScanFingerprint(string UserID)

        {

            Console.WriteLine("*****ScanFingerprint Task Started*****");

            CookieContainer cookieContainer = new CookieContainer();

 

            HttpClientHandler handler = new HttpClientHandler();

            handler.CookieContainer = cookieContainer;

 

            HttpClient httpClient = new HttpClient(handler);

 

            HttpClient client = new HttpClient(handler);

               httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID);

            cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID));

            string deviceID = "538747164";

            string resourceAddress = "https://127.0.0.1/api/devices/" + 538747164 + "/scan_fingerprint";

 

            JavaScriptSerializer serializer = new JavaScriptSerializer();

 

            string payload = "{ \"ScanFingerprintOption\": { \"enroll_quality\": \"80\", \"raw_image\": false}, \"noblockui\": true}";

            Console.WriteLine(payload);

            StringContent sc = new StringContent(payload, Encoding.UTF8, "application/json");

            //HttpResponseMessage httpResponse = await httpClient.PostAsync(resourceAddress, sc);

            HttpResponseMessage httpResponse = httpClient.PostAsync(resourceAddress, sc).Result;

 

            Console.WriteLine("SCAN YOUR FINGERPRINT with the DEVICE(ID: " + deviceID + ")");

 

            if (httpResponse.IsSuccessStatusCode == true)

            {

                Console.WriteLine("Scan Fingerprint Successful.");

                string httpResponseBody = await httpResponse.Content.ReadAsStringAsync();

                   Console.WriteLine(httpResponseBody);

                dynamic obj = JsonConvert.DeserializeObject(httpResponseBody);

                string template0 = obj.FingerprintTemplate.template0;

                string template_image0 = obj.FingerprintTemplate.template_image0;

                //Console.WriteLine("Scanned Fingerprint's template0: " + template0);

                   RegisterFingerPrintToUser(UserID, template0);

            }

            else

            {

                Console.WriteLine("Scan Fingerprint Failed.");

                Console.WriteLine(httpResponse.ToString());

            }

        }

 

[RegisterFingerPrintToUser]

  • This method receives the template value from ‘ScanFingerprint’ method and places it to both ‘template0’ and ‘template1’ values.

static async void RegisterFingerPrintToUser(string UserID, string template0)

        {

            Console.WriteLine("*****RegisterFingerPrintToUser Task Started******");

            if (sessionID == null)

            {

                Console.WriteLine("You must log in first!");

                return;

            }

            CookieContainer cookieContainer = new CookieContainer();

 

            HttpClientHandler handler = new HttpClientHandler();

            handler.CookieContainer = cookieContainer;

 

            HttpClient httpClient = new HttpClient(handler);

 

            HttpClient client = new HttpClient(handler);

               httpClient.DefaultRequestHeaders.Add("bs-session-id", sessionID);

            cookieContainer.Add(new Uri("https://127.0.0.1"), new Cookie("bs-session-id", sessionID));

            Console.WriteLine("Registering Fingerprint to USER(" + UserID + ") ...");

 

            string resourceAddress = "https://127.0.0.1/api/users/" + UserID + "";

            string payload = "{ \"User\": { \"fingerprint_templates\": [ { \"template0\": \"" + template0 + "\", \"template1\": \"" + template0 + "\", \"finger_mask\": false,\"isNew\": true}  ] }}";

            //*You actually have to scan Fingerprint twice to have template0 & template1 but I skipped this procedure. I only receive template0 and use it twice in above payload(requestbody(JSON))

            StringContent sc = new StringContent(payload, Encoding.UTF8, "application/json");

            //HttpResponseMessage httpResponse = await httpClient.PutAsync(resourceAddress, sc);

            HttpResponseMessage httpResponse = httpClient.PutAsync(resourceAddress, sc).Result;

 

 

            if (httpResponse.IsSuccessStatusCode == true)

            {

                   Console.WriteLine(httpResponse.ToString());

                string httpResponseBody = await httpResponse.Content.ReadAsStringAsync();

                Console.WriteLine("***** FINGERPRINT is now registered to " + " User " + UserID + " *****");

            }

            else

            {

                Console.WriteLine("Failed to Register FINGERPRINT to User(" + UserID + ")");

                   Console.WriteLine(httpResponse.ToString());

            }

 

        }

 

[Select a User] 

Input: User ID

텍스트이(가) 표시된 사진 자동 생성된 설명


[Scan your fingerprint] 


[Registration Processed successfully]

텍스트이(가) 표시된 사진 자동 생성된 설명