SaaS

1. Description

1.1 FaceCloud Overview

FaceSec's Facial Recognition Cloud Management Platform (titled "FaceCloud") is an open platform, allowing third parties/ISV to develop software and applications that can interact with it. Utilizing CMP's development API, third-party applications can easily utilize CMP's modules to accomplish tasks (such as editing personnel profiles, setting of new rules and data retrieval) and allow FaceSec's facial recognition devices and user applications to communicate with each other and better fulfill users' needs.

1.2 API Functionality Overview

The API enables developers to tap into the CMP's functionality to create new applications or integrate withi existing systems. For example, these functions can be developed through the API:

Retrieval of tenant details
Add/edit/delete personnel (and synchronize with devices)
Add/edit/delete personnel groups
Retrieve device information
Manage access rules
Retrieve identifcation logs
Upload personnel images
Set facial comparison parameters
And more.

2. API Revision History

New versions of interfaces are backwards compatible. If changes are made, please refer to the following revision log.

Update 2.6

Updated Interface	Update Type	Update Description
5.1.1. Retrieve tenant details	Edit	Changed request URL to: /bbox-service/api/admin/tenant
5.2.1. Retrieve personnel list	Addition	Added fingerprint parameters
5.2.3. Add new personnel	Edit	PersonDTO hiredate type is changed from Date to Long and features are added (use this attribute when avatars is empty). When adding personnel without including an organization ID, ordinary users will be randomly assigned an organization and special users will be placed under the root organization. When adding personnel, the person's photo features will not be extracted when the feature field contains a value.
5.2.4. Update personnel	Edit	When updating personnel, the type of organization before and after the update must be the same. When updating personnel, if the parameter is null, it will not update. When the parameter is "", it will update as empty. When updating personnel, image features will not be extracted when the feature has value.
5.3.2. Add organization	Edit	Added new organization type attribute. This attribute is not required when updating the organization.
6.2. Message format	Edit	Updated type parameter

Update 2.5

Updated Interface	Update Type	Update Description
3.1. Accessing public cloud deployment	Edit	Modified the deployment process for accessing the public cloud
5.2.2. Add rule	Edit	Added `passMode` type parameter
5.10.1 Retrieve individual device's administrator	Addition	Added an interface to get an individual device's administrator
5.10.2 Update device administrator	Addition	Added an interface to Update device administrator
5.10.3. Retrieve device administrator list	Addition	Added an interface to get a list of device administrators
5.10.4. Save device administrator	Addition	Added an interface to save device administrator
5.10.5 Delete device administrator	Addition	Added an interface to delete device administrator
5.10.6. Bind device administrator	Addition	Added an interface for binding device administrators
5.10.6. Unbind device administrator	Addition	Added an interface for unbinding device administrators
6.2. Message format	Edit	New type parameter

Update 2.3

Updated Interface	Update Type	Update Description
5.2.5. Add personnel pictures and information	Addition	Added new interface for adding personnel pictures and information
5.3.4. Retrieve organization details	Addition	Added an interface for obtaining organization details
5.3.5. Query list of sub-organizations based on the parent organization id, with pagination	Addition	Added an interface to query the list of sub-organizations based on the parent organization ID, with pagination
5.2.2. Get personnel information based on ID	Edit	Added response body `vftPwdFlag` field
5.2.3. Add new personnel	Edit	Added `imageSourceType` field
5.2.4. Update personnel	Edit	Added `imageSourceType` field
5.7.2. Batch image upload	Edit	Modified and added new request parameters
6.2. Message format	Edit	Modify and add new type parameter

Update 2.2.1

Updated Interface	Update Type	Update Description
5.2.1. Retrieve personnel list	Edit	The `ruleId` field in `PersonVo` response body is deprecated
5.2.2. Get personnel information based on id	Edit	The `ruleId` field in `PersonVo` response body is deprecated
5.5.14. Add device to rule	Edit	Support binding organization group's rules to the add devices interface
5.5.15. Remove device from rule	Edit	Support binding organization rules to delete devices

Update 2.2

Updated Interface	Update Type	Update Description
5.5.10. Add rules and bind personnel	Addition	Added an interface for adding of rules and binding of personnel
5.5.11. Update rule and bind personnel	Addition	Added an interface to modify rules and bind personnel
5.5.12. Add personnel to rules	Addition	Added an interface to add personnel to rules
5.5.13. Delete personnel from rules	Addition	Added an interface for deleting personnel from rules
5.5.14. Add device to rule	Addition	Added an interface to bind device to rule
5.5.15. Remove device from rule	Addition	Added an interface to unbind device from rule
5.8. Facial Recognition Management Interface	Edit	Modified the paths and return values of all facial recognition interfaces
5.9. Device Group Management Interface	Addition	Added an interface for device group management

Update 2.1

Updated Interface	Update Type	Update Description
5.3 Organization Management Interface	Addition	Added an interface for organization management
5.4. Device Management Interface>	Addition	Added an interface for device management
5.5.1. Retrieve rule list	Update	Added parameters `deviceSns, deviceVisible, saasVisible, deviceUpdateTime`
5.5.2. Add rule	Update	Add `deviceSns, deviceVisible, saasVisible` fields to `Rule`
5.7.1. Single image upload (deprecated)	Remove	2.1 Deprecated the single photo upload interface
5.7.2. Batch image upload	Addition	Added an interface to upload frontal photos, to replace the single photo upload inteface
5.8. Facial Recognition Management Interface	Addition	Added an interface for facial recognition

3. API Access Procedure

The developer should first confirm whether the connected CMP is the FaceSec public cloud platform or on another private deployment platform. If it is connected to the FaceSec public cloud platform, refer to 3.1. Accessing public cloud deployment. For private cloud deployment, refer to 3.2 Accessing private cloud deployment. After deployment, developers will be asked to choose a docking method. FaceSec provides two docking methods: client credential license, which can directly call the REST interface, and authorization code license that can integrate applications into the platform.

3.1. Accessing public cloud deployment

Access to the public cloud for CMP deployment requires a tenant account. Please contact sales and apply for an account, using the following template:


Account name: xxxx
Account password: xxxx
Customer contact name: xxxx
Customer contact email: xxxx
Customer contact phone number: xxxx
Project name or the name of the company that opened the account: xxxx
Industry: xxxx
Region: xxxx
Sales policy: xxxx
Account start date: xxxx
Account expiry: xxxx
Sales contact: xxxx
Sales contact phone: xxxx
Account applicant: xxxx
Remarks: xxxx

After the application is completed, use the tenant account to log in to https://cloud.facesec.com (FaceSec public CMP). To create an application authorization call interface, please refer to 3.2 Accessing private cloud deployment

3.2 Accessing private cloud deployment

To access the private cloud for CMP deployment, you will need to apply for an application ID (subsequently referred to as app_id). Please use the super-administrator account to log in to the CMP and click "Create Application ID" under (Application Management > Application Authorization), as shown:

Field	Description
App ID	Apply for application authorization to obtain this token
Application name	Application name
Place on desktop	"Yes" means it will be displayed on the desktop page of the CMP, "No" means it will not be displayed on the desktop page of the CMP
3rd party application address	Home page address of third-party platform application
Secure_key	Used to encrypt with `app_id` to obtain token
Push_key	Used to verify the authenticity of push messages. If you need to receive the identification records, you will need to fill in the push address and push event type after generation, otherwise it will not be generated. Note: Public cloud test accounts should avoid generating, to avoid errors where the push address is unavailable.
Push address	Addresses for receiving identification record messages
Push event type	Message type

Push event types

Type	Description
ACCESS_RECORD_ADD	Added identification records
PERSON_ADD	Personnel added
PERSON_UPDATE	Personnel updated
PERSON_DELETE	Personnel deleted
RULE_ADD	Rule added
RULE_UPDATE	Rule updated
RULE_DELETE	Rule deleted
DEVICE_ACTIVE	Device reconnected
DEVICE_INACTIVE	Device disconnected
DEVICE_RECOVERY	Device restored to factory settings
DEVICE_INFO_UPDATE	Device information update
ORGANIZATION_ADD	Organization added
ORGANIZATION_UPDATE	Organization updated
ORGANIZATION_DELETE	Organization deleted

The platform can generate randomized application ID, Secure_key and Push_key codes. Applications created in this way support both authorization code authorization and client credential authorization.

3.3 Authorization Code License

After authorization code license application is complete, it will be displayed on the CMP desktop. Entering the application will start the authorization process. The authorization process is as follows:

3.4 Client Credential Token

A client credential token allows third-party applications to call the CMP interface through its REST interface. The call process flow is detailed below:

（1）app_id and secure_key are used as credentials for each token acquisition.

（2）A third-party application uses app_id and secure_key to request an access token from the CMP. The token has a validity period and will be checked for validity to ensure security. If expired, the token will need to be refreshed.

(3) The CMP API can be accessed after the third-party application obtains the token.

Since the CMP hosts multiple tenants, the tenant ID will need to be included in interface calls. This type of authorization provides the greatest degree of freedom for third-party applications, and will require an authentication protocol.

4. API Access Protocol Description

The CMP uses the OAuth2 protocol standard for interface calls. The following is an example of the OAuth protocol call:

4.1 Handshake Protocol Procedure


xxxxxxxxxx
     +--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+

To learn more about OAuth2.0, please visit https://oauth.net/2/.

4.2 Obtain authorization token for interface access

All methods using the authorization token must call this process to be authenticated.

Interface name	Request authorization interface
Address template	/oauth2/authorize
Request method	GET
Brief description	Located in process A and B of Section 3.1. When an application needs to access user information, or needs to access the system API as a user, it needs to obtain user authorization through this interface
Request example	https://api.kaioh.com/oauth2/authorize?app_id=test&response_type=code&redirect_uri=https%3A%2F%2Fwww.test.com%2Fcheck&state=abc

Request parameter

Parameter name	Type	Required	Maximum length	Description
app_id	string	Yes	10	The application ID assigned by the authorization server to the third party.
response_type	string	Yes	N/A	Optional values are: `token` (return access token directly) and `code` (return authorization code), currently only `code` is supported.
redirect_uri	string	No	N/A	`urlencode` is required. This parameter is optional only when the client has registered a redirect address in the authorization server in advance. When the address is not registered or multiple addresses are registered, this parameter must be passed.
scope	string	No	N/A	For application access, this parameter does not need to be passed in since access scope permissions will be assigned by the system.
state	string	No	N/A	Client-defined parameters, the authorization server will pass to the redirection address of the client as-is

Response

Status Cause

Success Response When the authorization process is successful (normally through interacting with the user center, requiring users to log in and clicking the Authorize button, etc.), the authorization server will redirect to the client's redirect_uri and acquire the token or code (license key). Currently, the system does not support token (implicit license) type, due to potential security issues (Needing to splice in the url, which is not secure. Only consider this method if and only if the code (license authorization code) is not available), will redirect users to https://www.test.com/check?code=afgewfsdfgwefdfg&state=abc

Error response Will redirect the user to https://www.test.com/check?error={errorCode}&error_description=app_id&state=abcThe value of errorCode may be:
invalid_request:Required request parameter is missing, or it contains an invalid parameter value, a repeated parameter, or a bad format.
unauthorized_client:Required request parameter is missing, or it contains an invalid parameter value, a repeated parameter, or a bad format.
acess_denied:The resource owner or authorization server rejected the request.
unsupported_response_type:The authorization server does not support using this method to obtain an authorization code.
invalid_scope:The scope is invalid, unknown or incorrectly formatted.
server_error:The authorization server encountered an unexpected exception that prevented it from performing the request. (This error code is necessary because the 500 internal server error HTTP status code cannot be returned to the client by HTTP redirection)
temporarily_unavailable: The authorization server is currently unable to process the request due to temporary overload or server maintenance. (This error code is necessary because the 503 service unavailable HTTP status code cannot be returned to the client by HTTP redirection).

Status	Cause
Success Response	When the authorization process is successful (normally through interacting with the user center, requiring users to log in and clicking the Authorize button, etc.), the authorization server will redirect to the client's redirect_uri and acquire the token or code (license key). Currently, the system does not support token (implicit license) type, due to potential security issues (Needing to splice in the url, which is not secure. Only consider this method if and only if the code (license authorization code) is not available), will redirect users to `https://www.test.com/check?code=afgewfsdfgwefdfg&state=abc`
Error response	Will redirect the user to `https://www.test.com/check?error={errorCode}&error_description=app_id&state=abc`The value of errorCode may be: `invalid_request:`Required request parameter is missing, or it contains an invalid parameter value, a repeated parameter, or a bad format. `unauthorized_client:`Required request parameter is missing, or it contains an invalid parameter value, a repeated parameter, or a bad format. `acess_denied:`The resource owner or authorization server rejected the request. `unsupported_response_type:`The authorization server does not support using this method to obtain an authorization code. `invalid_scope:`The scope is invalid, unknown or incorrectly formatted. `server_error:`The authorization server encountered an unexpected exception that prevented it from performing the request. (This error code is necessary because the 500 internal server error HTTP status code cannot be returned to the client by HTTP redirection) `temporarily_unavailable:` The authorization server is currently unable to process the request due to temporary overload or server maintenance. (This error code is necessary because the 503 service unavailable HTTP status code cannot be returned to the client by HTTP redirection).

