Technical Support

Updated 2023-06-20

Introduction

If you’d like to use BioStar 2 API as a RESTful API for your own customization or other purposes, you can simply reference this article. This article will cover the most basic usage of the BioStar 2 API by C# console application.

This is just a sample application made for those who might need to use the BioStar 2 API. It is a Visual C# console application.

Features

This article will cover the function below:

Register Visual Face via Send Email API
Register Visual Face via Face Scanning by a device (FaceStation F2 equivalent procedure for BioStation 3)

Through this article, you can learn how to call an API function to register Visual Face to the users in BioStar 2 server. There are 2 different ways to register Visual Face via BioStar 2 API.

Make sure you take a good look at the example code of the C# program built for API calls. You can simply copy & paste the source code to use the same function in your own integration.

You can also see how to call the API functions via Postman, which is a program used for RESTful API calls.

*You must have a FaceStation F2 or BioStation 3 connected to your BioStar 2.

For the description of how to register Visual Face via Scanning by a device with BioStar 2, please visit https://support.supremainc.com/a/solutions/articles/24000060147?lang=en .

Part 1. API Call & Parameters

- Scanning Visual Face

[GET]: /api/devices/{deviceID}/credentials/face?pose_sensitivity=0&nonBlock=true

[Parameters]

Name	Type	*M/O	Explanation	Value

* M – Mandatory, O – Optional

- Registering Visual Face

[PUT]: /api/users/{id}

[Parameters]

Name	Type	*M/O	Explanation	Value
User/credentials/visualFaces	Array	O	Visual Face Information
Template_ex_normalized_image	String	O	Image name in Base64
Templates	Array	O	“template_ex”, “credential_bin_type”, “template_ex_ir”
Templates/template_ex	String	O	Base64	“5”
Templates/credential_bin_type	String	O	Credential bin type
Templates/credential_ex_ir	String	O	Base64
Templates/credential_bin_type	String	O	Credential bin type	“6”
Flag	String	O	Flag	“1”
useProfile	String	O	Use as profile or not	True & False

* M – Mandatory, O – Optional

Part 2. Request Body & Response Model

- Scanning Visual Face

[GET]: /api/devices/{deviceID}/credentials/face?pose_sensitivity=0&nonBlock=true

[Example Value/Parameters Model]

[Response Model]

