Test

cropped-background8.png

Important Notes

  • All calls to the Zenus API require an authorization header. The authorization header is not a JSON object; it will look like: {“Authorization”: [api_key] }
    Your API token can be found on your account summary page.
  • Image files that you use when enrolling or calling the identification/verification functions are not JSON objects. They are HTTP form fields.
  • All other POST data and response data will be in JSON format. For example, in the function that creates a person, the POST data (i.e., {“descriptor”: [string]}) will be a JSON object.

Functionality

 

Person
_Create Person_

Once you have your bearer token, you can begin adding persons into the system. Provide a descriptor (optional) and we will assign a unique person_id. If no descriptor is provided, a unique descriptor will be created.

POST https://api.zenus-biometrics.com/api/engine/person
{"descriptor": [string] }
Response Content: {"person_id": [int], "descriptor": [string]}
_Enroll Person_

Once you have created a person, you can begin uploading images that correspond to them using their person_id. The images should include only the person’s face. It is strongly recommended to upload at least two pictures for each person but not more than 10. Enrollment occurs one photo at a time.

POST https://api.zenus-biometrics.com/api/engine/person/:person_id/enroll
files:{"file": [image_file_object] }
Response Content: {"message": "success"}
_Get Person_

After you have created some persons, you may provide the person_id to get their descriptor and vice versa. You may also request a list of all persons.

Retrieving the descriptor of a person_id

GET https://api.zenus-biometrics.com/api/engine/person/:person_id
Response Content: {"person_id": [int], "descriptor": [string]}

Retrieving the person_id given the descriptor
Descriptors are not required to be unique so a list is returned even if there is only one result.

POST https://api.zenus-biometrics.com/api/engine/person/search
{"descriptor": [string]}
Response Content:  [person_id1, person_id2 ...]

Retrieving a list of all the persons

GET https://api.zenus-biometrics.com/api/engine/person
Response Content:  [{"person_id": [int], "descriptor": [string]}, ...]
_Update Person_

You may update a person’s descriptor.

POST https://api.zenus-biometrics.com/api/engine/person/:person_id
{"descriptor": [string]}
Response Content:  {"person_id": [int] , "descriptor": [string]}
_Delete Person_

You may delete a person.

DELETE https://api.zenus-biometrics.com/api/engine/person/:person_id
Response Content: {"message": "success"}
Group
_Create Group_

In order to perform any facial recognition task, you need to create a group and add persons to it. Provide a descriptor (optional) and we will assign a unique group_id. If no descriptor is provided, a unique descriptor will be created.

Each group must have at least five people and maxes at the number of people specified by your paid tier. The verification_threshold and identification_threshold are critical but if you are not sure how to set their value we can do that for you (see Thresholds below).

POST https://api.zenus-biometrics.com/api/engine/group
{"descriptor": [string], "verification_threshold": [number], "identification_threshold": [number]}
Response Content: {"group_id":  [int], "descriptor": [string], "verification_threshold": [number], "identification_threshold": [number]}
_Group Membership_

You may add/remove persons and get a list of the current group persons.

Adding a person

POST https://api.zenus-biometrics.com/api/engine/group/:group_id/person/:person_id
{"descriptor": [string], "verification_threshold": [number], "identification_threshold": [number]}
Response Content: {"message": "success"}

Removing a person

DELETE https://api.zenus-biometrics.com/api/engine/group/:group_id/person/:person_id
Response Content: {"message": "success"}

List the current group persons

GET https://api.zenus-biometrics.com/api/engine/group/:group_id/members
Response Content: {"members": [person_id1, person_id2, ...]}
_Get Group_

You may check the values of a group, get a list of all the groups, and retrieve the group_id given a descriptor.

Check the values of a group

POST https://api.zenus-biometrics.com/api/engine/group
{"descriptor": [string], "verification_threshold": [number], "identification_threshold": [number]}
Response Content: {"group_id":  [int], "descriptor": [string], "verification_threshold": [number], "identification_threshold": [number]}
GET https://api.zenus-biometrics.com/api/engine/group/:group_id
Response Content: {"group_id": [int], "descriptor": [string], "identification_threshold": [number], "verification_threshold": [number]}