4.3 Obtain token for interface access

Interface name	Obtain token for interface access
Address template	/oauth2/token
Request method	POST
Brief description	The handshake procedure between the endpoint and the client. The endpoint needs to verify the identity of the client, which the client needs to provide credentials for. Currently HTTP Basic authentication is used (reliant on HTTPS to provide transfer security, and the OAuth2 protocol required Basic authentication to be supported). When making requests using client credentials, headers should include the Basic authentication header. For example: `Authorization Basic base64 (app_id: secure_key) (code style request headers only need to transfer this), Content-Type: application/x-www-form-urlencoded` Additional parameters, such as `grant_type, app_id` and `tenant_id`, should be written in the Body, formatted as `x-www-form-urlencoded`
Request parameter	Parameter nameTypeRequiredMaximum lengthDescriptiongrant_typestringYesN/ACan be set as `authorization_code` (Authorization code), `client_credentials` (Client credentials), `password` (User password), `refresh_token` (Refresh token). Currently supported methods are `authorization_code, client_credentials, refresh_token`.app_idstringYesN/AWhen `grant_type` is `authorization_code, client_credentials, refresh_token`, this parameter must be passed.codestringNo32When `grant_type` is `authorization_code`, this parameter must be passed.redirect_uristringNoN/AThe redirect address. When `grant_type` is `authorization_code`, this parameter must be passed. The same parameters must be used to request the authorization initiation.scopestringNoN/AFor the accessing applications, the access scope permissions will be assigned by the system, and this parameter does not need to be passed inusernamestringNo50When `grant_type` is `password`, this parameter must be passedpasswordstringNo32When `grant_type` is `password`, this parameter must be passedrefresh_tokenstringNoN/AWhen `grant_type` is `refresh_token`, this parameter must be passedtenant_idstringNoN/AWhen `grant_type` is `client_credentials`, this parameter must be passed
Request example	POST https://api.kaioh.com/oauth2/token?grant_type=authorization_code&code=xxx-xxx-xxx&app_id=10001&redirect_uri=https://www.test.com/check
Response	CauseSuccess ResponseParameter nameTypeDescriptionaccess_tokenstringAccess tokentoken_typestringToken type. Currently only bearer type is supportedrefresh_tokenstringWhen the refresh token permission is granted, the refresh token will be issued together with the access_token.expires_innumberThe token validity period, in seconds. It will expire after expires_in, defined in seconds.Example:`{ "access_token":"eyJ0b2tlblR5cGUiOiJiZWFyZXIi....", "token_type":"bearer", "refresh_token": "e57b6316-d0af-4f10-928b-32b41bb79fc0", "expires_in":1799 }`Error responseError codeError descriptioninvalid_requestMissing required parameters or contains unsupported parameter values (except for the license type), or duplicate parameters, or contains multiple credentials, or uses more than one client authentication mechanism, or invalid format.invalid_clientClient authentication failed (e.g. unknown client, client authentication is not included, or an authentication method that is not supported). The authorization server can return an `HTTP 401 (Unauthorized)` status code to indicate the supported HTTP authentication scheme. If the client tries to use "Authorization" request header or attempts to start authentication, the authorization server must respond with `HTTP 401 (Unauthorized)` status code. The reply will also containing the authentication scheme used by the client matches the `WWW-Authenticate` response header field.invalid_grantThe credentials (such as authorization code, resource owner credentials) or refresh token provided is invalid, expired, revoked, does not match the redirect URI used in the authorization request, or is issued to another client.unauthorized_clientThe client attempting authentication is not authorized to use this authentication method.unsupported_grant_typeThe credential type is not supported by the authentication server.invalid_scopeThe request scope is invalid or unknown or incorrectly formatted, or outside the scope permitted by the resource owner.Example:`HTTP1.1 /token 400 { "error":"invalid_client", "error_description":"authorization fail" }`

Request parameter

Parameter name	Type	Required	Maximum length	Description
grant_type	string	Yes	N/A	Can be set as `authorization_code` (Authorization code), `client_credentials` (Client credentials), `password` (User password), `refresh_token` (Refresh token). Currently supported methods are `authorization_code, client_credentials, refresh_token`.
app_id	string	Yes	N/A	When `grant_type` is `authorization_code, client_credentials, refresh_token`, this parameter must be passed.
code	string	No	32	When `grant_type` is `authorization_code`, this parameter must be passed.
redirect_uri	string	No	N/A	The redirect address. When `grant_type` is `authorization_code`, this parameter must be passed. The same parameters must be used to request the authorization initiation.
scope	string	No	N/A	For the accessing applications, the access scope permissions will be assigned by the system, and this parameter does not need to be passed in
username	string	No	50	When `grant_type` is `password`, this parameter must be passed
password	string	No	32	When `grant_type` is `password`, this parameter must be passed
refresh_token	string	No	N/A	When `grant_type` is `refresh_token`, this parameter must be passed
tenant_id	string	No	N/A	When `grant_type` is `client_credentials`, this parameter must be passed

Response

Success Response

Parameter name	Type	Description
access_token	string	Access token
token_type	string	Token type. Currently only bearer type is supported
refresh_token	string	When the refresh token permission is granted, the refresh token will be issued together with the access_token.
expires_in	number	The token validity period, in seconds. It will expire after expires_in, defined in seconds.

Example:


xxxxxxxxxx
{
    "access_token":"eyJ0b2tlblR5cGUiOiJiZWFyZXIi....",
    "token_type":"bearer",
    "refresh_token": "e57b6316-d0af-4f10-928b-32b41bb79fc0",
    "expires_in":1799
}

Error response

Error code	Error description
invalid_request	Missing required parameters or contains unsupported parameter values (except for the license type), or duplicate parameters, or contains multiple credentials, or uses more than one client authentication mechanism, or invalid format.
invalid_client	Client authentication failed (e.g. unknown client, client authentication is not included, or an authentication method that is not supported). The authorization server can return an `HTTP 401 (Unauthorized)` status code to indicate the supported HTTP authentication scheme. If the client tries to use "Authorization" request header or attempts to start authentication, the authorization server must respond with `HTTP 401 (Unauthorized)` status code. The reply will also containing the authentication scheme used by the client matches the `WWW-Authenticate` response header field.
invalid_grant	The credentials (such as authorization code, resource owner credentials) or refresh token provided is invalid, expired, revoked, does not match the redirect URI used in the authorization request, or is issued to another client.
unauthorized_client	The client attempting authentication is not authorized to use this authentication method.
unsupported_grant_type	The credential type is not supported by the authentication server.
invalid_scope	The request scope is invalid or unknown or incorrectly formatted, or outside the scope permitted by the resource owner.

Example:


xxxxxxxxxx
HTTP1.1 /token 400
{
    "error":"invalid_client",
    "error_description":"authorization fail"
}

4.4 Access API interface description

The application needs to add the following parameters in the header:

HTTP header name	HTTP header value	Description
Authorization	Bearer {access_token}	Retrieved through 4.3 Obtain token for interface access
TenantId	0001	Tenant ID (Required when using typed authorization)

When accesstoken verification fails, the server responds with a HTTP 401 (Unauthorized) status code. TenantId represents the ID of the tenant. The TenantId can be retrieved from the User Information tab on the upper right corner of the desktop, after logging into the CMP.

5. API Interface Description

5.1. Tenant interface

Used to retrieve some tenant details

5.1.1. Retrieve tenant details

Retrieve tenant details

Summary

Request URL：/bbox-service/api/admin/tenant
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/admin/tenant

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Tenant»>	OK

Response body: CommonResponse«Tenant»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<Tenant>	Included objects
message	string	Yes		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Response body: Tenant

Tenant object

Field	Type	Required	Description
businessType	int	No	Business type
contact	string	No	Tenant contact
contactPhone	string	No	Tenant contact no.
countryCode	int	No	Area code
email	string	No	Tenant contact email
id	long	No	Tenant ID
loginName	string	No	Superuser login account
name	string	No	Tenant name

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545983387434,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 11,
                "loginName": "facesec_admin",
                "tenantId": 4,
                "isRoot": true,
                "status": 1,
                "email": "support@facesec.com",
                "phone": "",
                "createTime": 1545973967027,
                "tenant": {
                    "id": 4,
                    "name": "FaceSec",
                    "businessType": 0,
                    "countryCode": 0,
                    "contact": "R&D",
                    "contactPhone": "",
                    "loginName": "facesec_admin",
                    "email": "support@facesec.com"
                }
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.2. Personnel Management Interface

Management of personnel details, which can be sent to devices

5.2.1. Retrieve personnel list

Retrieve personnel list

Summary

Request URL：/bbox-service/api/person/page
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/person/page?name=张&no=1&page=0&size=10&sort=name,desc&organizationId=1

Request parameters

Field	Parameter position	Type	Required	Description
name	query	string	false	Personnel name
no	query	string	false	Personnel no.
organizationId	query	integer	false	Organization ID
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
sort	query	string	false	Sorting rules (e.g. `?sort=version,updateTime,asc&sort=name,desc`)

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«PersonVo»»>	OK

Response body: CommonResponse«Page«PersonVo»»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<Page«PersonVo»>	Included objects
message	string	Yes		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Response body: Page«PersonVo»

Field	Type	Required	Structure	Description
content	array	No	<PersonVo>	Content
first	boolean	Yes		Is first page
last	boolean	Yes		Is last page
number	int	Yes		Current page
numberOfElements	int	Yes
size	int	Yes		Number of items on each page
sort	undefined	No		Sort
totalElements	long	Yes		Total items
totalPages	int	Yes		Total pages

Response body: PersonVo

PersonnelVo entity

Field	Type	Required	Description
appId	string	No	Application ID
avatars	object	No	Image
createTime	int	No	Creation time
groupId	string	No	Parameter ID
hiredate	string	No	Hire date
icNumber	string	No	IC card no.
id	string	No	id
idCard	string	No	Identity card no.
mail	string	No	Email
name	string	No	Name
no	string	No	No.
operatorId	long	No	Administrator ID
operatorName	string	No	Administrator
organization	string	No	Organization name
organizationId	int	No	Organization ID
fingerprint	boolean	No	Are fingerprints stored
phone	string	No	Mobile
position	string	No	Position
remark	string	No	Remarks
sex	string	No	Gender: `MALE`, `FEMALE`
syncStatus	string	No	Synchronization status `DATA_DEFAULT` Default. No synchronization needed `DATA_NOT_SYNC` Not synchronized `DATA_ALREADY_SYNC` Already synchronized
syncVersion	long	No	Synchronization version
tenantId	long	No	Tenant ID
type	string	No	Type
updateTime	int	No	Update time
variable	object	No	Optional field
wgNumber	string	No	Wiegand No.

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": {
                "content": [
                    {
                        "avatars": {
                            "VISIBLE_LIGHT": [
                                "https://172.16.20.30/ocfs/file/download/Z3JvdXAxL00wMC8xMC85Qi9yQkFVSGx0VnJ2bUFHN1VyQUFEQjcxWl9WcG82MDkuanBn"
                            ]
                        },
                        "groupId": "paramDB0",
                        "icNumber": "2345yuhgf",
                        "id": "2aa3956080a54d8dbcad7221f6db6e05",
                        "idCard": "130123123412121234",
                        "mail": "test@123.com",
                        "name": "Mark1977",
                        "no": "10013977",
                        "organization": "FaceSectianzc",
                        "organizationId": 102,
                        "password": "123.com",
                        "phone": "18512340001",
                        "position": "Position",
                        "sex": "MALE",
                        "type": "FREQUENTER",
                        "updateTime": 1532414453000,
                        "variable": {},
                        "wgNumber": "323"
                    }
                ],
                "first": true,
                "last": true,
                "number": 0,
                "numberOfElements": 1,
                "size": 10,
                "totalElements": 1,
                "totalPages": 1
            },
            "message": "success",
            "path": "",
            "status": 200,
            "timestamp": 1531200287758
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.2.2. Retrieve personnel details via ID

Retrieve personnel via ID

Summary

Request URL：/bbox-service/api/person/{id}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/person/f7852a8ba69b42afa2b6f502bbcc7f78

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
id	path	string		true		id

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Person»>	OK

Response body: CommonResponse«Person»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<Person>	Included objects
message	string	Yes		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Response body: Person

Personnel entity