{

"credentials": {

"faces": [

{

"raw_image": "Base64: RDQQFJYAVUYvFXsEIzIQC1QYbodkHe...",

"templates": [

{

"template": "Base64: RDQQFJYAVUYvFXsEIzIQC1QYbodkHe..."

}

"flag": "0"

}

]

"Response": {

"code": "1003",

"link": "https://support.supremainc.com/en/support/home",

"message": "Success"

"httpResponseStatus": 200

}

[Response: Fail]

{

"Response": {

"code": "262155",

"link": "https://support.supremainc.com/en/support/home",

"message": "not defined"

}

[Response: Successful]

{

"credentials": {

"faces": [

{

"template_ex_normalized_image": "/9j/4AAQSkZJRgABAQEASABI… ",

"templates": [

{

"template_ex": "AAAAAAEA4gCFAe4AFQE8//7/…",

"credential_bin_type": "5"

{

"template_ex_ir": "AAAAAAEAHgGPAeIAHAEAAAAASlQ7RU…",

"credential_bin_type": "6"

}

"flag": "1"

}

]

"Response": {

"code": "0",

"link": "https://support.supremainc.com/en/support/home",

"message": "Success"

}

- Registering visual face

[PUT]: /api/users/{id}

[Example Value/Parameters Model]

{

"User": {

"credentials": {

"visualFaces": [

{

"template_ex_normalized_image": "/9j/4AAQSkZJRgABAQEASABIAAD/…",

"templates": [

{

"template_ex": "AAAAAAEA+QCAAeMAJwFhAQD/XFVUQ0…",

"credential_bin_type": "5"

{

"template_ex_ir": "AAAAAAEANAF+AdsAGQEAAAAASlBCRTyDfAA…",

"credential_bin_type": "6"

}

"flag": "1",

"useProfile": "false"

}

]

}

[Response Model]

{

"DeviceResponse": {

"rows": [

{

"id": "541530887",

"code": "65230"

}

"result": "false"

"Response": {

"code": "0",

"link": "https://support.supremainc.com/en/support/home",

"message": "Success"

}

[Response: Fail]

{

"Response": {

"code": "20",

"message": "Permission not allowed"

}

[Response: Successful]

{

"Response": {

"code": "0",

"link": "https://support.supremainc.com/en/support/home",

"message": "Success"

}

Part 3. Console Example

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

ScanAndRegisterVisualFace: Choose a user for Visual Face registration
ScanVisualFace: Scan Visual Face via selected device (Must use FaceStation F2 or BioStation 3).
RegisterVisualFaceToUser: Register the scanned Visual Face to the user chosen.

[ScanAndRegisterVisualFace]

static async void ScanAndRegisterVisualFace()

{

Console.WriteLine("*****ScanAndRegisterVisualFace 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 Visual Face 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 VISUAL FACE to the USER(" + userID + ")");

ScanVisualFace(userID);

}

else

{

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

Console.WriteLine(httpResponse.ToString());

}

[ScanVisualFace]

This step scans the Visual Face via selected device (FaceStation F2/BioStation 3).

static async void ScanVisualFace(string UserID)

{

Console.WriteLine("*****ScanVisualFace 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));

ListDevices();

Console.WriteLine("Select Device ID for Visual Face Scanning...(SELECT FaceStation F2 or BioStation 3...");

string deviceID = Console.ReadLine();

string resourceAddress = "https://127.0.0.1/api/devices/" + deviceID + "/credentials/face?pose_sensitivity=0&nonBlock=true";

JavaScriptSerializer serializer = new JavaScriptSerializer();

string payload = "";

Console.WriteLine(resourceAddress);

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

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

HttpResponseMessage httpResponse = httpClient.GetAsync(resourceAddress).Result;

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

if (httpResponse.IsSuccessStatusCode == true)

{

Console.WriteLine("Scan VISUAL FACE Successful.");

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

Console.WriteLine(httpResponseBody);

dynamic obj = JsonConvert.DeserializeObject(httpResponseBody);

string template_ex_normalized_image = obj.credentials.faces[0].template_ex_normalized_image;

string template_ex = obj.credentials.faces[0].templates[0].template_ex;

string template_ex_ir = obj.credentials.faces[0].templates[1].template_ex_ir;

string flag = obj.credentials.faces[0].flag;

RegisterVisualFaceToUser(UserID, template_ex_normalized_image, template_ex, template_ex_ir, flag);

}

else

{

Console.WriteLine("Scan VISUAL FACE Failed.");

Console.WriteLine(httpResponse.ToString());

}

[RegisterVisualFaceToUser]

This method receives the template values from ‘ScanVisualFace’ method and places it to ‘template_ex_normalized_image’, ‘template_ex’, ‘template_ex_ir’, and ‘flag’ values.

static async void RegisterVisualFaceToUser(string UserID, string template_ex_normalized_image, string template_ex, string template_ex_ir, string flag)

{

Console.WriteLine("*****RegisterVisualFaceToUser 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 VISUAL FACE to USER(" + UserID + ") ...");

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

string payload = "{\"User\": {\"credentials\": {\"visualFaces\": [{\"template_ex_normalized_image\": \"" + template_ex_normalized_image + "\",\"templates\": [{\"template_ex\": \"" + template_ex + "\",\"credential_bin_type\": \"5\"},{\"template_ex_ir\": \"" + template_ex_ir + "\",\"credential_bin_type\": \"6\"}],\"flag\": \"" + flag + "\",\"useProfile\": \"false\"}]}}}";

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("***** VISUAL FACE is now registered to " + " User " + UserID + " *****");

}

else

{

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