Skip to content

Considerations

DEPRECATION NOTICE: Some endpoints will be deprecated on Q2 2022. Such endpoints are conveniently identified in the API definition section of this document.

The following are some general considerations about this API that must be taken into account before consuming the service.

Compatibility

This service exposes a RESTful API designed to be backwards-compatible (whenever possible). An API is said to be backwards-compatible if a client written against a previous version of the API will keep working against future ones.

The following changes are considered backwards compatible:

  • Adding new resources (on new URIs)
  • Adding new optional request form fields or JSON properties
  • Adding new optional query parameters
  • Adding new JSON properties to existing API responses
  • Changing the order of JSON properties on existing API responses
  • Changing the order of items on JSON object or array properties (unless the documentation states they are ordered)
  • Adding new optional headers in requests
  • Adding new headers in responses

The following changes are considered backwards incompatible (breaking changes):

  • Removing API resources
  • Renaming API resources (changing URIs)
  • Adding new required request form fields, JSON properties, query parameters or headers
  • Making any existing optional request form fields, JSON properties, query parameters or headers required
  • Removing existing request form fields, JSON properties, query parameters or headers
  • Changing the meaning of existing request form fields, JSON properties, query parameters or headers
  • Adding new request form fields, JSON properties, query parameters or headers that alter the meaning of existing ones
  • Changing the type of existing request form fields or JSON properties (from string to number for example)
  • Changing the format or maximum length of existing opaque string properties with documented conflicting constraints

Backwards incompatible (breaking) changes may be introduced by bumping the API version, as explained on the Versioning section. In this scenario, previous versions of the API may be marked as deprecated and stop receiving new features. Should this happen, these old versions will be available for some agreed period of time, until they are eventually removed.

Veridas will announce in advance this deprecation and removal process (also called sunsetting) to ensure that users have enough time to migrate to the newest version of the API without causing any downtime or service disruptions.

Authentication

This service sits behind a gateway responsible for authenticating end users and routing requests. The authentication method is API key based.

Requests

Requests must meet the following requirements:

  • Content type must be either multipart/form-data, or application/json.
  • The API can only be accessed via TLS. Always validate server certificates and never trust a VeriSaaS endpoint that offers an invalid certificate.

The documentation for all the endpoints that require a POST method has been written assuming a multipart/form-data MIME type. However JSON is equally accepted for all such endpoints and the behavior should be the same.

The following differences should be taken into account when consuming an API with a JSON body:

  • Content type must be set to application/json. Otherwise the API will assume a multipart body.
  • All the parameters that have been marked as body parameters in the endpoints’ descriptions (location: body) can be sent in the JSON body. For example, in the /credential/qr-code endpoint, the parameters selfieImage and contextualData are marked as such. Hence, these parameters can also appear in the JSON object.
  • Query string parameters will continue to be so regardless of the body format.
  • Mandatory parameters (marked as ‘required’) will continue to be so regardless of the body format.
  • All JSON values MUST be encoded in base64, whereas multipart bodies need not, except where explicitly stated. This is a relevant detail when sending binary data.

Some endpoints require a biometric model to be specified. These endpoints have been conveniently marked with the placeholder {model}, as this parameter is passed in the path.

Example: 

/dasfaceqr/v2/3a9e9d5ffd5de4c212c2aff26eeca523fb69754e604894520b32e4ed/credential/qr-code
Models can be specified either by their hash (as in the example above) or by a tag. An example of a model tag is given below. 
/dasfaceqr/v2/20190813/credential/qr-code
Available models can be obtained with the GET /models endpoint.

Versioning

The API version will be included in the URL, after the base url and before the endpoint:

https://< base_url >/<service>/**v{number:integer}**/<endpoint>

Non-backwards compatible changes will cause a version increment. As of now, the API only supports the v1 version.