Field	Type	Required	Description
appId	string	No	Application ID
avatars	object	No	Image
createTime	int	No	Creation time
groupId	string	No	Feature library
hiredate	string	No	Hire date
icNumber	string	No	IC card no.
id	string	No	id
idCard	string	No	Identity card no.
mail	string	No	Email
name	string	Yes	Name
no	string	Yes	No.
vftPwdFlag	boolean	Yes	Is verification password present (`true` if present, `false` if absent)
openId	string	No	Open ID
operatorId	long	No	Operator ID
operatorName	string	No	Operator
organizationId	int	No	Organization ID
password	string	No	Password
verificationPassword	string	No	Verification password
phone	string	No	Mobile
position	string	No	Position
remark	string	No	Remarks
sex	string	No	Gender: `MALE`, `FEMALE`
syncStatus	string	No	Synchronization status `DATA_DEFAULT` Default. No synchronization needed `DATA_NOT_SYNC` Not synchronized `DATA_ALREADY_SYNC` Already synchronized
syncVersion	long	No	Synchronization version
tenantId	long	No	Tenant ID
type	string	No	Personnel type
updateTime	int	No	Update time
variable	object	No	Addition field
wgNumber	string	No	Wiegand No.

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545198746304,
            "status": 200,
            "code": 0,
            "entity": {
                "id": "72b089f28cb74e67b67983992d2e349a",
                "name": "test",
                "no": "test",
                "password": "123.com",
                "sex": "MALE",
                "idCard": "101010201812192020",
                "phone": "13100010001",
                "position": "test position",
                "mail": "test@test.com",
                "icNumber": "222",
                "wgNumber": "test wgnumber",
                "organizationId": 7,
                "syncVersion": 1545198746287,
                "hiredate": 1543852800000,
                "groupId": "116079edb4d54d95859881d956759650",
                "remark": "2",
                "createTime": 1545198746298,
                "updateTime": 1545198746298,
                "tenantId": 1,
                "operatorId": 1,
                "operatorName": "superadmin",
                "appId": "test",
                "variable": {
                    "VARIABLE5": "test",
                    "VARIABLE6": "test",
                    "VARIABLE3": "test",
                    "VARIABLE4": "test",
                    "VARIABLE1": "test",
                    "VARIABLE2": "test"
                },
                "avatars": {
                    "VISIBLE_LIGHT": [
                        "https://172.16.20.220/ocfs/file/download/Z3JvdXAxL00wMC8wNS9BQy9yQkFVM0Z3WjJ5NkFXTkd5QUFCRmNTYUJLYVUxMjkuanBn"
                    ]
                },
                "type": "FREQUENTER"
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.2.3. Add new personnel

Add new personnel

Summary

Request URL：/bbox-service/api/person/save
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/person/save
        {
            "no": "test",
            "hiredate": "2018-12-03T16:00:00.000Z",
            "name": "test",
            "icNumber": "222",
            "sex": "MALE",
            "organizationId": 7,
            "groupId": "116079edb4d54d95859881d956759650",
            "idCard": "101010201812192020",
            "mail": "test@test.com",
            "phone": "13100010001",
            "remark": "2",
            "position": "test position",
            "wgNumber": "test wgnumber",
            "features": {
            "VISIBLE_LIGHT": [
              {
                "base64Vectors": "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",
                "version": "7.2"
              }
            ]
          },
            "avatars": {
                "VISIBLE_LIGHT": [
                    "https://172.16.20.220/ocfs/file/download/Z3JvdXAxL00wMC8wNS9BQy9yQkFVM0Z3WjJ5NkFXTkd5QUFCRmNTYUJLYVUxMjkuanBn"
                ]
            },
            "variable": {
                "VARIABLE1": "test",
                "VARIABLE2": "test",
                "VARIABLE3": "test",
                "VARIABLE4": "test",
                "VARIABLE5": "test",
                "VARIABLE6": "test"
            },
            "password": "123.com"
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
PersonDTO	body	ref		true	<PersonDTO>	PersonDTO

Request body: PersonDTO

Personnel request body

Field	Type	Required	Structure	Description
avatars	object	No		Image
name	string	Yes		Name (Length between 1-64 characters, special characters not allowed.)
no	string	Yes		No. (Length between 1-20 characters. Limited to numbers, letters, underscores and dashes. Must be unique.)
feature	ref	No	<Feature>	Map<String,List>，Key value range：`VISIBLE_LIGHT`, `NEAR_INFRARED`
groupId	string	No		Feature library
hiredate	long	No		Hire date, formatted as YYYY-MM-DD. Response body is timestamp, or request body with timestamp.
icNumber	string	No		IC card no. (Length between 0-32 characters, special characters not allowed.)
idCard	string	No		Identity card no. (Length between 0-32 characters, special characters not allowed.)
imageSourceType	DEFAULT	No		Image source `DEFAULT` (Default) `THIRD_PARTY` (Third-party address)
mail	string	No		Email (Length between 4-64 characters, special characters not allowed.)
organizationId	int	No		Organization ID
password	string	No		Password (Length between 6-20 characters, special characters not allowed.)
fingerprint	boolean	No		Are fingerprints stored
verificationPassword	string	No		Verification password (Length between 6-20 characters, special characters not allowed.)
phone	string	No		Phone (Length between 4-64 characters, special characters not allowed.)
position	string	No		Position (Length between 0-64 characters, special characters not allowed.)
remark	string	No		Remarks (Length between 0-256 characters)
sex	string	No		Gender: `MALE`, `FEMALE`
variable	object	No		Additional field (Length between 0-32 characters, up to 10 can be created.)
wgNumber	string	No		Wiegand No. (Length between 0-32 characters, special characters not allowed.)

Request body: Feature

undefined

Field	Type	Required	Description
imageURL	string	No	Image address
version	string	Yes	Algorithm version
base64Vectors	string	Yes	Feature value (base64 format)

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Person»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545198746304,
            "status": 200,
            "code": 0,
            "entity": {
                "id": "72b089f28cb74e67b67983992d2e349a",
                "name": "test",
                "no": "test",
                "password": "123.com",
                "sex": "MALE",
                "idCard": "101010201812192020",
                "phone": "13100010001",
                "position": "test position",
                "mail": "test@test.com",
                "icNumber": "222",
                "wgNumber": "test wgnumber",
                "organizationId": 7,
                "syncVersion": 1545198746287,
                "hiredate": 1543852800000,
                "groupId": "116079edb4d54d95859881d956759650",
                "remark": "2",
                "createTime": 1545198746298,
                "updateTime": 1545198746298,
                "tenantId": 1,
                "operatorId": 1,
                "operatorName": "superadmin",
                "appId": "test",
                "variable": {
                    "VARIABLE5": "test",
                    "VARIABLE6": "test",
                    "VARIABLE3": "test",
                    "VARIABLE4": "test",
                    "VARIABLE1": "test",
                    "VARIABLE2": "test"
                },
                "avatars": {
                    "VISIBLE_LIGHT": [
                        "https://172.16.20.220/ocfs/file/download/Z3JvdXAxL00wMC8wNS9BQy9yQkFVM0Z3WjJ5NkFXTkd5QUFCRmNTYUJLYVUxMjkuanBn"
                    ]
                },
                "type": "FREQUENTER"
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.2.4. Update personnel

Update personnel via ID

Summary

Request URL:/bbox-service/api/person/update/{id}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/person/update/f7852a8ba69b42afa2b6f502bbcc7f78
        {
            "no": "test",
            "hiredate": "2018-12-03T16:00:00.000Z",
            "name": "test",
            "icNumber": "222",
            "sex": "MALE",
            "organizationId": 7,
            "groupId": "116079edb4d54d95859881d956759650",
            "idCard": "101010201812192020",
            "mail": "test@test.com",
            "phone": "13100010001",
            "remark": "2",
            "position": "test position",
            "wgNumber": "test wgnumber",
            "features": {
            "VISIBLE_LIGHT": [
              {
                "base64Vectors": "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",
                "version": "7.2"
              }
            ]
          },
            "avatars": {
                "VISIBLE_LIGHT": [
                    "https://172.16.20.220/ocfs/file/download/Z3JvdXAxL00wMC8wNS9BQy9yQkFVM0Z3WjJ5NkFXTkd5QUFCRmNTYUJLYVUxMjkuanBn"
                ]
            },
            "variable": {
                "VARIABLE1": "test",
                "VARIABLE2": "test",
                "VARIABLE3": "test",
                "VARIABLE4": "test",
                "VARIABLE5": "test",
                "VARIABLE6": "test"
            },
            "password": "123.com"
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
id	path	string		true		Personnel ID
PersonDTO	body	ref		true	<PersonDTO>	PersonDTO

Response

Name	Type	Structure	Description
200	string		OK

5.2.5. Add personnel image and details

Add personnel image and details

Summary

Request URL:/bbox-service/api/person/increase
Request protocol:HTTPS
Request method:post
Request format:multipart/form-data
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/person/increase
-F "clearLevel=70&file=@7005.jpg;type=image/jpeg"

Request parameters

Field	Parameter position	Type	Required	Description
clearLevel	query	number	false	Assessed clarity level (0-100). Above 70 is considered blurred, otherwise, considered clear.
file	formData	number	true	Image
groupId	query	string	false	Feature library
hiredate	query	string	false	Hire date
icNumber	query	string	false	IC card no.
idCard	query	string	false	Identity card no.
imagePixel	query	string	false	Image resolution `THREE_TWO` (3232 px, cannot be lower than 32px) `ONE_TWO_EIGHT` (128128 px, cannot be lower than 128px) `THREE_TWO_ZERO` (320*320 px, cannot be lower than 320px)
mail	query	string	false	Email
name	query	string	true	Name
no	query	string	true	No.
organizationId	query	integer	false	Organization ID
password	query	string	false	Password
verificationPassword	query	string	false	Verification password
phone	query	string	false	Mobile
position	query	string	false	Position
qualityAngle	query	boolean	false	Whether to turn on the angle symbol
qualityDetect	query	boolean	false	Whether to turn on image evaluation. If activated, the four variables (`qualityAngle, clearLevel, visLevel, imagePixel`) must be filled in.
remark	query	string	false	Remarks
sex	query	string	false	Gender
visLevel	query	number	false	Occlusion (0-100). Values above 80 indicate subject is blocked. Otherwise, considered visible.
wgNumber	query	string	false	Wiegand No.

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Person»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545198746304,
            "status": 200,
            "code": 0,
            "entity": {
                "id": "72b089f28cb74e67b67983992d2e349a",
                "name": "test",
                "no": "test",
                "password": "123.com",
                "sex": "MALE",
                "idCard": "101010201812192020",
                "phone": "13100010001",
                "position": "test position",
                "mail": "test@test.com",
                "icNumber": "222",
                "wgNumber": "test wgnumber",
                "organizationId": 7,
                "syncVersion": 1545198746287,
                "hiredate": 1543852800000,
                "groupId": "116079edb4d54d95859881d956759650",
                "remark": "2",
                "createTime": 1545198746298,
                "updateTime": 1545198746298,
                "tenantId": 1,
                "operatorId": 1,
                "operatorName": "superadmin",
                "appId": "test",
                "variable": {
                    "VARIABLE5": "test",
                    "VARIABLE6": "test",
                    "VARIABLE3": "test",
                    "VARIABLE4": "test",
                    "VARIABLE1": "test",
                    "VARIABLE2": "test"
                },
                "avatars": {
                    "VISIBLE_LIGHT": [
                        "https://172.16.20.220/ocfs/file/download/Z3JvdXAxL00wMC8wNS9BQy9yQkFVM0Z3WjJ5NkFXTkd5QUFCRmNTYUJLYVUxMjkuanBn"
                    ]
                },
                "type": "FREQUENTER"
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.2.6. Delete personnel

Batch delete personnel via ID

Summary

Request URL:/bbox-service/api/person/delete
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/person/delete
        
["94fb50f31f484278886ec83a44451ca6","f7852a8ba69b42afa2b6f502bbcc7f78"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
ids	body	array		true	[String]	Personnel ID set

Response

Name	Type	Structure	Description
200	string		OK

5.3.Organization Management Interface

Organizations are used as a collection of personnel, to help simplify bulk operations

5.3.1. Organization Structure

Retrieve organization structure (in tree structure)

Summary

Request URL:/bbox-service/api/org/node
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/org/node

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description

Response

Name	Type	Structure	Description
200	ref	<ResponseEntity«OrgVo»>	OK

Response body: ResponseEntity«OrgVo»

Field	Type	Required	Structure	Description
status	string	Yes		Status code
code	int	Yes		Request response code
entity	array	No	<OrgVo>	Response entity details
timestamp	long	Yes		Timestamp

Response body: OrgVo

Organization

Field	Type	Required	Structure	Description
id	int	No		id
name	string	Yes		Organization name
parentId	int	Yes		Parent organization ID
remark	string	No		Remarks
orgType	string	No		Organization type
disabled	boolean	No		Active
createTime	int	No		Creation time
updateTime	int	No		Update time
childNodes	array	No	<OrgVo>	Suborganizations

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545896186529,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "id": 1,
                    "name": "Avengers",
                    "parentId": -1,
                    "orgType": "SAAS",
                    "disabled": false,
                    "createTime": 1544079274000,
                    "updateTime": 1544079274000,
                    "childNodes": [
                        {
                            "id": 6,
                            "name": "test",
                            "parentId": 1,
                            "orgType": "SAAS",
                            "disabled": false,
                            "createTime": 1544253402000,
                            "updateTime": 1544253402000,
                            "childNodes": [
                                {
                                    "id": 7,
                                    "name": "Permission",
                                    "parentId": 6,
                                    "orgType": "SAAS",
                                    "disabled": false,
                                    "createTime": 1544253408000,
                                    "updateTime": 1544253408000,
                                    "childNodes": []
                                }
                            ]
                        },
                        {
                            "id": 15,
                            "name": "Valve",
                            "parentId": 1,
                            "orgType": "SAAS",
                            "disabled": false,
                            "createTime": 1545634428000,
                            "updateTime": 1545634428000,
                            "childNodes": []
                        },
                        {
                            "id": 17,
                            "name": "testOgdd",
                            "parentId": 1,
                            "orgType": "SAAS",
                            "disabled": false,
                            "createTime": 1545701551000,
                            "updateTime": 1545701551000,
                            "childNodes": []
                        },
                        {
                            "id": 18,
                            "name": "1",
                            "parentId": 1,
                            "orgType": "SAAS",
                            "disabled": false,
                            "createTime": 1545701598000,
                            "updateTime": 1545701598000,
                            "childNodes": [
                                {
                                    "id": 20,
                                    "name": "Test1226",
                                    "parentId": 18,
                                    "orgType": "SAAS",
                                    "disabled": false,
                                    "createTime": 1545880684000,
                                    "updateTime": 1545880684000,
                                    "childNodes": []
                                }
                            ]
                        }
                    ]
                }
            ]
        }
        Error response http status（400-599）
        {
            "timestamp": 1545894841247,
            "status": 400,
            "code": 104001,
            "message": "Error Message",
            "path": "/api/org/save"
        }

5.3.2. Add organization

Add organization

Summary

Request URL:/bbox-service/api/org/save
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/org/save
        {"name":"testOrga","parentId":1}

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
orgDTO	body	ref		true	<OrgDTO>	orgVo

Request body: OrgDTO

Organization

Field	Type	Required	Structure	Description
name	string	Yes		Organization name. (Length between 1-20 characters, special characters not allowed, must be unique.)
parentId	int	Yes		Parent organization ID

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Organization»>	OK

Response body: CommonResponse«Organization»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	ref	No	<Organization>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: Organization

Organization

Field	Type	Required	Description
createTime	int	No	Creation time
id	int	No	id
name	string	Yes	Organization name
operatorId	long	No	Operator ID
orgType	string	No	Organization type `SAAS` SaaS organization `OTHER` Other organizations Default is SaaS organization
parentId	int	Yes	Parent organization ID
tenantId	long	No	Tenant ID
updateTime	int	No	Update time

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545894801645,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 24,
                "parentId": 1,
                "tenantId": 1,
                "operatorId": 1,
                "name": "testOrga",
                "orgType": "SAAS",
                "createTime": 1545894801502,
                "updateTime": 1545894801502
            }
        }
        Error response http status（400-599）
        {
            "timestamp": 1545894841247,
            "status": 400,
            "code": 104001,
            "message": "Error Message",
            "path": "/api/org/save"
        }

5.3.3. Update Organization

Update organization via ID

Summary

Request URL:/bbox-service/api/org/update/{orgId}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/org/update/24
        {"name":"testOrga","parentId":1}

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
orgId	path	string		true		Organization ID to be updated
orgDTO	body	ref		true	<OrgDTO>	orgDTO

Response

Name	Type	Structure	Description
200	string		OK

5.3.4. Retrieve organization details

Retrieve organization details

Summary

Request URL:/bbox-service/api/org/{OrgId}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/org/1

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
orgId	path	integer		true		orgId

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Organization»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545894801645,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 24,
                "parentId": 1,
                "tenantId": 1,
                "operatorId": 1,
                "name": "testOrga",
                "orgType": "SAAS",
                "createTime": 1545894801502,
                "updateTime": 1545894801502
            }
        }
        Error response http status（400-599）
        {
            "timestamp": 1545894841247,
            "status": 400,
            "code": 104001,
            "message": "Error Message",
            "path": "/api/org/save"
        }

