Clients
The client identity system resolves individuals across all participating insurance companies. When you submit a claim or search for history, the system automatically matches clients based on their date of birth and identity documents — ensuring the same person is recognized regardless of which company submitted their data.
The client model
A client represents a unique individual in the shared database. Clients are created automatically when claims are submitted — you never need to create them directly.
Properties
- Name
id- Type
- string (UUID)
- Description
Unique identifier for the client.
- Name
first_name- Type
- string
- Description
The client's first name. Encrypted at rest.
- Name
last_name- Type
- string
- Description
The client's last name. Encrypted at rest.
- Name
date_of_birth- Type
- string (YYYY-MM-DD)
- Description
The client's date of birth. Encrypted at rest.
- Name
id_documents- Type
- array
- Description
All identity documents associated with this client. Each document includes its
type. Document numbers are never returned in API responses.
Identity matching
The system uses a deterministic matching algorithm to resolve clients:
- Date of birth — The client's DOB is hashed and used as the first matching criterion.
- Identity document — At least one document hash (type + number) must match an existing record.
- Both must match — A client is only resolved if the DOB hash AND at least one document hash match the same existing client record.
This means names are informational only — they are stored for display but never used for matching. Two submissions with slightly different name spellings but the same DOB and document number will correctly resolve to the same client.
Document accumulation
When an existing client submits a claim with a new document type they haven't used before (e.g., a national ID after previously only having a passport), the new document is automatically added to their record. Over time, a single client may accumulate multiple identity documents.
DOB mismatch protection
If an identity document matches an existing client but the date of birth doesn't match, the system rejects the submission as a data quality error. This prevents accidental identity merges between different people who happen to share a document number.
Supported document types
- Name
passport- Type
- string
- Description
National passport.
- Name
national_id- Type
- string
- Description
Government-issued national identity card.
- Name
alien_registration- Type
- string
- Description
Alien Registration Certificate (ARC) for foreign residents.
ID number normalization
Before matching, identity document numbers are normalized to prevent duplicates caused by formatting differences:
- Country prefixes are stripped:
CY-12345678→12345678,CY 12345678→12345678 - Whitespace is removed
- Letters are uppercased
This means CY-12345678, CY 12345678, cy12345678, and 12345678 all resolve to the same client.
Privacy & encryption
All client personally identifiable information (PII) is encrypted at the application level:
- Encrypted fields:
first_name,last_name,date_of_birth, and document numbers - Hashed indexes: Date of birth and document numbers are also stored as SHA-256 hashes for matching. These hashes cannot be reversed to recover the original values.
- API responses: Document numbers are never included in API responses. Only the document
typeis returned.