API docs by Redocly

ID Gateway Registry API (0.1.0)

Download OpenAPI specification:Download

OpenAPI specification for the ID Gateway registry integration endpoints.

The Registry API provides identity verification and sanctions screening through integration with external registries. All endpoints require authentication and explicit user consent for registry lookups.

Features

  • Citizen registry lookup for identity verification
  • Sanctions/PEP screening for AML/CTF compliance
  • Response caching with configurable TTL (5 minutes)
  • Data minimization in regulated mode (GDPR Article 5)
  • Audit logging for all registry operations

Security

  • All endpoints require valid bearer token (JWT)
  • Consent required: registry_check purpose
  • TLS-only transport in production

Lookup citizen record from national registry

Retrieves citizen identity information from the national population registry. Returns full identity attributes including name, date of birth, and address.

Caching: Responses are cached for 5 minutes. Repeated lookups within the TTL window will return cached data without calling the external registry.

Data Minimization: In regulated mode, PII fields (national_id, full_name, date_of_birth, address) are stripped from the response, returning only validation status, source, and timestamps.

Audit: All lookups emit an audit event with action registry_citizen_checked.

Authorizations:
bearerAuth
Request Body schema: application/json
required
national_id
required
string [ 6 .. 20 ] characters ^[A-Z0-9]{6,20}$

National identifier to lookup

Responses

Request samples

Content type
application/json
Example
{
  • "national_id": "CITIZEN123456"
}

Response samples

Content type
application/json
Example
{
  • "national_id": "CITIZEN123456",
  • "full_name": "Alice Marie Johnson",
  • "date_of_birth": "1990-05-15",
  • "address": "123 Main Street, Springfield, IL 62701",
  • "valid": true,
  • "source": "Mock Citizen Registry",
  • "checked_at": "2025-12-11T10:00:00Z"
}

Check sanctions and PEP status

Screens a national ID against sanctions lists, PEP databases, and watchlists. Returns whether the individual is flagged and the source of the flag.

Caching: Responses are cached for 5 minutes to reduce external calls.

Data Minimization: Sanctions records contain no PII (only boolean flag), so no additional minimization is applied.

Audit: All checks emit an audit event with action registry_sanctions_checked and include the screening result (listed/not_listed).

Authorizations:
bearerAuth
Request Body schema: application/json
required
national_id
required
string [ 6 .. 20 ] characters ^[A-Z0-9]{6,20}$

National identifier to screen

Responses

Request samples

Content type
application/json
{
  • "national_id": "CITIZEN123456"
}

Response samples

Content type
application/json
Example
{
  • "national_id": "CITIZEN123456",
  • "listed": false,
  • "source": "Mock International Sanctions Database",
  • "checked_at": "2025-12-11T10:00:00Z"
}