Skip to content

Integrating with the Deduplication Engine

This guide is for developers of client systems — such as HOPE Country Workspace — that use the engine's REST API to deduplicate a set of individuals by their photographs.

Before you start, make sure you understand the deduplication set lifecycle: almost every API error you will encounter is a 409 telling you an operation is not allowed in the set's current state.

API reference

The complete, always-up-to-date endpoint reference is generated from the code and served by the application itself:

  • Swagger UI (interactive): https://<server>/api/rest/swagger/
  • Redoc (reference): https://<server>/api/rest/redoc/
  • OpenAPI schema (machine-readable): https://<server>/api/rest/

This guide focuses on the workflow and semantics that the schema alone doesn't convey.

Authentication

Every request must carry a token:

Authorization: Token <your-token>

Tokens are issued by an engine administrator through the admin panel (see admin guide). A token is bound to a user and an external System; all data you create and read is scoped to that system — you can never see another system's groups or sets.

If your token is missing or invalid you get 401; if the user lacks the API permission you get 403.

Core resources

Resource Endpoint Purpose
Deduplication sets /deduplication_sets/ Create, list, retrieve, delete sets; trigger process, ready, approve, reject
Images /deduplication_sets/{id}/images/ Register image batches; clear to start over
Findings /deduplication_sets/{id}/findings/ Read results (paginated, filterable)
Group config /deduplication_set_groups/{reference_pk}/config/ Read / update per-group thresholds
Group status /deduplication_set_groups/{reference_pk}/status/ Check whether a new set can be created

Two identifiers appear throughout and are yours to choose:

  • Group reference_pk — identifies the group of related deduplication runs, e.g. your program/project ID. Sets created with the same reference_pk belong to the same group and share settings and approved reference data.
  • Image reference_pk — identifies the individual/record an image belongs to, e.g. your individual ID. Findings refer to images by this value.

Images

You register images by providing a reference_pk (your identifier for the individual) and a filename containing the image as a base64 data URL (e.g. data:image/jpeg;base64,/9j/4AAQ...). The engine decodes the payload, stores the file via its images storage backend, and reads it back during processing. If the file cannot be found at processing time, that image is reported in the findings with status code 404.

Where to next