Identification and Verification API

This chapter explains how to invoke biometric matching from third-party systems – both identification (1:N) against a criminal gallery, and verification (1:1 or 1:few) when comparing a probe to one or several known references.

For the conceptual background see Biometric matching.

Operations

Operation	Purpose	Verb / path
Identification, stored probe	The probe is a stored applicant; matched against a gallery.	POST applicants/{externalId}/identify
Identification, transient probe (image)	Probe sent in the body as an image.	POST identify/images
Identification, transient probe (template)	Probe sent in the body as a template.	POST identify/template
Verification 1:1 / 1:few, stored probe	Probe stored, references stored.	POST applicants/{externalId}/verify/references
Verification 1:1 / 1:few, transient probe	Probe sent in the body, references stored.	POST verify/template/references, POST verify/images/references
Verification 1:1 / 1:few, fully transient	Probe and references both in the body.	POST verify/template/template, POST verify/template/images, POST verify/images/template, POST verify/images/images
Identification on stored data	Probe stored, matched against stored gallery; persisted.	POST identify/reference

Choosing a matching mode

Scenario	Recommended mode
Search a latent print against the criminal gallery, the result must end up in the search history.	POST applicants/{externalId}/identify (fully-stateful) – or the equivalent identification endpoint of the Investigation Service.
Quick, ad-hoc comparison between two pieces of evidence that were just received and should not be persisted.	Stateless verification, e.g. POST verify/images/images.
External RMS sends a face image of a suspect, ABIS must return the candidates without persisting the probe.	Semi-stateful identification, e.g. POST identify/images.
Booking workflow: a freshly enrolled criminal record must run a 1:N deduplication search against the criminal gallery.	Fully-stateful, POST applicants/{externalId}/identify.

Sample – stateful identification of a stored probe

C#

var matchingApi = new MatchingApi(BuildAbisConfiguration(accessToken));

var identifyRequest = new IdentifyRequest
{
    Galleries        = new List<string> { "criminal-applicants", "wanted-persons" },
    CandidateCount   = 50,
    ThresholdOverride = 5000,
    Modalities       = new List<Modality> { Modality.Fingerprint, Modality.Face },
    SaveToHistory    = true
};

var identifyResponse = matchingApi.IdentifyStoredApplicant("CR-2026-000123", identifyRequest);

foreach (var candidate in identifyResponse.Candidates)
{
    Console.WriteLine($"{candidate.ExternalId} - score {candidate.Score}");
}

Java

MatchingApi matchingApi = new MatchingApi(buildAbisClient(accessToken));

IdentifyRequest identifyRequest = new IdentifyRequest()
        .galleries(List.of("criminal-applicants", "wanted-persons"))
        .candidateCount(50)
        .thresholdOverride(5000)
        .modalities(List.of(Modality.FINGERPRINT, Modality.FACE))
        .saveToHistory(true);

IdentifyResponse identifyResponse =
        matchingApi.identifyStoredApplicant("CR-2026-000123", identifyRequest);

for (Candidate candidate : identifyResponse.getCandidates()) {
    System.out.println(candidate.getExternalId() + " - score " + candidate.getScore());
}

Sample – stateless verification of two transient images

C#

var verifyRequest = new VerifyImagesRequest
{
    Probe     = new Image { Format = "wsq", DataBytes = LoadAsBase64("probe.wsq") },
    Reference = new Image { Format = "wsq", DataBytes = LoadAsBase64("reference.wsq") }
};

var verifyResponse = matchingApi.VerifyImagesImages(verifyRequest);
Console.WriteLine($"Score: {verifyResponse.Score} (matches threshold: {verifyResponse.IsMatch})");

Java

VerifyImagesRequest verifyRequest = new VerifyImagesRequest()
        .probe(new Image().format("wsq").dataBytes(loadAsBytes("probe.wsq")))
        .reference(new Image().format("wsq").dataBytes(loadAsBytes("reference.wsq")));

VerifyResponse verifyResponse = matchingApi.verifyImagesImages(verifyRequest);
System.out.println("Score: " + verifyResponse.getScore() +
        " (matches threshold: " + verifyResponse.getIsMatch() + ")");

Latent-specific options

When identifying a latent print the request can include:

• rotation – maximum amount of rotation (degrees, default 180°);
• identificationSpeed – lower values give higher accuracy at the cost of latency;
• mask – the polygon describing the region of interest;
• gallerySelector – may include the criminal gallery (case-to-case search) in addition to applicant galleries.

Modality masks

A modality mask declares which modality positions are used in a request – e.g. only the right index finger and the left thumb. Masks are useful for partial captures, for restricting expensive modalities or for enforcing matching policies (for example, "always match only against the rolled position").

Persistence and search history

A request flagged with saveToHistory=true is persisted by the Investigation Service – the search itself, its parameters and the full candidate list become part of the case search history. The persisted record can be retrieved later through the Cases / Evidences API to resume work where it was left off.