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
  20221017	2e0cb1f8dd755e2c9caf18c48c2b550dc7e64e57205b82c3fc5c62d6	9040 bits in binary format	das-Face v3.12	veridas-009
  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:

    {
      "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:

    {
      "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.

API Usage tutorial

The following video shows a short tutorial on how to use the das-Face API.

Integration Review

The below document summarizes general recommendations/improvements, mandatory checks and several weak points an integration may have, so we strongly suggest paying special attention to them before moving forward as not doing so might cause issues in production.

Veridas Integration Review Document: Download