Person Management

Following the collection(s) creation, let's start enrolling some person(s) in the collection.

Add a person

PUT /person

This endpoint is to enroll or update a single person. For bulk person enrollment, please refer to PUT/persons

Headers

Name	Value
Content-Type	application/json
x-api-key	<your-api-key>

Body

Name	Description
person_id	Required: Yes Type: string Example: "person_id": "F12345" Person id must be unique and defined, using same face with different person id will result duplicated record, be aware the person_id is case-sensitive.
person_name	Required: Yes Type: string Example: "person_name": "John Doe" Person name must be defined during enrollment. You can also update an enrolled person's name in later stage, as long the person_id remains the same
check_duplicates	Required: Yes Type: boolean Default value: false Accepted values: false, true "check_duplicates": false Based on the set similarity score, this feature checks if there is a duplicated enrollment in a collection. If value set as true, enrolling a duplicate person is not allowed.
check_liveness	Required: Yes Type: boolean Default value: false Accepted values: false, true "check_liveness": false If set to true, the liveness check is conducted during the person enrollment. If the person is successfully enrolled, means the face is live, else an error of "ERR_LIVENESS_ERROR" will return if face is not live, and person is not enrolled. Check liveness image requirement here
collection_name	Required: Yes Type: string Example: "collection_name": "SSAI" Please create a collection first before enrolling person(s). Else an error "The requested entity could not be found." will return
duplicate_check_min_similarity	Required: Yes Type: float Default value: 0.7 Example: "duplicate_check_min_similarity": 0.7 It's recommended to keep the default value to check the duplicate enrollment. If "check_duplicates" set as false, "duplicate_check_min_similarity" will not be used
face_base_64	Required: Yes Type: string Example: face_base_64": "U2Vjb25kIGltYWdl" Use base64 encoded string to enroll the face, one image should have only one face
face_storage_type	Required: Yes Type: string Accepted values: "NoStorage", "StoreThumbnails", "StoreFullImage" Example: "face_storage_type": "NoStorage" "NoStorage" = do not store any face image "StoreThumbnails" = store only thumbnails (cropped face from the given image) "StoreFullImage" = store full base64 image
metadata	Required: Optional Type: dict Example: "metadata": { "DOB": "2000-01-01", "Department": "Operation", "Nationality": "Singaporean", "Address": "101 Cecil Street, Singapore", ... } Metadata is a customizable field that allows to put additional info while enrolling a person. You can add N number customized fields for your use case.

Response

200

{
  "face_base_64": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "person_id": "string",
  "person_name": "string"
}

400

The collection name specified is not valid

{
  "code": "ERR_INVALID_COLLECTION_NAME",
  "message": "Collection names can only contain alphanumeric characters, underscores, hyphens, and periods."
}

401

Please use an API Key to access this endpoint

{
  "code": "ERR_API_KEY_NOT_PRESENT",
  "message": "The API key is missing from the request."
}

403

API Key is invalid. Please provide a valid API Key

{
  "code": "ERR_API_KEY_NOT_VALID",
  "message": "The API key is not valid."
}

404

The collection with the specified name does not exist

{
  "code": "ERR_NOT_FOUND",
  "message": "The requested entity could not be found."
}

409

Another person with a similar face already exists in the collection

{
  "code": "ERR_PERSON_ALREADY_EXISTS",
  "message": "Another person exists with a similar face. Check metadata for the person_id of the duplicate.",
  "metadata": {
    "person_id": "c96a1bc7-4c4e-497e-897f-c448a4a4be6a"
  }
}

412

Liveness error. The metadata contains the code that provides specifics about the error

EYES_CLOSED || FACE_CLOSE_TO_BORDER || FACE_CROPPED || FACE_NOT_LIVE || FACE_TOO_CLOSE || FACE_ANGLE_TOO_LARGE || FACE_IS_OCCLUDED || FACE_NOT_FOUND || FACE_TOO_SMALL || LICENSE_ERROR || TOO_MANY_FACES || UNKNOWN_ERROR

{
  "code": "ERR_LIVENESS_ERROR",
  "message": "A liveness error occurred. Please check the supplied image and the error metadata.",
  "metadata": {
    "code": "FACE_NOT_LIVE || .. || UNKNOWN_ERROR"
  }
}