Considerations¶

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

Security¶

This service is fortified by a comprehensive security framework designed to protect and manage access to the API. or detailed insights into the security architecture and measures, please consult the Veridas Security Mechanisms Documentation.

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.

Requests¶

The multipart/form-data content type must be used on every POST request when a request body is required.
Sample files sent to VCSP as part of POST requests must have one of the following content types:
- audio files:
  - audio/wav
  - audio/x-wav
  - audio/wave
- image files:
  - image/jpg
  - image/png
  - image/tiff

The API is HTTP-based and uses SSL everywhere with valid certificates. For security reasons, customers should never trust VCSP endpoints exposing invalid certificates.
Endpoints attempt to conform to the design principles of Representational State Transfer (REST).
Each request is uniquely identified, which might be helpful to trace support cases. This unique id is returned in the X-Request-Id header. The format of the unique id is a UUID in its hexadecimal form.
Every timestamp stored in the system is referenced to Zulu timezone (UTC+00). A Z character is present at the end of every timestamp field within API response.

Responses¶

All responses will be encoded using JSON, regardless of the accepted content type specified by the client.
Responses will return a suitable HTTP status code indicating if the request was successful (2xx), a client error occurred (4xx) or a server error occurred (5xx).
Error responses received as a result of an unsuccessful request will have following format:

Field	Description
error	Error code
title	Title of the error
reason	Human readable reason of the error cause
details	Metadata about the error (optional)

Example:

{
    "error": "audio_not_authentic",
    "title": "Audio not authentic",
    "reason": "Audio is not authentic",
    "details": {
        "authenticity_threshold": 0.8,
        "authenticity_score": 0.03283321443788212
    }
}

Applying boolean logic to requests¶

VCSP allow adding Boolean logic to certain operations. To do this, it uses JSON Logic, a specification for processing rules written in JSON format that allows defining logic or a set of conditions using a specific JSON structure.

Matching 1:N filtering¶

The 1:N matching endpoint allows for attribute-based filtering prior to performing the actual search. This reduces N to only those subjects that meet the specified filter.

Currently, subject tags are the only attribute allowed for this filtering. Below are several examples of how to specify the filter parameter for the 1:N matching operation, using JSON Logic to apply different Boolean logic:

// Filter those subjects that belong to production blacklist
filter = {
  "tag": "prod:blacklist"
}

// Filter those subjects that does not belong to production blacklist
filter = {
  "NOT": {
    "tag": "prod:blacklist"
  }
}

// Filter those subjects that are from spain and live in madrid.
filter = {
  "AND": [
    {
      "tag": "country:spain"
    },
    {
      "tag": "city:madrid"
    }
  ]
}

// Filter those subjects that belong to finance or marketing department but don't belong to west region
filter = {
  "AND": [
    {
      "NOT": {
        "tag": "region:west"
      }
    },
    {
      "OR": [
        {
          "tag": "department:finance"
        },
        {
          "tag": "department:marketing"
        }
      ]
    }
  ]
}

Audio constraints¶

Audio format: WAV.
Number of channels: Mono (single voice) or stereo (specifying the target channel).
Audio encoding: PCM16 or G711 (mu-law/a-law). We recommend using the PCM16 encoding, as it will have better performance with the voice biometry engine.
Sampling frequency: 8 kHz or 16 kHz.
Minimum amount of subject speech: 3s for all endpoints.
Maximum audio duration: 30s for all endpoints.

Other formats could be converted to these conditions using the appropriate tools (e.g. ffmpeg). However, Veridas cannot guarantee the performance of the voice biometry engine with such samples.

If the audio contains multiple voices, the resulting voice credential will incorporate information from all these voices, which can adversely impact the accuracy of future verification attempts.

Face Images constraints¶

Supported image formats: JPEG/JFIF, JPEG/EXIF, JPEG Blob, PNG, and TIFF.
Face must be of at least 80px between eyes to ensure optimum verification and biometric credential computations.
Face must be of at least 150px width to ensure it can be processed by the face liveness detection systems. To increase accuracy, faces with more than 320px width are recommended.
Face is expected to be frontal with the camera in the photograph. Less than 30 degrees in head pose rotation (roll, pitch, yaw) is the optimum.
Face appearance must be with no significant fish-eye distortion.

Asynchronous task management in VCSP¶

Some of the operations available in the VCSP can be processed either synchronously or asynchronously, depending on the expected response time, to optimize resource utilization for our clients.

Synchronous and asynchronous processing¶

Synchronous processing: operations that complete almost instantly are processed synchronously. In these cases, the client sends an HTTP request and waits for the response on the same connection, receiving the results immediately.

Asynchronous processing: tasks requiring more processing time are handled asynchronously. Here, the client sends a request and receives an immediate acknowledgment that the task has been accepted for processing. However, the final result is not available right away. Instead, a unique task_id is provided in the response body. This task_id allows the client to query the status and retrieve the results once the task is completed.

Workflow for asynchronous tasks¶

Task initiation: the client initiates an operation that is processed asynchronously. For example, when performing a batch enrollment using the /v1/enrollments/batch endpoint, the client submits a request containing a TAR file with biometric samples and a JSON file detailing each applicant.
Receiving the task_id: upon receiving the request, VCSP responds with an HTTP status code 202 Accepted, indicating that the request has been accepted for processing. The response body includes a unique task_id that identifies the asynchronous task.
Monitoring task status: the client can monitor the task's progress by querying the /v1/tasks/{task_id} endpoint. This endpoint provides information about the current state of the task. Tasks may have one of the following statuses:
- PENDING: The task has been accepted but has not yet started processing.
- IN_PROGRESS: The task is currently being processed.
- FAILED: The task has completed but encountered an error during processing.
- COMPLETED: The task has been successfully processed.
Retrieving task result: once the task is completed, the client can obtain the final results by accessing the /v1/tasks/{task_id}/result endpoint. This endpoint delivers a detailed report indicating whether each biometric sample in the batch was processed successfully or if any issues were encountered during processing.

The following sequence diagram illustrates the asynchronous task workflow:

sequenceDiagram participant Client participant VCSP Client->>VCSP: Initiate asynchronous task VCSP-->>Client: 202 Accepted with task_id Client->>VCSP: Query task status using task_id VCSP-->>Client: Return current task status Client->>VCSP: Retrieve task result using task_id VCSP-->>Client: Return task result

For further details on which endpoints may return asynchronous responses, please visit the API definition section.