IDFace Match Server¶

Install¶

IDFace Match Server is provided as a Docker image via Amazon ECR. The current version of the server and the docker pull command for it are in your personal account on the customer portal.

Install Docker¶

Since the IDFace Match Server is distributed in a form of Docker image, you need to make sure that you have Docker Engine installed on your machine. Follow the Docker's instruction to install Docker Engine on Ubuntu, CentOS or other supported platform. For Windows you can use Docker Desktop.

Note that by default you need to run docker with sudo. You can disable it if you want.

Download image¶

Follow these steps to install an image via the custom portal:

1. Navigate to your personal account on the custom portal and select the desired image.
2. In the Docker containers section, click the "Generate command" button.
3. Wait for the command to be generated. Once ready, click the "Copy" button to copy the pull command.
4. Use the copied command in Terminal or another tool.

Once the Docker image is pulled, you may want to change its name since the original name is quite long. Use docker tag to create a second short image name:

docker tag \
    367672406076.dkr.ecr.eu-central-1.amazonaws.com/idfacematch-server-eval:1.1.0 \
    idfacematch-server-eval:1.1.0

Now you can use idfacematch-server-eval:1.1.0 with the Docker commands. The old name is still available if you need it.

Start container¶

To run the application, start the Docker container:

docker run --name idfacematch-server -d -p 8080:8080 idfacematch-server-eval:1.1.0

The application is ready once it prints Ready into the log stream. You can also call the /info endpoint. Once it returns 200 OK, the application has started.

The OpenAPI specification is available at http://localhost:8080/openapi.json. You can use Postman or Swagger UI to explore it. Online Swagger UI is available at https://petstore.swagger.io.

Generate a face template¶

To generate a face template, send an image to the /detect endpoint. The content type does not matter, but make sure it is not a multipart request:

curl -s --data-binary @image.jpg  http://localhost:8080/detect

Image can be in JPG, PNG or BMP formats. The response will contain information about all faces on the image, including a face box and a template:

{
  "faces": [
    {
      "box": {
        "x": 967,
        "y": 124,
        "width": 183,
        "height": 254
      },
      "template": "wRkUy8zdCs.."
    }
  ]
}

The coordinates start from the top-left corner of the image. The faces list will be empty if no faces were detected.

The /detect endpoint supports these optional query parameters:

Match templates¶

To match two templates, prepare this JSON file:

{
  "source": "wRkUy8zdCs...",
  "target": "32k3vAHk6T..."
}

And send it to the /match endpoint:

curl -s --header "Content-Type: application/json" \
        --data-binary @templates.json http://localhost:8080/match

Example of a response:

{ "probability": 0.83 }

The matching result contains the probability field which is the main factor in determining whether two biometric templates belong to the same identity or different ones. It ranges from 0 (different identities) to 1 (same identity) and the threshold for the decision is 0.5.

Additionaly you can select a calibration:

{
  "source": "wRkUy8zdCs...",
  "target": "32k3vAHk6T...",
  "calibration": "SOFT"
}

Calibration allows you to set the desired FNMR/FMR balance.

Available values for calibration:

• REGULAR (the default) targets low FMR (0.00001).
• SOFT achieves lower FNMR while still having acceptable FMR (0.0001).
• HARD targets extra low FMR (0.000001) with possibly higher FNMR.

Licensing¶

IDFace Match uses software protection to protect ID R&D's intellectual property. The Server's image contains a license key, which will automatically be used on a container's startup.

License variants¶

IDFace Match Server is distributed in 2 variants: Eval (for evaluation) and Prod (for production). They differ in limitations the license imposes:

• The evaluation variant will function for 90 days from the release date.

• The production variant will function for 1 year from the release date.

The expiration date can be found in the key's file name. It is printed when you start the Server:

License "license/rte/prod-license-2025-09-01.adminmode.v2c" installed

This key will expire on September 1, 2025.

Once the license has expired you either need to update to the new IDFace Match version or contact us for the new license key.