Visual Annotations API

The Visual Annotations endpoints of the Investigation Service expose CRUD operations on the annotation layer drawn over examinations. Annotations are stored as a separate layer that does not modify the source image, and can be linked between probe and candidate to highlight matching features in the Hit detail report.

Annotations are scoped to the examination they were drawn in – two examinations that compare against the same biometric sample have fully independent annotation layers.

Operations

Operation	Verb / path
Annotation creation	PUT visual-annotations/{annotationId}/create
Annotation retrieval	GET visual-annotations/{annotationId}
Annotation update	PUT visual-annotations/{annotationId}/update
Annotation soft-delete	POST visual-annotations/{annotationId}/delete
Linked annotation create	PUT linked-visual-annotations/{linkId}/create
Linked annotation retrieval	GET linked-visual-annotations/{linkId}
Linked annotation soft-delete	POST linked-visual-annotations/{linkId}/delete

Annotation shapes

The supported annotation shapes are:

• Freehand stroke – polyline of points.
• Rectangle – axis-aligned bounding box.
• Ellipse – defined by a centre and two radii.
• Arrow – two endpoints; the head is rendered at the second point.
• Text label – a position and a text string.

Every annotation is associated with a snapshot of the underlying examination, so the annotation always references a stable view of the image even after subsequent edits.

Sample – creating a rectangle annotation

C#

var va = new VisualAnnotationsApi(BuildAbisConfiguration(accessToken));

var createAnnotationRequest = new CreateVisualAnnotationRequest
{
    ExaminationId = Guid.Parse("existing-examination-id"),
    SnapshotId    = Guid.Parse("snapshot-id"),
    Shape         = AnnotationShape.RECTANGLE,
    Geometry      = new RectangleGeometry { X = 120, Y = 80, Width = 60, Height = 40 },
    Color         = "#FF0000",
    Note          = "Distinct ridge cluster"
};

var annotationId = Guid.NewGuid().ToString();
var annotation = va.CreateVisualAnnotation(annotationId, createAnnotationRequest);
Console.WriteLine($"Annotation created with ID: {annotation.Id}");

Java

VisualAnnotationsApi va = new VisualAnnotationsApi(buildAbisClient(accessToken));

CreateVisualAnnotationRequest createAnnotationRequest = new CreateVisualAnnotationRequest()
        .examinationId(UUID.fromString("existing-examination-id"))
        .snapshotId(UUID.fromString("snapshot-id"))
        .shape(CreateVisualAnnotationRequest.ShapeEnum.RECTANGLE)
        .geometry(new RectangleGeometry().x(120).y(80).width(60).height(40))
        .color("#FF0000")
        .note("Distinct ridge cluster");

String annotationId = UUID.randomUUID().toString();
VisualAnnotationResponse annotation = va.createVisualAnnotation(annotationId, createAnnotationRequest);
System.out.println("Annotation created with ID: " + annotation.getId());

Linking annotations

To indicate that two annotations represent the same physiological feature in the probe and in the candidate, create a linked annotation that references both annotation IDs.

C#

var lva = new LinkedVisualAnnotationsApi(BuildAbisConfiguration(accessToken));

var createLinkRequest = new CreateLinkedVisualAnnotationRequest
{
    ProbeAnnotationId     = Guid.Parse("probe-annotation-id"),
    CandidateAnnotationId = Guid.Parse("candidate-annotation-id"),
    Note = "Matching delta"
};

var linkId = Guid.NewGuid().ToString();
var link = lva.CreateLinkedVisualAnnotation(linkId, createLinkRequest);
Console.WriteLine($"Link created with ID: {link.Id}");

Java

LinkedVisualAnnotationsApi lva = new LinkedVisualAnnotationsApi(buildAbisClient(accessToken));

CreateLinkedVisualAnnotationRequest createLinkRequest = new CreateLinkedVisualAnnotationRequest()
        .probeAnnotationId(UUID.fromString("probe-annotation-id"))
        .candidateAnnotationId(UUID.fromString("candidate-annotation-id"))
        .note("Matching delta");

String linkId = UUID.randomUUID().toString();
LinkedVisualAnnotationResponse link = lva.createLinkedVisualAnnotation(linkId, createLinkRequest);
System.out.println("Link created with ID: " + link.getId());

Linked annotations show up as paired annotations in the Comparison Tool and as paired callouts in the Hit detail report.