5.3.5. Search suborganizations via parent organization ID with pagination

Search suborganizations via parent organization ID with pagination

Summary

Request URL:/bbox-service/api/org/{orgid}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/org/1

Request parameters

Field	Parameter position	Type	Required	Description
orgId	query	integer	true	Organization ID
page	query	integer	false	Pagination, First page defaults to 0
size	query	integer	false	Number of pages
sort	query	integer	false	Sorting rule

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Organization»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545894801645,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 24,
                "parentId": 1,
                "tenantId": 1,
                "operatorId": 1,
                "name": "testOrga",
                "orgType": "SAAS",
                "createTime": 1545894801502,
                "updateTime": 1545894801502
            }
        }
        Error response http status（400-599）
        {
            "timestamp": 1545894841247,
            "status": 400,
            "code": 104001,
            "message": "Error Message",
            "path": "/api/org/save"
        }

5.3.6. Delete organization

Delete organization via ID and transfer its contents to a new group

Summary

Request URL:/bbox-service/api/org/{orgId}
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/org/1?targetOrgId=3&type=DEL_MOVE

Request parameters

Field	Parameter position	Type	Required	Description
orgId	path	integer	true	orgId
targetOrgId	query	integer	false	targetOrgId, required when `type` is `DEL_MOVE`, refers to the organization the current organization's contents will be transferred to upon deletion
type	query	string	true	type: `DEL_DIRECT`: immediate deletion; `DEL_MOVE`: delete and move its contents to organization referenced by targetOrgId

Response

Name	Type	Structure	Description
200	string		OK

5.4.Device Management Interface

Management of endpoint devices with access control, identification & other functionality

5.4.1. Retrieve device list

Retrieve device list

Summary

Request URL:/bbox-service/api/device/page
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/device/page?deviceAdminName=Bob&name=XIONG&groupId=3&page=0&size=10&sn=1&sort&status=DEVICE_OFF_LINE&type=DEVICE_TYPE_SINGLE_SCREEN

Request parameters

Field	Parameter position	Type	Required	Description
deviceAdminName	query	string	false	Device administrator name
groupId	query	integer	false	Device group ID
name	query	string	false	Device name
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
sn	query	string	false	Device serial no.
sort	query	string	false	Sorting order (e.g. `?sort=updateTime,desc`)
status	query	string	false	Device status (String type) Device disconnected `DEVICE_OFF_LINE` Device normal `DEVICE_RECOVERY`
type	query	string	false	Device type: Standing terminal `DEVICE_ONE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_ONE_ACCESS_CONTROL` Turnstile `DEVICE_ONE_GATE_MACHINE` Desktop terminal `DEVICE_ONE_DESKTOP_MACHINE` Standing terminal `DEVICE_TYPE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_TYPE_ACCESS_CONTROL` Turnstile `DEVICE_TYPE_GATE_MACHINE` Desktop terminal `DEVICE_TYPE_DESKTOP_MACHINE` Camera `TYPE_DYNAMIC_CAMERA` Kiosk `TYPE_SELF_SERVICE_TERMINAL` Digital signage `TYPE_DIGITAL_SIGNAGE`

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«DeviceVo»»>	OK

Response body: CommonResponse«Page«DeviceVo»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	ref	No	<Page«DeviceVo»>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: Page«DeviceVo»

Field	Type	Required	Structure	Description
content	array	No	<DeviceVo>	Content
first	boolean	Yes		Is first page
last	boolean	Yes		Is last page
number	int	Yes		Current page
numberOfElements	int	Yes		Current page
size	int	Yes		Number of items on each page
sort	undefined	No		Sort
totalElements	long	Yes		Total items
totalPages	int	Yes		Total pages

Response body: DeviceVo

DeviceDTO

Field	Type	Required	Description
adminId	int	No
adminName	string	No	Device administrator
groupId	int	No
groupName	string	No	Device group
id	int	No
name	string	No	Device name
sn	string	No	Device serial no.
status	string	No	Device status (String type) Device disconnected `DEVICE_OFF_LINE` Device normal `DEVICE_RECOVERY`
type	string	No	Device type: Standing terminal `DEVICE_ONE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_ONE_ACCESS_CONTROL` Turnstile `DEVICE_ONE_GATE_MACHINE` Desktop terminal `DEVICE_ONE_DESKTOP_MACHINE` Standing terminal `DEVICE_TYPE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_TYPE_ACCESS_CONTROL` Turnstile `DEVICE_TYPE_GATE_MACHINE` Desktop terminal `DEVICE_TYPE_DESKTOP_MACHINE` Camera `TYPE_DYNAMIC_CAMERA` Kiosk `TYPE_SELF_SERVICE_TERMINAL` Digital signage `TYPE_DIGITAL_SIGNAGE`
updateTime	int	No	Update time
version	string	No	Device software version no.

Example response


