Skip to content

Considerations

The API described in this appendix has the following attributes:

  • This API enables generation of biometric credentials, which are binary strings containing a biometric vector (embedding). Such vectors are a representation of the face used by das-Face for similarity comparison. Credentials have the following specifications:
    • Encoding: das-Face returns credentials encoded in base64. It is recommended to decode the string to binary before writing it to a persistent storage. Any POST request containing a credential must encoded it in base64 to be understood by das-Face.
    • Length: depends on the biometric model, please, look below for the model specs.

  • Available biometric models:

    Model tag Model hash Credential length Released NIST Submission
    20210913 1f29f3d61aecf88b961d33bad141a98d9da514c8bac7c2b81eb94235 9040 bits in binary format das-Face v3.4 veridas-007
    20210203 bab0b604e3cb088dd6c484a9774505f5545d3e5837874f3ec0172af5 9040 bits in binary format das-Face v3.0 veridas-006
    20200514 904fa9ef6e71ef541f20a95d3dc97821b7af43b8cd2c1bb3eb09df15 2896 bits in binary format das-Face v2.4
  • All endpoints in this API v2 are prefixed with /v2/.
  • A unique id is returned to the VeriSaaS API users using the 'X-Request-Id' header.
    • Each request is uniquely identified, which might be helpful to trace support cases.
  • The server processes requests in application/json and multipart/form-data media types.
    • In case of application/json, all files should be encoded in base64 and sent as a string field in the JSON document.
    • For multipart/form-data, files will be sent as different parts of the body, using binary encoding formats (usually as media/jpeg, media/png, …, depending on the media file type).

  • Responses are always in application/json media type.

    • Successful responses (HTTP status codes 2XX and 3XX) are described in this documentation by specifiying the returned JSON fields. For each JSON field, the following properties are described:
      • Name: The name of the field in the JSON object.
      • Req.: Indicates if this field is required or not. When it is required, the server will produce an error when the indicated field is not found in the request.
      • Type: The expected type of the field content. It could be: file, string, integer, number, array.
      • Description: A paragraph describing the purpose and the content of the field.

    • Responses for request errors and server exceptions (HTTP status codes 4XX and 5XX) always follow the same JSON structure:

      1
2
3
4
      {
  "code" : "FaceNotFoundError" ,
  "message" : "Unable to locate a face in the image" 4
}

      Then, they are documented by specifying the available code names and a message example. For different convenient reasons, the server may return more fields in such a JSON object, and the client must ignore them.

    • Finally, bad formed requests, i.e., with from validation errors, will produce a 400 response with "code": "FormValidationError". This particular error code adds to previous JSON structure the optional field "errors", which is an array of 2-tuples, where each tuple indicates the field name and a message of the failure reason. The following example illustrates one of these cases:

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
      {
  "code" : "FormValidationError" ,
  "message" : " Incorrect parameters" ,
  "errors " : [
    [
      "anchorImage" ,
      "This field is required"
    ]
  ]
}
      Similarly to previous case, due to convenience, the server may return more fields in the JSON object, and the client must ignore them.