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: 20210203
      • Model hash: bab0b604e3cb088dd6c484a9774505f5545d3e5837874f3ec0172af5
      • Credential length: 9040 bits in binary format.
    • Model tag: 20200514
      • Model hash: 904fa9ef6e71ef541f20a95d3dc97821b7af43b8cd2c1bb3eb09df15
      • Credential length: 2896 bits in binary format.
  • 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.

The following are the average response times of the main endpoints:

Endpoint Average (ms)
/v2/authenticity/photo 1075
/v2/authenticity/photo/unequal-pair 1163
/v2/credential/photo 374
/v2/verification/credential 344
/v2/verification/photo 1274
/v2/verification/video 2223
/v2/challenges/analysis/video-photo 4257

"Note: response time for /v2/verification/credential may increase up to 910ms when verifying a photo versus a credential generated with the model bab0b604e3cb088dd6c484a9774505f5545d3e5837874f3ec0172af5"