This article will guide you through creating a user in BioStar 2 server via BioStar 2 API.
You can find a more detailed introduction to BioStar 2 New Local API in this article : [BioStar 2 API] How To Use BioStar 2 New Local API
In this article, you can learn how to call an API function to create users to your BioStar 2 server. There are quite a lot of parameters, but you can create users just with the mandatory parameter values. If you’d like to add other optional fields to your user, you can simply insert the values accordingly.
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.
Part 1. API Call & Parameters
[POST]: /users
You can also find information regarding this API in the following link : Create New User API Documentation
[Parameters]
| Parameters | Type | Required | Description |
|---|---|---|---|
| users: | Y | ||
| user_id | String | Y | ID of the User. Unique. When User ID Type in Setting > Server is set to Number, a number between 1 and 4294967295 can be entered. When Alphanumeric is set, a combination of alphabetic characters and numbers can be entered. Do not use spaces when entering ID. Numbers or Alphanumeric characters can be set for user_id. For more details, refer to Setting Section of this documentation. |
| name | String | N | Name of the user. Up to 48 characters. |
| user_group_id:id | Number | Y | ID of the User Group that the user will be under. Refer to User Group Section of this documentation for listing available User Groups. |
| disabled | Boolean | N | Toggle User active or not; false for active, true for non-active. |
| start_datetime | Date/Time | Y | Start active period for the User. |
| expiry_datetime | Date/Time | Y | End active period for the User. |
| String | N | Email address of the User. | |
| department | String | N | Department of the User. Up to 64 characters. |
| title | String | N | Title of the User. |
| photo | Base64 | N | Photo of the User. |
| phone | String | N | Phone number of the User. |
| permission:id | Number | N | Operator Level of the User. None: The user has no operator privilege. To use this Operator Level, remove permission parameter from the API Request. Administrator: The user can use all menus. User Operator: The user can only use the USER and PREFERENCE menus. Monitoring Operator: The user can use the MONITORING and PREFERENCE menus and only view the DASHBOARD, USER, DEVICE, DOOR, ZONE and ACCESS CONTROL menus. Video Operator: The user can only use the VIDEO menu. T&A Operator: The user can only use the TIME ATTENDANCE menu and only view the USER menu. User: The user can only view own information and T&A records. |
| access_groups:id | Number | N | ID of the Access Group that the User will have access. Can enter more than 1 Access Group. |
| login_id | String | N | Required when permission parameter is not removed. |
| password | String | N | Required when permission parameter is not removed. |
| user_ip | String | N | Limit the access of the User so he/she can only login from the registered IP Address. The user IP can be entered in the format xxx.xxx.xxx.xxx. Each octet can only be entered in numbers between 0 and 255. Users whose user IP is not registered can log in from any IP. |
| pin | Number | N | PIN of the user. Maximum 32 digit. |
| fingerprint_templates | N | Add fingerprint data to a user. | |
| :finger_mask | Boolean | N | Set 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. |
| :template0 | Raw | N | First scan template of the fingerprint. Required if you are adding 'fingerprint_templates' |
| :template1 | Raw | N | Second scan template of the fingerprint. Required if you are adding 'fingerprint_templates' |
| :isNew | Boolean | N | |
| cards:id | Number | N | Add card credential to user. |
| credentials:face | Array | N | Main container of face credential |
| :raw_image | Raw | N | Raw image of the face scan. Required if you are adding 'credentials:face' |
| :templates | Array | N | Container of face templates Required if you are adding 'credentials:face' |
| ::template | Raw | N | Face template of user |
| credentials:visualFaces | Array | N | Main container of Visual Face credential for user. |
| : template_ex_normalized_image | Base64 | N | Cropped image ready for visual face extraction. Required if you are adding 'credentials:visualFaces' |
| :templates | Array | N | Container of the templates Required if you are adding 'credentials:visualFaces' |
| ::credential_bin_type | Number | N | UNKNOWN = -1 FACE_TEMPLATE = 0 FACE_TEMPLATE_IMAGE = 1 FACE_RAW_IMAGE = 2 FACE_TEMPLATE_EX = 5 FACE_TEMPLATE_EX_IR = 6 FACE_TEMPLATE_EX_NORMALIZED = 7 FACE_TEMPLATE_EX_PICTURE = 8 Required if you are adding 'credentials:visualFaces' |
| ::templateEx | Raw | N | Visual Face template data which includes FaceStation F2 and the new BioStation 3. Required if you are adding 'credentials:visualFaces' and using BioStation 3 or FaceStation F2 |
| ::templateExIr | Raw | N | Visual Face IR template data, but only used in FaceStation F2 v1.x.x. The F2 v2.x.x and BioStation 3 does not use IR templates. Required if you are adding 'credentials:visualFaces' and using FaceStation F2 v1.x.x |
| :template_ex_picture | Base64 | N | Parameter for Upload Picture raw data Required if you are adding 'credentials:visualFaces' |
Part 2. Request Body & Response Model
[Input Example]
{ "User": { "name": "API2", "user_id": "108", "user_group_id": { "id": 1, "name": "All Users" }, "disabled": "false", "start_datetime": "2001-01-01T00:00:00.00Z", "expiry_datetime": "2030-12-31T23:59:00.00Z", "login_id": "api23", "password": "PassWord@" } } |
[Response Example: Fail]
{ "Response": { "code": "202", "link": "https://support.supremainc.com/en/support/home", "message": "User who has same id already exists" } } |
[Response Example : Successful]
{ "UserCollection": { "total": "1", "rows": [ { "user_id": "108", "name": " API2" } ] }, "Response": { "code": "0", "link": "https://support.supremainc.com/en/support/home", "message": "Success" } } |
Part 3. Console Create User Example
This is a sample of Visual C# console application made for those who might need some guide for integrating the BioStar 2 New Local API.
You can simply copy & paste the source code to use the same function in your own integration.
[Create Users Method Source Code]
static async void CreateUserTask() { 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));
string resourceAddress = "https://127.0.0.1/api/users";
JavaScriptSerializer serializer = new JavaScriptSerializer(); Console.WriteLine("Enter USER NAME: "); string UserName = Console.ReadLine(); Console.WriteLine("Enter USER ID: "); string UserID = Console.ReadLine(); Console.WriteLine("Enter USER LOGIN ID: "); string User_login_id = Console.ReadLine(); Console.WriteLine("Enter USER LOGIN PASSWORD: "); string User_login_pw = Console.ReadLine();
string payload2 = "{ \"User\": "; payload2 = payload2 + "{\"name\": \"" + UserName + "\", "; payload2 = payload2 + "\"user_id\": \"" + UserID + "\","; payload2 = payload2 + "\"user_group_id\": { \"id\": 1, \"name\": \"All Users\" },\"disabled\": \"false\",\"start_datetime\": \"2001-01-01T00:00:00.00Z\", \"expiry_datetime\": \"2030-12-31T23:59:00.00Z\", "; payload2 = payload2 + "\"login_id\": \""+ User_login_id +"\", "; payload2 = payload2 + "\"password\": \"" + User_login_pw + "\"}}"; Console.WriteLine(payload2); StringContent sc = new StringContent(payload2, Encoding.UTF8, "application/json");
HttpResponseMessage httpResponse = httpClient.PostAsync(resourceAddress, sc).Result;
if (httpResponse.IsSuccessStatusCode == true) { Console.WriteLine("User has been created"); string httpResponseBody = await httpResponse.Content.ReadAsStringAsync(); Console.WriteLine(httpResponseBody); } else { Console.WriteLine("User Creation Failed"); Console.WriteLine(httpResponse.ToString()); } } |
[After Creating User Successfully]
Part 4. Create User via Postman
[Request Example: Headers]
*You must use the ‘be-session-id’ value from the response header of the Login API call to authenticate API use for other API calls.
[Request Example]
[Response Example: body]
