Skip to main content

Hits API

The Hits endpoint of the Investigation Service exposes operations on hits – the records that document the relationship between a probe and a candidate after the examiner has reached a conclusion. Hits are the official, court-relevant artefact of the comparison process.

For the conceptual background see Examinations and Hits.

Operations​

OperationVerb / path
Hit creationPOST hits
Hit retrievalGET hits/{hitId}
Hit soft-deletePOST hits/{hitId}/delete

Hits are immutable in the sense that they cannot be updated. To "change a decision" the examiner deletes the existing hit (which is soft-deleted, retained for audit, and excluded from counters) and creates a new one with the corrected relationType.

Client instance​

using Innovatrics.Abis.Rest.Api;

static HitsApi GetHitsApiInstance(string accessToken)
{
    return new HitsApi(BuildAbisConfiguration(accessToken));
}

Creation​

The createHit operation records an examiner's decision. The required fields depend on the modality (latent print, face, iris, DNA, etc.). The supported relation types are Individualized, Excluded and Inconclusive.

var ha = GetHitsApiInstance(accessToken);

var createHitRequest = new CreateHitRequest
{
    IdentifyApplicantId  = Guid.Parse("probe-applicant-id"),
    IdentifyCandidateId  = Guid.Parse("candidate-applicant-id"),
    RelationType         = "INDIVIDUALIZED",
    VerificationScore    = 85.5,
    FromLatentId         = 1,
    ToFingerprintId      = 2,
    Note                 = "Strong match found during comparison",
    MatchingMinutiaePoints = new List<MatchingMinutiaePoints>
    {
        new MatchingMinutiaePoints
        {
            Score = 95.0,
            ProbeMinutiaePoint = new MinutiaePoint { Id = 1, X = 100, Y = 200, Angle = 45, Type = "ending" },
            ReferenceMinutiaePoint = new MinutiaePoint { Id = 2, X = 102, Y = 201, Angle = 47, Type = "ending" }
        }
    }
};

var hitResponse = ha.CreateHit(createHitRequest);
Console.WriteLine($"Hit created with ID: {hitResponse.Id}");

Retrieval​

getHit returns everything required to render the hit in the UI – relation type, scores, the linked probe / reference identifiers, the matching minutiae (for prints) and the free-text note.

var ha = GetHitsApiInstance(accessToken);
var hitResponse = ha.GetHit("existing-hit-id");

Console.WriteLine($"Hit ID: {hitResponse.Id}");
Console.WriteLine($"Relation Type: {hitResponse.RelationType}");
Console.WriteLine($"Verification Score: {hitResponse.VerificationScore}");
Console.WriteLine($"Note: {hitResponse.Note}");

Deletion​

Hits are soft-deleted. They remain in the database for audit purposes and are excluded from hit counters and aggregations.

var ha = GetHitsApiInstance(accessToken);
var deletedHit = ha.DeleteHit("hit-to-delete");

Console.WriteLine($"Hit deleted: {deletedHit.Id}");
Console.WriteLine($"Deleted at: {deletedHit.DeletedAt}");

Aggregated views​

  • The list of hits per examination is part of the examination response.
  • The list of hits per evidence is exposed by the evidence response and can be retrieved using the standard list endpoints.
  • The list of hits per case is exposed by the case response.

These three views correspond to the three UI surfaces that show hits (examination sidebar, evidence Hits table, case Hits table).