List of all groups

GET https://api.zenus-biometrics.com/api/engine/group/0
Response Content: [{"group_id": [int], "descriptor": [string], "identification_threshold": [number], "verification_threshold": [number]}, ...]

Retrieve the ID of a group given a descriptor
Descriptors are not required to be unique so multiple group_ids might be returned.

POST https://api.zenus-biometrics.com/api/engine/group/search
{"descriptor": [string]}
Response Content: [group_id1, group_id2, ...]
_Delete Group_

You may delete a group.

DELETE https://api.zenus-biometrics.com/api/engine/group/:group_id
Response Content: {"message": "success"}
Thresholds

A different threshold is needed for verification and identification. Moreover, each group requires its own verification and identification thresholds. Our system can compute these values for you to achieve your selected false acceptance/rejection ratio (FAR or FRR) for each group.

_Requesting Computation of New Thresholds_
POST https://api.zenus-biometrics.com/api/engine/group/:group_id/threshold
{"target": "FRR", "target_value":  [number]}
OR
{"target": "FAR", "target_value": [number] }
Response Content: {"message": "Computing best thresholds for group"}

Notes
The target value must be a real number between 0 and 1 (see definitions). We recommend setting it between 0.01 and 0.05. Values smaller than 0.01 will result in either large FAR or FRR values.
This API call only needs to be called on a group after you have made any modifications to the group. There is no need to call this API call otherwise. Calling this function locks the group until the thresholds are computed

_Requesting Computed Thresholds_
GET https://api.zenus-biometrics.com/api/engine/group/:group_id/thresholds
Response Content: {"group_id": [int] , "descriptor": [string], "identification_threshold": [number], "verification_threshold": [number]}
_Requesting Estimated Accuracy_
GET https://api.zenus-biometrics.com/api/engine/group/:group_id/accuracy
Response Content: {"group_id": [int] , "descriptor": [string], "FAR": [number], "FRR": [number]}

Notes
The more persons in the group and the more images per person, the more reliable the estimates will be.
If you fix the FRR when requesting new thresholds, the estimated FRR will be close to the expected one but the estimated FAR may be overestimated as much as ten times. This is because we always consider a “worst-case” scenario to ensure smooth operation in the real-world.

Scheduling

In order to use the verification and identification API endpoints, you must use some of the time your paid tier has allocated you. This API endpoint lets you start the timer and determine how long the system will be active. The number of minutes must be an integer divisible by 10.

POST https://api.zenus-biometrics.com/api/engine/start
{"minutes": [int] }
Response Content: {“message”: “engine access granted”}

Verification

The process of determining whether or not someone is who they claim they are. In order to perform a verification task you will need to have already completed the following steps:

  1. Created persons
  2. Enrolled each person’s respective photos
  3. Placed the persons in a group
  4. Start the clock (see scheduling above)

When performing a verification task you will need to provide:

  1. An image of the person who needs to be verified
  2. The person_id of the claimed identity
  3. The group_id of the group the claimed identity belongs to
POST https://api.zenus-biometrics.com/api/engine/group/:group_id/person/:person_id/verify
files:{"file": [image_file_object]}
Response Content: {"result": [boolean], "score": [number]} 

Note
The boolean is True if the score is above the verification_threshold of the group_id specified. Otherwise, it will be False.

Identification

The process of determining whether an unidentified person exists in a group and who they are. In order to perform an identification task you will need to have already completed the following steps:

  1. Created persons
  2. Enrolled each person’s respective photos
  3. Placed the persons in a group
  4. Start the clock (see scheduling above)

When performing an identification task you will need to provide:

  • An image of the person who needs to be identified
  • The group_id of the group we are searching
POST api.zenus-biometrics.com/api/engine/group/identify
files:{"file": [image_file_object]}
Response Content: [{"id": [int], "score": [number]}, ...]

Note
A list with all the person_ids is returned for which the corresponding scores are above the identification_threshold for the group_id specified. Otherwise, the list will be empty.