xxxxxxxxxx
            Success response
        {
            "code": 0,
            "entity": {
              "content": [
                {
                  "adminId": 0,
                  "adminName": "string",
                  "groupId": 0,
                  "groupName": "string",
                  "id": 0,
                  "name": "string",
                  "sn": "string",
                  "status": "DEVICE_OFF_LINE",
                  "type": "DEVICE_ONE_SINGLE_SCREEN",
                  "updateTime": "2018-12-28T09:13:51.560Z",
                  "version": "string"
                }
              ],
              "first": true,
              "last": true,
              "number": 0,
              "numberOfElements": 0,
              "size": 0,
              "sort": {},
              "totalElements": 0,
              "totalPages": 0
            },
            "message": "string",
            "path": "string",
            "status": 0,
            "timestamp": 0
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.4.2. Retrieve device details

Retrieve device details via ID

Summary

Request URL:/bbox-service/api/device/{id}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
 https://172.16.20.30/bbox-service/api/device/2

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
id	path	integer		true		id

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«DeviceVo»>	OK

Response body: CommonResponse«DeviceVo»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	ref	No	<DeviceVo>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1546943524198,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 2,
                "sn": "LILI",
                "version": "123",
                "type": "DEVICE_TYPE_SINGLE_SCREEN",
                "status": "DEVICE_OFF_LINE",
                "groupId": 3,
                "groupName": "12",
                "updateTime": 1544863775000,
                "adminName": "Bob"
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.4.3. Door unlock request

Request the device to perform a temporary unlock of its associated door

Summary

Request URL:/bbox-service/api/device/door/{sn}/_open
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
 https://172.16.20.30/bbox-service/api/device/door/SN2018122101/_open

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
sn	path	string		true		sn

Response

Name	Type	Structure	Description
200	ref	<CommonResponse>	OK

5.4.4. Device reboot

Device reboot

Summary

Request URL:/bbox-service/api/device/_reboot
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/device/_reboot
["LILI","XIONG"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
snSet	body	array		true		snSet

Response

Name	Type	Structure	Description
200	ref	<CommonResponse>	OK

5.5.Rule Management Inteface

Rules refer to conditions which control which specified personnel will have access rights (or will be refused access) at a specified device within a specified timeframe

5.5.1. Retrieve rule list

Retrieve rule list, adding deviceSns, deviceVisible, saasVisible and deviceUpdateTime fields to the rules

Summary

Request URL:/bbox-service/api/rule/
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/?pageg=0&size=10&sort=name,desc&deviceVisible=0&saasVisible=0&name=新&type=0

Request parameters

Field	Parameter position	Type	Required	Description
deviceVisible	query	integer	false	Device visibility 0: hidden; 1: visible
saasVisible	query	integer	false	SaaS visibility 0: hidden; 1: visible
name	query	string	false	Name
type	query	integer	false	Rule type 0: Personnel rule; 1: Organization rule
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
sort	query	string	false	Sorting rule. `name, desc` will return results in reverse alphabetical order, not in reverse chronological order using updateTime

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«Rule»»>	OK

Response body: CommonResponse«Page«Rule»»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<Page«Rule»>	Included objects
message	string	No		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Response body: Page«Rule»

Rule object

Field	Type	Required	Structure	Description
content	array	No	<Rule>	Content
first	boolean	Yes		Is first page
last	boolean	Yes		Is last page
number	int	Yes		Current page
numberOfElements	int	Yes		Current page
size	int	Yes		Number of items on each page
sort	undefined	No		Sort
totalElements	long	Yes		Total items
totalPages	int	Yes		Total pages

Response body: Rule

Rule object

Field	Type	Required	Structure	Description
createBy	string	No		Creator
createTime	int	No		Creation time
description	string	No		Description (Length between 0-64 characters, special characters not allowed.)Special characters
deviceCount	int	No		Number of synchronized devices
name	string	Yes		Name (Length between 1-64 characters, special characters not allowed, must be unique
organizationIds	array	No	int	Organization ID set When `type` is set as 0, select between personIds and organizationIds When `type` is set as 1, this field is required
passMode	string	Yes		Access method `FACE` Facial scan `FACE_AND_ID` Facial scan + Identity card `FACE_AND_PASSPORT` Facial scan + Passport `FACE_AND_GUARD` Facial scan + Access card `FACE_AND_IC` Facial scan + IC card `QCODE` QR Code `SCANNING_GUN` Scanning device `FACE_AND_PASSWORD` Facial scan + Password
personCount	int	No		App user count
personIds	array	No	int	Personnel ID set Required when `type` is set as 0
status	string	No		Rule status: Normal: NORMAL Completed: FINISH
tenantId	long	No		Tenant ID
timeRule	array	Yes	<TimeRule>	Rule timeframe `timeRule[0].action` ALLOW (allow access), DENY (deny access) `timeRule[0].type` CYCLE (long-term), TIMING (custom) `timeRule[0].dayType` EVERYDAY (daily), CUSTOM (custom) `timeRule[0].customDays` When dayType is set to CUSTOM, parameters are days from Monday to Sunday. Example parameter: Calendar.SUNDAY `timeRule[0].dayRange` Date range (in years, months, days). When `type` is set as TIMING, this value is the date time period `timeRule[0].timeRange` Time range (in hours, minutes, seconds)
type	byte	Yes		Type 0: Personnel rule (default) 1: Organization rule
updateTime	int	No		Update time
validTill	string	No		Valid until

Response body: TimeRule

Rule timeframe object

Field	Type	Required	Structure	Description
action	string	Yes		Access method: ALLOW (allow access) DENY (deny access)
customDays	array	Yes	int	Selected days between Monday to Sunday 1: Sunday, 2: Monday, 3: Tuesday, 4: Wednesday, 5: Thursday, 6: Friday, 7: Saturday
dayRange	ref	Yes	<Range«Day»>	Date range (in year, month, day)
dayType	string	Yes		EVERYDAY (daily), CUSTOM (custom)
timeRange	ref	Yes	<Range«Time»>	Time period (in hours, minutes, seconds)
title	string	Yes		Name (Length between 1-20 characters, special characters not allowed, duplicates are not allowed within the same rule.)
type	string	Yes		CYCLE (long-term), TIMING (custom)

Response body: Range«Day»

Field	Type	Required	Structure	Description
end	ref	No	<Day>
start	ref	No	<Day>

Response body: Day

Field	Type	Required
day	int	Yes
mm	int	Yes
year	int	Yes

Response body: Range«Time»

Field	Type	Required	Structure	Description
end	ref	No	<Time>
start	ref	No	<Time>

Response body: Time

Field	Type	Required
hour	int	Yes
minute	int	Yes
second	int	Yes

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1546944370817,
            "status": 200,
            "code": 0,
            "entity": {
                "content": [
                    {
                        "id": 84,
                        "name": "NewRule3",
                        "description": "",
                        "type": 0,
                        "passMode": "FACE",
                        "timeRule": [
                            {
                                "title": "Custom",
                                "type": "TIMING",
                                "dayRange": {
                                    "start": {
                                        "year": 2018,
                                        "mm": 7,
                                        "day": 28
                                    },
                                    "end": {
                                        "year": 2019,
                                        "mm": 7,
                                        "day": 31
                                    }
                                },
                                "dayType": "CUSTOM",
                                "customDays": [
                                    1,
                                    7
                                ],
                                "timeRange": {
                                    "start": {
                                        "hour": 14,
                                        "minute": 30,
                                        "second": 32
                                    },
                                    "end": {
                                        "hour": 15,
                                        "minute": 30,
                                        "second": 32
                                    }
                                },
                                "action": "ALLOW"
                            }
                        ],
                        "createTime": 1545211774000,
                        "updateTime": 1545211774000,
                        "deviceUpdateTime": 1545211774000,
                        "createBy": "1",
                        "tenantId": 1,
                        "validTill": 1564558232000,
                        "saasVisible": 0,
                        "deviceVisible": 0,
                        "status": "NORMAL",
                        "personCount": 1,
                        "deviceCount": 0
                    }
                ],
                "totalElements": 1,
                "totalPages": 1,
                "last": true,
                "size": 10,
                "number": 0,
                "sort": [
                    {
                        "direction": "DESC",
                        "property": "name",
                        "ignoreCase": false,
                        "nullHandling": "NATIVE",
                        "ascending": false,
                        "descending": true
                    }
                ],
                "first": true,
                "numberOfElements": 1
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.2. Add new rule

Add rules, add deviceSns, deviceVisible and saasVisible fields

Summary

Request URL:/bbox-service/api/rule/
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule
        {
            "deviceVisible":1,
            "saasVisible":1,
            "deviceSns":["SN2018122101"],
            "description": "Test access rule - for testing purposes",
            "name": "Test access rule",
            "passMode": "FACE",
            "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
            "timeRule": [
                {
                    "action": "ALLOW",
                    "customDays": [
                        7,
                        1
                    ],
                    "dayRange": {
                        "end": {
                            "day": "31",
                            "mm": "7",
                            "year": "2019"
                        },
                        "start": {
                            "day": "28",
                            "mm": "7",
                            "year": "2018"
                        }
                    },
                    "dayType": "CUSTOM",
                    "timeRange": {
                        "end": {
                            "hour": "15",
                            "minute": "30",
                            "second": "32"
                        },
                        "start": {
                            "hour": "14",
                            "minute": "30",
                            "second": "32"
                        }
                    },
                    "title": "Custom",
                    "type": "TIMING"
                }
            ],
            "type": 0
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
rule	body	ref		true	<RuleDTO>	rule

Request body: RuleDTO

Rule

Field	Type	Required	Structure	Description
description	string	No		Description
deviceSns	array	No	string	Device group serial no. to send rule to
deviceVisible	int	No		On-device visibility 0: Hidden (default) 1: Visible
name	string	Yes		Name
organizationIds	array	No	integer	Organization ID set Required when `type` is 1
passMode	string	Yes		Access method `FACE` Facial scan `FACE_AND_ID` Facial scan + Identity card `FACE_AND_PASSPORT` Facial scan + Passport `FACE_AND_GUARD` Facial scan + Access card `FACE_AND_IC` Facial scan + IC card `QCODE` QR Code `SCANNING_GUN` Scanning device `FACE_AND_PASSWORD` Facial scan + Password
personIds	array	No	string	Personnel ID set Required when `type` is 0
saasVisible	int	No		Visible to SaaS 0: Hidden (default) 1: Visible
timeRule	array	Yes	<TimeRule>	Rule timeframe `timeRule[0].action` ALLOW (allow access), DENY (deny access) `timeRule[0].type` CYCLE (long-term), TIMING (custom) `timeRule[0].dayType` EVERYDAY (daily), CUSTOM (custom) `timeRule[0].customDays` When dayType is set to CUSTOM, parameters are days from Monday to Sunday. Example parameter: Calendar.SUNDAY `timeRule[0].dayRange` Date range (in years, months, days). When `type` is set as TIMING, this value is the date time period `timeRule[0].timeRange` Time range (in hours, minutes, seconds)
type	int	Yes		Type 0: Personnel rule; 1: Organization rule

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Rule»>	OK

Response body: CommonResponse«Rule»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	ref	No	<Rule>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545893213857,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 104,
                "name": "Test access rule",
                "description": "Test access rule - for testing purposes",
                "type": 0,
                "passMode": "FACE",
                "timeRule": [
                    {
                        "title": "Custom",
                        "type": "TIMING",
                        "dayRange": {
                            "start": {
                                "year": 2018,
                                "mm": 7,
                                "day": 28
                            },
                            "end": {
                                "year": 2019,
                                "mm": 7,
                                "day": 31
                            }
                        },
                        "dayType": "CUSTOM",
                        "customDays": [
                            1,
                            7
                        ],
                        "timeRange": {
                            "start": {
                                "hour": 14,
                                "minute": 30,
                                "second": 32
                            },
                            "end": {
                                "hour": 15,
                                "minute": 30,
                                "second": 32
                            }
                        },
                        "action": "ALLOW"
                    }
                ],
                "createTime": 1545893212998,
                "updateTime": 1545893212998,
                "deviceUpdateTime": 1545893212997,
                "createBy": "1",
                "tenantId": 1,
                "validTill": 1564558232994,
                "saasVisible": 1,
                "deviceVisible": 1,
                "status": "NORMAL",
                "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
                "deviceSns": [
                    "SN2018122101"
                ]
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.3. Get rule details from ID

Get rule details from ID

Summary

Request URL:/bbox-service/api/rule/{ruleId}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/10

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Rule»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545893213857,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 104,
                "name": "Test access rule",
                "description": "Test access rule - for testing purposes",
                "type": 0,
                "passMode": "FACE",
                "timeRule": [
                    {
                        "title": "Custom",
                        "type": "TIMING",
                        "dayRange": {
                            "start": {
                                "year": 2018,
                                "mm": 7,
                                "day": 28
                            },
                            "end": {
                                "year": 2019,
                                "mm": 7,
                                "day": 31
                            }
                        },
                        "dayType": "CUSTOM",
                        "customDays": [
                            1,
                            7
                        ],
                        "timeRange": {
                            "start": {
                                "hour": 14,
                                "minute": 30,
                                "second": 32
                            },
                            "end": {
                                "hour": 15,
                                "minute": 30,
                                "second": 32
                            }
                        },
                        "action": "ALLOW"
                    }
                ],
                "createTime": 1545893212998,
                "updateTime": 1545893212998,
                "deviceUpdateTime": 1545893212997,
                "createBy": "1",
                "tenantId": 1,
                "validTill": 1564558232994,
                "saasVisible": 1,
                "deviceVisible": 1,
                "status": "NORMAL",
                "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
                "deviceSns": [
                    "SN2018122101"
                ]
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.4. Update rule

Update rule

Summary

Request URL:/bbox-service/api/rule/{ruleId}
Request protocol:HTTPS
Request method:put
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/10
        {
            "deviceVisible":1,
            "saasVisible":0,
            "description": "Test access rule - for testing purposes",
            "name": "Test access rule",
            "passMode": "FACE",
            "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
            "timeRule": [
                {
                    "action": "ALLOW",
                    "customDays": [
                        7,
                        1
                    ],
                    "dayRange": {
                        "end": {
                            "day": "31",
                            "mm": "7",
                            "year": "2019"
                        },
                        "start": {
                            "day": "28",
                            "mm": "7",
                            "year": "2018"
                        }
                    },
                    "dayType": "CUSTOM",
                    "timeRange": {
                        "end": {
                            "hour": "15",
                            "minute": "30",
                            "second": "32"
                        },
                        "start": {
                            "hour": "14",
                            "minute": "30",
                            "second": "32"
                        }
                    },
                    "title": "Custom",
                    "type": "TIMING"
                }
            ],
            "type": 0
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
rule	body	ref		true	<RuleDTO>	rule
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.5. Delete rule

Delete rule

Summary

Request URL:/bbox-service/api/rule/{ruleId}
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/10

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.6. Retrieve details of personnel under a rule

Retrieve details of personnel under a rule/div>

Summary

Request URL:/bbox-service/api/rule/person/
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/person/
        ?ruleId=1&name=sdf&number=8&organizationId=1&page=0&size=10&sort=name,desc

Request parameters

Field	Parameter position	Type	Required	Description
name	query	string	false	Name
number	query	string	false	No.
organizationId	query	integer	false	Organization ID
ruleId	query	integer	true	Rule ID
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
sort	query	string	false	Sorting rule. `name, desc` will return results in reverse alphabetical order, not in reverse chronological order using updateTime

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«PersonVo»»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": {
                "content": [
                    {
                        "avatars": {
                            "VISIBLE_LIGHT": [
                                "https://172.16.20.30/ocfs/file/download/Z3JvdXAxL00wMC8xMC85Qi9yQkFVSGx0VnJ2bUFHN1VyQUFEQjcxWl9WcG82MDkuanBn"
                            ]
                        },
                        "groupId": "paramDB0",
                        "icNumber": "2345yuhgf",
                        "id": "2aa3956080a54d8dbcad7221f6db6e05",
                        "idCard": "130123123412121234",
                        "mail": "test@123.com",
                        "name": "Mark1977",
                        "no": "10013977",
                        "organization": "FaceSectianzc",
                        "organizationId": 102,
                        "password": "123.com",
                        "phone": "18512340001",
                        "position": "Service",
                        "sex": "MALE",
                        "type": "FREQUENTER",
                        "updateTime": 1532414453000,
                        "variable": {},
                        "wgNumber": "323"
                    }
                ],
                "first": true,
                "last": true,
                "number": 0,
                "numberOfElements": 1,
                "size": 10,
                "totalElements": 1,
                "totalPages": 1
            },
            "message": "success",
            "path": "",
            "status": 200,
            "timestamp": 1531200287758
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.7. Bind device to rule

Bind device to rule

Summary

Request URL:/bbox-service/api/rule/device/issue/{ruleId}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/device/issue/120
        
        [
          "KRFQ899SGIKBPV8S",
          "C10016756343345Y"
        ]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
deviceSns	body	string		true		Device serial no. group
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.8. Unbind device from rule

Unbind device from rule

Summary

Request URL:/bbox-service/api/rule/device/{ruleId}/{deviceSn}
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/device/120/KRFQ899SGIKBPV8S

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
deviceSn	path	string		true		Device serial no.
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.9. Retrieve details of devices under a rule

Retrieve details of devices under a rule

Summary

Request URL:/bbox-service/api/rule/device/{ruleId}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/device/10?deviceGroupId=104&deviceName=aa&deviceSn=SN2018122101&deviceType=DEVICE_TYPE_ACCESS_CONTROL&page=0&size=10&sort=sn,desc&status=DEVICE_OFF_LINE

Request parameters

Field	Parameter position	Type	Required	Description
deviceGroupId	query	string	false	Device group ID
deviceName	query	string	false	Device name
deviceSn	query	string	false	Device serial no.
deviceType	query	string	false	Device type Standing terminal: `DEVICE_ONE_SINGLE_SCREEN` Wall-mounted terminal: `DEVICE_ONE_ACCESS_CONTROL` Turnstile: `DEVICE_ONE_GATE_MACHINE` Desktop terminal: `DEVICE_ONE_DESKTOP_MACHINE`
ruleId	path	integer	true	Rule ID
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
sort	query	string	false	Sorting rule. `name, desc` will return results in reverse alphabetical order, not in reverse chronological order using updateTime
status	query	string	false	Device status (String type) Device disconnected `DEVICE_OFF_LINE` Device normal `DEVICE_RECOVERY`

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«Device»»>	OK

Response body: CommonResponse«Page«Device»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	ref	No	<Page«Device»>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: Page«Device»

Field	Type	Required	Structure	Description
content	array	No	<Device>	Content
first	boolean	Yes		Is first page
last	boolean	Yes		Is last page
number	int	Yes		Current page
numberOfElements	int	Yes		Current page
size	int	Yes		Number of items on each page
sort	undefined	No		Sort
totalElements	long	Yes		Total items
totalPages	int	Yes		Total pages

Response body: Device

Device type

Field	Type	Required	Description
createTime	int	No	Creation time
groupId	int	No	Device group ID
groupName	string	No	Device group
id	int	No	id
name	string	No	Device name
operatorId	long	No	Operator ID
operatorName	string	No	Operator
sn	string	No	Device serial no.
status	string	No	Device status (String type) Device disconnected `DEVICE_OFF_LINE` Device normal `DEVICE_RECOVERY`
tenantId	long	No	Tenant ID
type	string	No	Device type: Standing terminal `DEVICE_ONE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_ONE_ACCESS_CONTROL` Turnstile `DEVICE_ONE_GATE_MACHINE` Desktop terminal `DEVICE_ONE_DESKTOP_MACHINE` Standing terminal `DEVICE_TYPE_SINGLE_SCREEN` Wall-mounted terminal `DEVICE_TYPE_ACCESS_CONTROL` Turnstile `DEVICE_TYPE_GATE_MACHINE` Desktop terminal `DEVICE_TYPE_DESKTOP_MACHINE` Camera `TYPE_DYNAMIC_CAMERA` Kiosk `TYPE_SELF_SERVICE_TERMINAL` Digital signage `TYPE_DIGITAL_SIGNAGE`
updateTime	int	No	Update time
version	string	No	Version no.

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": {
                "content": [
                    {
                        "createTime": 1532283482000,
                        "id": 21286,
                        "sn": "KRFQ899SGIKBPV8S",
                        "status": "DEVICE_OFF_LINE",
                        "tenantId": 197,
                        "type": "DEVICE_TYPE_ACCESS_CONTROL",
                        "updateTime": 1532336603000,
                        "version": "BFRT_1.0.07.19"
                    }
                ],
                "first": true,
                "last": true,
                "number": 0,
                "numberOfElements": 1,
                "size": 10,
                "totalElements": 1,
                "totalPages": 1
            },
            "status": 200,
            "timestamp": 1532422368350
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.10. Add rules and bind personnel

Simplified rule binding interface

Summary

Request URL:/bbox-service/api/rule/simple
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/simple
        {
          "name": "SimpleRule",
          "description": "DescriptionMessage",
          "saasVisible": 1,
          "deviceVisible": 1,
          "passMode": "FACE",
          "endDate": "1548586693000",
          "startDate": "1547722693000",
          "personInfo": {
            "avatars": {
              "VISIBLE_LIGHT": [
                "https://172.16.20.191/ocfs/file/download/Z3JvdXAxL00wMC8wMC9FMC9yQkFVdjF4QUZvV0FkZzAzQUFCRmNTYUJLYVUwMTYuanBn"
              ]
            },
            "groupId": "61dbc2c46ffe43f5b5080845db0f4f07",
            "icNumber": "9876",
            "idCard": "123445656777",
            "mail": "123@qq.com",
            "name": "AdamS",
            "no": "CM123123",
            "organizationId": 1,
            "password": "123456",
            "phone": "18512341234",
            "sex": "MALE"
          },
          "deviceSns": [
            "FC211118380009"
          ]
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
simpleRuleDTO	body	ref		true	<SimpleRuleDTO>	simpleRuleDTO

Request body: SimpleRuleDTO

Simplified rule object

Field	Type	Required	Structure	Description
description	string	No		Description (Length between 0-64 characters, special characters not allowed.)
deviceSns	array	No	string	Device group serial no. to send rule to
deviceVisible	int	No		On-device visibility 0: Hidden (default) 1: Visible
endDate	long	Yes		End Date
name	string	Yes		Name (Length between 1-64 characters, special characters not allowed, must be unique)
passMode	string	Yes		Access method `FACE` Facial scan `FACE_AND_ID` Facial scan + Identity card `FACE_AND_PASSPORT` Facial scan + Passport `FACE_AND_GUARD` Facial scan + Access card `FACE_AND_IC` Facial scan + IC card `QCODE` QR Code `SCANNING_GUN` Scanning device `FACE_AND_PASSWORD` Facial scan + Password
personInfo	ref	No	<PersonDTO>	Personnel details Required when adding rule, not required if updating rule
saasVisible	int	No		Visible to SaaS 0: Hidden (default) 1: Visible
startDate	long	Yes		Start date

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Rule»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545893213857,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 104,
                "name": "AccessRuleTest",
                "description": "AccessRuleTest-For Testing Purposes",
                "type": 0,
                "passMode": "FACE",
                "timeRule": [
                    {
                        "title": "Custom",
                        "type": "TIMING",
                        "dayRange": {
                            "start": {
                                "year": 2018,
                                "mm": 7,
                                "day": 28
                            },
                            "end": {
                                "year": 2019,
                                "mm": 7,
                                "day": 31
                            }
                        },
                        "dayType": "CUSTOM",
                        "customDays": [
                            1,
                            7
                        ],
                        "timeRange": {
                            "start": {
                                "hour": 14,
                                "minute": 30,
                                "second": 32
                            },
                            "end": {
                                "hour": 15,
                                "minute": 30,
                                "second": 32
                            }
                        },
                        "action": "ALLOW"
                    }
                ],
                "createTime": 1545893212998,
                "updateTime": 1545893212998,
                "deviceUpdateTime": 1545893212997,
                "createBy": "1",
                "tenantId": 1,
                "validTill": 1564558232994,
                "saasVisible": 1,
                "deviceVisible": 1,
                "status": "NORMAL",
                "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
                "deviceSns": [
                    "SN2018122101"
                ]
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.11. Update rule and bind personnel

Simplified rule interface

Summary

Request URL:/bbox-service/api/rule/simple/{ruleId}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/rule/simple/166
        {
            "name":"xxxxx",
            "startDate":1547740800000,
            "endDate":1547827200000,
            "passMode":"FACE",
            "personInfo":
                {
                    "name":"xxxxxxx",
                    "no":"testaddsamplerule1"
                    
                },
            "description": "xxxxxx",
            "saasVisible": 1,
            "deviceVisible": 1
            
        }

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
ruleId	path	integer		true		Rule ID
simpleRuleDTO	body	ref		true	<SimpleRuleDTO>	simpleRuleDTO

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Rule»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545893213857,
            "status": 200,
            "code": 0,
            "entity": {
                "id": 104,
                "name": "Test access rule",
                "description": "Test access rule - for testing purposes",
                "type": 0,
                "passMode": "FACE",
                "timeRule": [
                    {
                        "title": "Custom",
                        "type": "TIMING",
                        "dayRange": {
                            "start": {
                                "year": 2018,
                                "mm": 7,
                                "day": 28
                            },
                            "end": {
                                "year": 2019,
                                "mm": 7,
                                "day": 31
                            }
                        },
                        "dayType": "CUSTOM",
                        "customDays": [
                            1,
                            7
                        ],
                        "timeRange": {
                            "start": {
                                "hour": 14,
                                "minute": 30,
                                "second": 32
                            },
                            "end": {
                                "hour": 15,
                                "minute": 30,
                                "second": 32
                            }
                        },
                        "action": "ALLOW"
                    }
                ],
                "createTime": 1545893212998,
                "updateTime": 1545893212998,
                "deviceUpdateTime": 1545893212997,
                "createBy": "1",
                "tenantId": 1,
                "validTill": 1564558232994,
                "saasVisible": 1,
                "deviceVisible": 1,
                "status": "NORMAL",
                "personIds": [
                    "14b9fdd5f45649729d6a1c710be3388d",
                    "522d7c963f834bf8864896b200b0e7fc"
                ],
                "deviceSns": [
                    "SN2018122101"
                ]
            }
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.5.12. Add personnel to rule

Simplified rule interface

Summary

Request URL:/bbox-service/api/rule/simple/person/add/{ruleId}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/simple/person/add/166
["e0c0461538ea4581aae4d459296a4bc8"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
personIds	body	array		true		personIds
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.13. Remove personnel from rule

Simplified rule interface

Summary

Request URL:/bbox-service/api/rule/simple/person/delete/{ruleId}
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/simple/person/delete/166
["e0c0461538ea4581aae4d459296a4bc8"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
personIds	body	array		true		personIds
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.14. Add device to rule

Simplified rule interface

Summary

Request URL:/bbox-service/api/rule/simple/device/add/{ruleId}
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/simple/device/add/166
["sn0001"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
deviceSns	body	array		true		deviceSns
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.5.15. Remove device from rule

Simplified rule interface

Summary

Request URL:/bbox-service/api/rule/simple/device/delete/{ruleId}
Request protocol:HTTPS
Request method:delete
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/rule/simple/device/delete/166
["sn001"]

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
deviceSns	body	array		true		deviceSns
ruleId	path	integer		true		Rule ID

Response

Name	Type	Structure	Description
200	string		OK

5.6. Identification Record Interface

Retrieve Identification Records from devices. Use to trace personnel access and gather statistics on recognition process.

5.6.1. Retrieve identification records list

Obtain Identification Records list

Summary

Request URL:/bbox-service/api/access-record
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
 https://172.16.20.30/bbox-service/api/access-record?name=ss&personNo=12&startTime=1543766400000&endTime=1546963200000
 &ruleId=109&deviceGroupId=-1&resultType=TERMINAL_VALIDATION_PASS&page=0&size=10

Request parameters

Field	Parameter position	Type	Required	Description
deviceGroupId	query	integer	false	Device group ID
endTime	query	long	false	End Date
name	query	string	false	Name
organizationId	query	integer	false	Organization ID
page	query	integer	false	Page number. If blank, defaults to retrieving data from the first page
size	query	integer	false	Page items. If blank, defaults to listing 10 items per page
personNo	query	string	false	Personnel no.
regexName	query	boolean	false	Whether regex-based search is used in name search
regexPersonNo	query	boolean	false	Whether regex-based search is used in personnel no. search
resultType	query	string	false	Access result: `TERMINAL_VALIDATION_PASS`, `TERMINAL_VALIDATION_FAILURE`
ruleId	query	integer	false	Rule ID
sn	query	string	false	Device serial no.
sort	query	string	false	Sorting rules (e.g. `?sort=version,updateTime,asc&sort=name,desc`)
startTime	query	long	false	Start date

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«Page«AccessRecordInfo»»>	OK

Response body: CommonResponse«Page«AccessRecordInfo»»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<Page«AccessRecordInfo»>	Included objects
message	string	Yes		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Response body: Page«AccessRecordInfo»

Field	Type	Required	Structure	Description
content	array	No	<AccessRecordInfo>	Content
first	boolean	Yes		Is first page
last	boolean	Yes		Is last page
number	int	Yes		Current page
numberOfElements	int	Yes		Current page
size	int	Yes		Number of items on each page
sort	undefined	No		Sort
totalElements	long	Yes		Total items
totalPages	int	Yes		Total pages

Response body: AccessRecordInfo

Identification record details

Field	Type	Required	Structure	Description
avatars	object	No		Image address
createTime	long	No		Creation time
deviceInfo	ref	Yes	<DeviceInfo>	Device details
id	string	Yes		Identification record ID
idNumber	string	No		Card no.
identifyCard	ref	No	<IdentifyCard>	Document no.
identifyInfo	object	No		Access document no.
name	string	Yes		Personnel name
nirScore	string	No		Near-infrared score
passMode	string	Yes		Access method `FACE` Facial scan `FACE_AND_ID` Facial scan + Identity card `FACE_AND_PASSPORT` Facial scan + Passport `FACE_AND_GUARD` Facial scan + Access card `FACE_AND_IC` Facial scan + IC card `QCODE` QR Code `SCANNING_GUN` Scanning device `FACE_AND_PASSWORD` Facial scan + Password
personInfo	ref	Yes	<PersonInfo>	Personnel details
qrCode	string	No		QR Code
rejectReason	string	No		Rejection cause: `FACIAL_COMPARISON_NOT_PASS` Facial scan does not match `BLACKLIST_EXCEEDS_REFUSE` Blacklist access denied `PERSONNAL_RULE_VALIDATION_FAILURE` Personnel rule `FINGERPRINT_VALIDATION_FAILURE` Fingerprint validation failed `INVALID_VALIDATION` Not validated (No valid card)
resultType	string	Yes		Access result: `TERMINAL_VALIDATION_PASS`, `TERMINAL_VALIDATION_FAILURE`
score	string	No		Visible light score
syncTime	long	Yes		Access time
tenantId	long	Yes		Tenant ID
type	string	No		Access type: `IN_TYPE` Entry, `OUT_TYPE` Exit

Response body: DeviceInfo

Device details

Field	Type	Required	Description
areaId	int	No	Area ID
areaName	string	No	Area name
direction	byte	No	Device direction
groupId	int	No	Device group ID
name	string	No	Device name
sn	string	No	Device serial no.

Response body: IdentifyCard

ID details

Field	Type	Required	Description
address	string	No	Address
birthPlace	string	No	Place of birth
birthday	string	No	Birthday
countryCode	string	No	Country code
idCard	string	No	ID no.
imageUrl	string	No	ID image
issuePlace	string	No	Place of issue
name	string	No	Name
nation	string	No	Nationality
sex	string	No	Gender: `MALE`, `FEMALE`
signBegin	string	No	Date of issue
signEnd	string	No	Expiry date
signOrg	string	No	Issuing authority

Response body: PersonInfo

Personnel details

Field	Type	Required	Description
age	int	No	Age
appId	string	No	Application ID
avatars	object	No	Image
groupId	string	No	Feature library
groupName	string	No	Feature library name
icNumber	string	No	IC card no.
id	string	No	id
idCard	string	No	Identity card no.
name	string	Yes	Name
no	string	Yes	No.
organizationId	int	No	Organization ID
phone	string	No	Mobile
ruleId	string	No	Rule ID
ruleName	string	No	Rule name
sex	string	No	Gender: `MALE`, `FEMALE`
tenantId	long	No	Tenant ID
type	string	No	`FREQUENTER`, `VISITOR`
variable	object	No	Dynamic variable
wgNumber	string	No	Wiegand no.

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": {
                "content": [
                    {
                        "avatars": {
                            "VISIBLE_LIGHT": [
                                "https://172.16.20.30/ocfs/file/download/Z3JvdXAxL00wMC8xMC9BRi9yQkFVSGx0V2g1aUFVMFVTQUFDQjZfRWVONTAxMC5qcGVn"
                            ]
                        },
                        "deviceInfo": {
                            "areaId": 14,
                            "areaName": "123",
                            "direction": 0,
                            "sn": "W4AYQ4RKTCSCGUDM"
                        },
                        "id": "4c1340c2649040478aa28e53a9df0528",
                        "passMode": "FACE",
                        "rejectReason": "FACIAL_COMPARISON_NOT_PASS",
                        "resultType": "TERMINAL_VALIDATION_FAILURE",
                        "score": "0.0",
                        "syncTime": 1532426232053,
                        "tenantId": 205
                    }
                ],
                "first": true,
                "last": false,
                "number": 0,
                "numberOfElements": 10,
                "size": 10,
                "totalElements": 389,
                "totalPages": 39
            },
            "message": "success",
            "path": "",
            "status": 200,
            "timestamp": 1531200287758
        }
        Error response http status（400-599）
        {
          "timestamp": 1531200287758,
          "message": "Error Message",
          "path": "",
          "status": 400,
          "code": 0
        }

5.6.2. Retrieve identification record details

Retrieve identification records via ID

Summary

Request URL:/bbox-service/api/access-record/{id}
Request protocol:HTTPS
Request method:get
Request format:``
Response format:*/*

Request Example


xxxxxxxxxx
        https://172.16.20.30/bbox-service/api/access-record/4c1340c2649040478aa28e53a9df0528

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
id	path	string		true		id

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«AccessRecordInfo»>	OK

Response body: CommonResponse«AccessRecordInfo»

Generic response object

Field	Type	Required	Structure	Description
code	int	Yes		Request response code
entity	ref	No	<AccessRecordInfo>	Included objects
message	string	Yes		Response message
path	string	No		Request path
status	int	Yes		Status code
timestamp	long	Yes		Request timestamp

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": {
                "avatars": {
                    "VISIBLE_LIGHT": [
                        "https://172.16.20.30/ocfs/file/download/Z3JvdXAxL00wMC8xMC9BRi9yQkFVSGx0V2g1aUFVMFVTQUFDQjZfRWVONTAxMC5qcGVn"
                    ]
                },
                "deviceInfo": {
                    "areaId": 14,
                    "areaName": "123",
                    "direction": 0,
                    "sn": "W4AYQ4RKTCSCGUDM"
                },
                "id": "4c1340c2649040478aa28e53a9df0528",
                "passMode": "FACE",
                "rejectReason": "FACIAL_COMPARISON_NOT_PASS",
                "resultType": "TERMINAL_VALIDATION_FAILURE",
                "score": "0.0",
                "syncTime": 1532426232053,
                "tenantId": 205
            },
            "message": "success",
            "path": "",
            "status": 200,
            "timestamp": 1531200287758
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.7. Image Upload Interface

Upload Controller

5.7.1. Single image upload (Deprecated)

This interface is deprecated since update 2.1, please use Batch image upload

Summary

Request URL:/bbox-service/api/upload/image
Request protocol:HTTPS
Request method:post
Request format:multipart/form-data
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/upload/image

Request parameters

Field	Parameter position	Type	Default value	Required	Structure	Description
file	formData	file		false		file

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«string»>	OK

Example response


xxxxxxxxxx
        Success response
        {
            "code": 0,
            "entity": "https://172.16.20.30/ocfs/file/download/Z3JvdXAxL00wMC8xMC85Qi9yQkFVSGx0VnJ2bUFHN1VyQUFEQjcxWl9WcG82MDkuanBn",
            "message": "string",
            "path": "string",
            "status": 0,
            "timestamp": 0
        }
        Error response http status（400-599）
        {
            "code": 0,
            "message": "Error Message",
            "path": "",
            "status": 400,
            "timestamp": 1531200287758
        }

5.7.2. Batch image upload

Upload a photo and return cropped photo details

Summary

Request URL:/bbox-service/api/upload/v2/batch-image
Request protocol:HTTPS
Request method:post
Request format:multipart/form-data
Response format:*/*

Request Example


xxxxxxxxxx
https://172.16.20.30/bbox-service/api/upload/v2/batch-image
-F "faceImages=@7005.jpg;type=image/jpeg"

Request parameters

Field	Parameter position	Type	Required	Description
clearLevel	formData	number	false	Assessed clarity level (0-100). Above 70 is considered blurred, otherwise, considered clear.
imagePixel	formData	string	false	Image resolution `THREE_TWO` (3232 px, cannot be lower than 32px) `ONE_TWO_EIGHT` (128128 px, cannot be lower than 128px `THREE_TWO_ZERO` (320*320 px, cannot be lower than 320px)
qualityAngle	formData	boolean	false	Whether to turn on the angle symbol
qualityDetect	formData	boolean	false	Whether to turn on image evaluation. If activated, the four variables (qualityAngle, clearLevel, visLevel, imagePixel) must be filled in.
visLevel	formData	number	false	Occlusion (0-100). Values above 80 means that subject is blocked

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«MultipartFileResp»»>	OK

Response body: CommonResponse«List«MultipartFileResp»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<MultipartFileResp>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: MultipartFileResp

File upload response body

Field	Type	Required	Description
fileName	string	Yes	Original file name
flag	boolean	Yes	Upload success flag
message	string	No	Response message
url	string	No	File access location

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1545900170459,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "flag": true,
                    "url": "https://172.16.20.191/ocfs/file/download/Z3JvdXAxL00wMC8wMC9DNC9yQkFVdjF3a2tJcUFQcVdEQUFCRmJxNTZjeE05MzAuanBn",
                    "fileName": "7005.jpg"
                }
            ]
        }
        Error response http status（400-599）
        {
            "timestamp": 1545894841247,
            "status": 400,
            "code": 104001,
            "message": "Error Message",
            "path": "/api/upload/v2/batch-image"
        }

5.8. Facial Recognition Management Interface

Uses facial recognition algorithms to perform face detection and analysis, based on image analysis and comparison operations

5.8.1. Single face analysis

Supports analysis of multiple images containing individual faces. The default maximum number of images that can be handled concurrrently is 20. If there are more than 20 concurrent requests, the system will notify that the handles cannot be retrieved and the processing will fail. Based on the number of custom handles, private deployment processes can manage the concurrent requests. The recommended number of handles is the number of CPUs available.

Summary

Request URL:/o-algorithm/api/open/analysis
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«FaceResponse»»>	OK

Response body: CommonResponse«List«FaceResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<FaceResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: FaceResponse

Face information response entity

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
face	ref	No	<Face>	Facial information
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information

Response body: Face

Facial information

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResult	ref	No	<DetectResult>	Face detection result
feature	string	No
qualityResult	ref	No	<QualityResult>	Face detection quality result

Response body: DetectResult

Face detection result

Field	Type	Required	Structure	Description
confidence	number	No		Face detection confidence level
height	int	No		Face height
pitch	number	No		Face pitch angle
pointLeftEye	ref	No	<Point>	Left eye coordinate point
pointRightEye	ref	No	<Point>	Right eye coordinate point
rectFace	ref	No	<Rect>	Face coordinate matrix
roll	number	No		Image float
signature	string	No		Facial signature
width	int	No		Face image width
yaw	number	No		Face yaw angle

Response body: Point

Coordinate information

Field	Type	Required	Structure	Description
x	long	No		X-coordinate
y	long	No		Y-coordinate

Response body: Rect

Face rectangle position

Field	Type	Required	Description
bottom	long	No	Rectangle bottom-right point Y-coordinate
left	long	No	Rectangle top left point X-coordinate
right	long	No	Rectangle bottom-right point X-coordinate
top	long	No	Rectangle top left point Y-coordinate

Response body: QualityResult

Face detection quality result

Field	Type	Required	Structure	Description
angle	array	No	int	Angle information
clearLevel	number	No		Face clarity level [0,100] Indicates the level of clarity of the image. If the value is greater than 70, the image is considered blur. Otherwise, the image is considered clear.
glassLevel	number	No		Probability that the person is wearing glasses [0,100]; Indicates if a person is wearing glasses. If the value is greater than 75, the person is considered to be wearing glasses. Otherwise, the person is considered as not wearing glasses.
visLevel	number	No		Degree of facial occlusion [0,100]; Indicates area of face that is blocked. If the value is greater than 80, the face is considered blocked. Otherwise, the face is not blocked.

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547794989116,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "faceDetect": {
                        "detectResult": {
                            "rectFace": {
                                "left": 128,
                                "top": 135,
                                "right": 328,
                                "bottom": 407
                            },
                            "pointLeftEye": {
                                "x": 188,
                                "y": 258
                            },
                            "pointRightEye": {
                                "x": 281,
                                "y": 258
                            },
                            "roll": 4.5846e-41,
                            "yaw": 0.7,
                            "pitch": 0.7,
                            "confidence": 4.5846e-41,
                            "quality": 0,
                            "width": 480,
                            "height": 720,
                            "signature": "GQAAAAAAAAAAAAAALEg8QyMfgUMBAAAAEnuMQ7A5gUMCAAAAMmoaQ7f/aEMDAAAANE9TQ8F7akMEAAAAdRuBQx+makMFAAAAmkudQxRTaUMGAAAAzExqQ/I4gEMJAAAA4h5rQ1ygnEMKAAAAgwVrQ3a8rEMLAAAA/gdrQ3O8uUMMAAAA1i5DQzbNrkMNAAAA5hCJQziSrkMrAAAAABGAQytxoUMsAAAAiDZUQ32AoUMtAAAAhQFrQ65HskPIAAAASS9rQ5ZNpEPdAAAAtIZQQ7j2gkPeAAAAfMA6Q7VJhEPfAAAANWIoQ9oygUPhAAAAnFuWQ89VgUPiAAAAWqaMQw1uhEPjAAAAP1WCQ6UKg0MsAQAAdKQ1QwcfYUMuAQAAvcOPQ5hIYUM6AQAAFy1qQ4YEzkMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                        },
                        "detectFaceCount": 1
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795246600,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": "/open/detect"
        }

5.8.2. Single-face detection details

Summary

Request URL:/o-algorithm/api/open/detect
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information, supports multiple image uploads.
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«DetectResponse»»>	OK

Response body: CommonResponse«List«DetectResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<DetectResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: DetectResponse

Face detection response object

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
faceDetect	ref	No	<FaceDetect>	Face detection information
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information

Response body: FaceDetect

Facial information

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResult	ref	No	<DetectResult>	Face detection result

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547799082839,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "faceDetect": {
                        "detectResult": {
                            "rectFace": {
                                "left": 387,
                                "top": 571,
                                "right": 724,
                                "bottom": 1062
                            },
                            "pointLeftEye": {
                                "x": 478,
                                "y": 771
                            },
                            "pointRightEye": {
                                "x": 645,
                                "y": 773
                            },
                            "roll": 4.5846e-41,
                            "yaw": 0.7,
                            "pitch": 0.7,
                            "confidence": 0,
                            "quality": 0,
                            "width": 1080,
                            "height": 1440,
                            "signature": "GQAAAAAAAAAAAAAA4v7uQ7TUQEQBAAAArE0hRLk0QUQCAAAA2TTSQ9gnNUQDAAAArioCRMeWN0QEAAAApAUXRGnAN0QFAAAAEFswRIzDNUQGAAAARAEMRLLQQEQJAAAAXLYLRDy9W0QKAAAAPnkLROBobEQLAAAAJiMLRMKUeUQMAAAACqb4Q/v2b0QNAAAAvJoaRKSgcEQrAAAAAJQURHbhYEQsAAAAgQsCRHSUYEQtAAAArUoLRJQZckTIAAAA9noLRGnTYkTdAAAAZZIARMlhQkTeAAAAcoftQ43UQ0TfAAAAQGXdQ+uFQEThAAAA/TMqRHM3QUTiAAAAYFEhRJwzRETjAAAA7EEYRPmFQkQsAQAAjILqQ3aTM0QuAQAATBckRLL9M0Q6AQAAPzgKRDKzhEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                        },
                        "detectFaceCount": 1
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795332896,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": ""
        }

5.8.3. Single-face facial feature extraction

Summary

Request URL:/o-algorithm/api/open/feature
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«FeatureResponse»»>	OK

Response body: CommonResponse«List«FeatureResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<FeatureResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: FeatureResponse

Feature extraction response body

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
faceFeature	ref	No	<FaceFeature>	Facial feature information
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information

Response body: FaceFeature

Facial feature information

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResult	ref	No	<DetectResult>	Face detection result
feature	string	No		Facial feature

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547796451035,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "faceFeature": {
                        "detectResult": {
                            "rectFace": {
                                "left": 387,
                                "top": 571,
                                "right": 724,
                                "bottom": 1062
                            },
                            "pointLeftEye": {
                                "x": 478,
                                "y": 771
                            },
                            "pointRightEye": {
                                "x": 645,
                                "y": 773
                            },
                            "roll": 4.5846e-41,
                            "yaw": 0.7,
                            "pitch": 0.7,
                            "confidence": 0,
                            "quality": 0,
                            "width": 1080,
                            "height": 1440,
                            "signature": "GQAAAAAAAAAAAAAA4v7uQ7TUQEQBAAAArE0hRLk0QUQCAAAA2TTSQ9gnNUQDAAAArioCRMeWN0QEAAAApAUXRGnAN0QFAAAAEFswRIzDNUQGAAAARAEMRLLQQEQJAAAAXLYLRDy9W0QKAAAAPnkLROBobEQLAAAAJiMLRMKUeUQMAAAACqb4Q/v2b0QNAAAAvJoaRKSgcEQrAAAAAJQURHbhYEQsAAAAgQsCRHSUYEQtAAAArUoLRJQZckTIAAAA9noLRGnTYkTdAAAAZZIARMlhQkTeAAAAcoftQ43UQ0TfAAAAQGXdQ+uFQEThAAAA/TMqRHM3QUTiAAAAYFEhRJwzRETjAAAA7EEYRPmFQkQsAQAAjILqQ3aTM0QuAQAATBckRLL9M0Q6AQAAPzgKRDKzhEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                        },
                        "detectFaceCount": 1,
                        "feature": "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"
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795332896,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": ""
        }

5.8.4. Single-face quality inspection information

Summary

Request URL:/o-algorithm/api/open/quality
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«QualityResponse»»>	OK

Response body: CommonResponse«List«QualityResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<QualityResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: QualityResponse

Single-face quality information entity

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
faceQuality	ref	No	<FaceQuality>	Face quality information entity
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information

Response body: FaceQuality

Face detection quality

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResult	ref	No	<DetectResult>	Face detection result
qualityResult	ref	No	<QualityResult>	Face detection quality

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547796192691,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "faceQuality": {
                        "detectResult": {
                            "rectFace": {
                                "left": 387,
                                "top": 571,
                                "right": 724,
                                "bottom": 1062
                            },
                            "pointLeftEye": {
                                "x": 478,
                                "y": 771
                            },
                            "pointRightEye": {
                                "x": 645,
                                "y": 773
                            },
                            "roll": 4.5846e-41,
                            "yaw": 0.7,
                            "pitch": 0.7,
                            "confidence": 4.5845e-41,
                            "quality": 0,
                            "width": 1080,
                            "height": 1440,
                            "signature": "GQAAAAAAAAAAAAAA4v7uQ7TUQEQBAAAArE0hRLk0QUQCAAAA2TTSQ9gnNUQDAAAArioCRMeWN0QEAAAApAUXRGnAN0QFAAAAEFswRIzDNUQGAAAARAEMRLLQQEQJAAAAXLYLRDy9W0QKAAAAPnkLROBobEQLAAAAJiMLRMKUeUQMAAAACqb4Q/v2b0QNAAAAvJoaRKSgcEQrAAAAAJQURHbhYEQsAAAAgQsCRHSUYEQtAAAArUoLRJQZckTIAAAA9noLRGnTYkTdAAAAZZIARMlhQkTeAAAAcoftQ43UQ0TfAAAAQGXdQ+uFQEThAAAA/TMqRHM3QUTiAAAAYFEhRJwzRETjAAAA7EEYRPmFQkQsAQAAjILqQ3aTM0QuAQAATBckRLL9M0Q6AQAAPzgKRDKzhEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                        },
                        "detectFaceCount": 1,
                        "qualityResult": {
                            "clearLevel": 0.42736092,
                            "visLevel": 0.17023087,
                            "glassLevel": 0.01988411,
                            "angle": [
                                0.9746387,
                                0.0018745515,
                                0.023486719,
                                4.5845e-41,
                                -1.8873458e-11
                            ]
                        }
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795332896,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": ""
        }

5.8.5. Multi-face analysisj

Supports analysis of multiple images containing multiple faces. The default maximum number of images that can be handled concurrrently is 20. If there are more than 20 concurrent requests, the system will notify that the handles cannot be retrieved and the processing will fail. Based on the number of custom handles, private deployment processes can manage the concurrent requests. The recommended number of handles is the number of CPUs available.

Summary

Request URL:/o-algorithm/api/multi-face/open/analysis
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«MultiFaceResponse»»>	OK

Response body: CommonResponse«List«MultiFaceResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<MultiFaceResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: MultiFaceResponse

Multi-face response object

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information
multiFace	ref	No	<MultiFace>	Muitple face information

Response body: MultiFace

Multi-face recognition parameters

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResultList	array	No	<DetectResult>	Multiple face detection quality result
featureList	array	No	int	Multiple face image information
qualityResultList	array	No	<QualityResult>	Multiple face detection quality result

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547794877789,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "face": {
                        "detectResult": {
                            "rectFace": {
                                "left": 387,
                                "top": 571,
                                "right": 724,
                                "bottom": 1062
                            },
                            "pointLeftEye": {
                                "x": 478,
                                "y": 771
                            },
                            "pointRightEye": {
                                "x": 645,
                                "y": 773
                            },
                            "roll": 4.5846e-41,
                            "yaw": 0.7,
                            "pitch": 0.7,
                            "confidence": 0,
                            "quality": 0,
                            "width": 1080,
                            "height": 1440,
                            "signature": "GQAAAAAAAAAAAAAA4v7uQ7TUQEQBAAAArE0hRLk0QUQCAAAA2TTSQ9gnNUQDAAAArioCRMeWN0QEAAAApAUXRGnAN0QFAAAAEFswRIzDNUQGAAAARAEMRLLQQEQJAAAAXLYLRDy9W0QKAAAAPnkLROBobEQLAAAAJiMLRMKUeUQMAAAACqb4Q/v2b0QNAAAAvJoaRKSgcEQrAAAAAJQURHbhYEQsAAAAgQsCRHSUYEQtAAAArUoLRJQZckTIAAAA9noLRGnTYkTdAAAAZZIARMlhQkTeAAAAcoftQ43UQ0TfAAAAQGXdQ+uFQEThAAAA/TMqRHM3QUTiAAAAYFEhRJwzRETjAAAA7EEYRPmFQkQsAQAAjILqQ3aTM0QuAQAATBckRLL9M0Q6AQAAPzgKRDKzhEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                        },
                        "detectFaceCount": 1,
                        "qualityResult": {
                            "clearLevel": 0.42736092,
                            "visLevel": 0.17023087,
                            "glassLevel": 0.01988411,
                            "angle": [
                                0.9746387,
                                0.0018745515,
                                0.023486719,
                                0,
                                -3.4938876e-7
                            ]
                        },
                        "feature": "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"
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795332896,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": ""
        }

5.8.6. Multiple-face detection details

Summary

Request URL:/o-algorithm/api/multi-face/open/detect
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«MultiDetectResponse»»>	OK

Response body: CommonResponse«List«MultiDetectResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<MultiDetectResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: MultiDetectResponse

Multi-face detection response object

Field	Type	Required	Structure	Description
error	string	No		Multi-face detection exception type: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information
multiFaceDetect	ref	No	<MultiFaceDetect>	Multi-face detection information

Response body: MultiFaceDetect

Multi-face detection result

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResultList	array	No	<DetectResult>	Multiple face detection quality result

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547799275095,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "multiFaceQuality": {
                        "detectResultList": [
                            {
                                "rectFace": {
                                    "left": 387,
                                    "top": 571,
                                    "right": 724,
                                    "bottom": 1062
                                },
                                "pointLeftEye": {
                                    "x": 478,
                                    "y": 771
                                },
                                "pointRightEye": {
                                    "x": 645,
                                    "y": 773
                                },
                                "roll": 4.5846e-41,
                                "yaw": 0.7,
                                "pitch": 0.7,
                                "confidence": 4.5846e-41,
                                "quality": 0,
                                "width": 1080,
                                "height": 1440,
                                "signature": "GQAAAAAAAAAAAAAA4v7uQ7TUQEQBAAAArE0hRLk0QUQCAAAA2TTSQ9gnNUQDAAAArioCRMeWN0QEAAAApAUXRGnAN0QFAAAAEFswRIzDNUQGAAAARAEMRLLQQEQJAAAAXLYLRDy9W0QKAAAAPnkLROBobEQLAAAAJiMLRMKUeUQMAAAACqb4Q/v2b0QNAAAAvJoaRKSgcEQrAAAAAJQURHbhYEQsAAAAgQsCRHSUYEQtAAAArUoLRJQZckTIAAAA9noLRGnTYkTdAAAAZZIARMlhQkTeAAAAcoftQ43UQ0TfAAAAQGXdQ+uFQEThAAAA/TMqRHM3QUTiAAAAYFEhRJwzRETjAAAA7EEYRPmFQkQsAQAAjILqQ3aTM0QuAQAATBckRLL9M0Q6AQAAPzgKRDKzhEQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                            }
                        ],
                        "detectFaceCount": 1,
                        "qualityResultList": [
                            {
                                "clearLevel": 0.42736092,
                                "visLevel": 0.17023087,
                                "glassLevel": 0.01988411,
                                "angle": [
                                    0.9746387,
                                    0.0018745515,
                                    0.023486719,
                                    4.5845e-41,
                                    -1.8871626e-11
                                ]
                            }
                        ]
                    }
                }
            ]
        }
        Error response 
        {
            "timestamp": 1547795332896,
            "status": 500,
            "code": 109101,
            "message": "Service exception",
            "path": ""
        }

5.8.7. Multiple-face facial feature extraction

Summary

Request URL:/o-algorithm/api/multi-face/open/feature
Request protocol:HTTPS
Request method:post
Request format:application/json
Response format:*/*

Request parameters

Field	Parameter position	Type	Required	Description
faceImages	formData	array	true	Image information
pitch	query	integer	false	Algorithm-reserved field. Optional setting
bpp	query	integer	false	Image information. Color image: 24; gray-scale image: 8. Optional setting
maxCount	query	integer	false	Maximum number of people that can be recognized. Optional setting

Response

Name	Type	Structure	Description
200	ref	<CommonResponse«List«MultiFeatureResponse»»>	OK

Response body: CommonResponse«List«MultiFeatureResponse»»

Generic response body

Field	Type	Required	Structure	Description
code	int	Yes		Response status code (Defined internally)
entity	array	No	<MultiFeatureResponse>	Response entity details
message	string	No		Error message
path	string	No		Request path
status	int	Yes		Response status code
timestamp	long	Yes		Timestamp

Response body: MultiFeatureResponse

Multiple-face feature extraction entity

Field	Type	Required	Structure	Description
error	string	No		Facial detection exception: Missing image border: `NO_IMAGE_RECT` Face not detected: `NO_FACE` Algorithm exception: `ALGO_EXCEPTION`
hasFace	boolean	No		Whether face information can be detected
message	string	No		Face detection information
multiFaceFeature	ref	No	<MultiFaceFeature>	Multiple-face feature extraction information

Response body: MultiFaceFeature

Multiple-face feature extraction result

Field	Type	Required	Structure	Description
detectFaceCount	int	No		Face count
detectResultList	array	No	<DetectResult>	Multiple face detection quality result
featureList	array	No	int	Multiple-face feature extraction information

Example response


xxxxxxxxxx
        Success response
        {
            "timestamp": 1547795863903,
            "status": 200,
            "code": 0,
            "entity": [
                {
                    "hasFace": true,
                    "multiFaceFeature": {
                        "detectResultList": [
                            {
                                "rectFace": {
                                    "left": 387,
                                    "top": 571,
                                    "right": 724,
                                    "bottom": 1062
                                },
                                "pointLeftEye": {
                                    "x": 478,
                                    "y": 771
                                },
                                "pointRightEye": {
                                    "x": 645,
                                    "y": 773
                                },
                                "roll": 4.5846e-41,
                                "yaw": 0.7,
                                "pitch": 0.7,
                                "confidence": -7.580006e+26,
       &