Skip to main content

Examinations API

The Examinations endpoint of the Investigation Service exposes CRUD operations on examinations and on their ACE-V state. Examinations are analysis sessions where evidence is processed, analysed and compared for identification purposes – see ACE-V methodology for the conceptual background.

Operations​

OperationVerb / path
Examination creationPOST examinations
Examination retrievalGET examinations/{examinationId}
Examination updatePUT examinations/{examinationId}/update
Examination soft-deletePOST examinations/{examinationId}/delete
Examination snapshotsGET examinations/{examinationId}/snapshots
Examination statusGET examinations/{examinationId}/status

Client instance​

using Innovatrics.Abis.Rest.Api;

static ExaminationsApi GetExaminationsApiInstance(string accessToken)
{
    return new ExaminationsApi(BuildAbisConfiguration(accessToken));
}

Examination kinds and creation triggers​

Before calling the API it is worth recalling what kinds of examinations exist and how the platform creates them. The full conceptual story is in Examinations and Hits; the table below summarises the integration view.

Examination kindAPI view
AnalysisOne examination per analysed impression. assetType matches the parent evidence (print, latent, face). Created either by integrator code or by the platform itself, depending on configuration. Pre-condition: the parent evidence has passed Technical Assessment.
ComparisonOne examination per probe / candidate pair. Parented to the Analysis. Created when an examiner selects a candidate from an identification result.
VerificationOne examination per Comparison whose resolution requires verification. Used in non-blind ACE-V. Triggering of the verification step is configurable per deployment.
VideoOne examination per detected person tracklet inside a video. Created automatically by the Video Manager pipeline; not part of the manual ACE-V workflow. Integrators do not create video examinations directly.

ACE-V examinations (Analysis / Comparison / Verification) are only valid for assetType values print, latent and face; the API rejects attempts to create them on other or dna evidence. Video examinations are produced by the platform and are not creatable through the public create endpoint.

Creation​

Below is a typical POST examinations call that creates an Analysis examination on a latent-print evidence.

var exa = GetExaminationsApiInstance(accessToken);

var createExaminationRequest = new CreateExaminationRequest
{
    EvidenceId = Guid.Parse("existing-evidence-id"),
    AssetType  = AssetType.Latent,
    Type       = ExaminationType.EXAMINATION,
    AssignedToId = 1,
    AvailableForIdentification = false,
    Name       = "Latent Analysis – primary examiner",
    Modality   = ModalityType.Latent
};

var examinationResponse = exa.CreateExamination(createExaminationRequest);
Console.WriteLine($"Examination created with ID: {examinationResponse.Id}");

The assetType of the new examination must be the same as the assetType of the parent evidence – face on a face evidence, print or latent on a fingerprint / latent evidence. The platform rejects mismatched combinations.

Retrieval​

var exa = GetExaminationsApiInstance(accessToken);
var examinationResponse = exa.GetExamination("existing-examination-id");

Console.WriteLine($"Examination Name: {examinationResponse.Name}");
Console.WriteLine($"Evidence ID: {examinationResponse.EvidenceId}");
Console.WriteLine($"Type: {examinationResponse.Type}");
Console.WriteLine($"Assigned To: {examinationResponse.AssignedToId}");

Update – including ACE-V state transitions​

updateExamination is also the endpoint that drives the ACE-V state machine. Setting examinationStatus.acevStatus and acevResolution is what moves the examination through Analysis, Comparison/Evaluation and Resolved.

var exa = GetExaminationsApiInstance(accessToken);

var updateExaminationRequest = new UpdateExaminationRequest
{
    AssignedToId = 2,
    AvailableForIdentification = true,
    Type = ExaminationType.EXAMINATION,
    Name = "Updated Fingerprint Analysis",
    ExaminationStatus = new ExaminationStatus
    {
        AcevStatus     = ExaminationAcevStatus.ANALYSIS,
        AcevResolution = ExaminationAcevResolution.SUITABLE_FOR_IDENTIFICATION,
        Note           = "Ready for comparison phase"
    }
};

var updated = exa.UpdateExamination("existing-examination-id", updateExaminationRequest);
Console.WriteLine($"Examination updated: {updated.Name}");

Deletion​

var exa = GetExaminationsApiInstance(accessToken);
var deleted = exa.DeleteExamination("examination-to-delete");

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

Snapshots​

Snapshots are the per-edit checkpoints captured by the Latent Editor. The list endpoint returns every snapshot with its asset type, the original / non-original flag and the creation timestamp.

var exa = GetExaminationsApiInstance(accessToken);
var snapshots = exa.GetExaminationSnapshots("existing-examination-id");

Console.WriteLine($"Found {snapshots.Count} snapshots");
foreach (var snapshot in snapshots)
{
    Console.WriteLine($"Snapshot ID: {snapshot.Id}");
    Console.WriteLine($"Asset Type: {snapshot.AssetType}");
    Console.WriteLine($"Original: {snapshot.IsOriginal}");
    Console.WriteLine($"Created At: {snapshot.CreatedAt}");
}

Status history​

getExaminationStatus returns the full ACE-V status history of an examination. Every entry includes the user, timestamp, ACE-V status, resolution and note – exactly what is shown in the examination sidebar.

var exa = GetExaminationsApiInstance(accessToken);
var statusList = exa.GetExaminationStatus("existing-examination-id");

foreach (var status in statusList)
{
    Console.WriteLine($"Status ID: {status.Id}");
    Console.WriteLine($"ACEV Status: {status.AcevStatus}");
    Console.WriteLine($"ACEV Resolution: {status.AcevResolution}");
    Console.WriteLine($"Created At: {status.CreatedAt}");
    Console.WriteLine($"Note: {status.Note}");
    Console.WriteLine("---");
}