Dependant Module

Immutable rows — dependant fields are never updated in place. Every change produces a new row (status = ACTIVE); the old row becomes status = DISCARDED. Follow previous_version_id links to walk version history.

Overview

A dependant represents a family member linked to a primary user (spouse, child, parent, sibling, etc.). The SELF dependant is a special row that mirrors the user’s own identity — it is managed automatically by the server and cannot be created or deleted via this API.

Immutability Model

When you PATCH /users/{user_id}/dependants/{id}, the server:

Sets the old row status → DISCARDED
Inserts a new row with a fresh UUID and previous_version_id = old_id
Returns the new (current) row

The new row’s previous_version_id points back to the discarded row, so version history is walked newest-to-oldest.

Auth Guards by Endpoint

Endpoint	JWT user	Admin key	Notes
`POST /users/{user_id}/dependants`	✓ own only	✓	`relationship = SELF` not allowed
`POST /users/{user_id}/dependants/bulk`	✓ own only	✓	Atomic batch insert, max 50. `relationship = SELF` not allowed
`GET /users/{user_id}/dependants`	✓ own only	✓	Returns `ACTIVE` rows; filter by `relationship`
`GET /users/{user_id}/dependants/{id}`	✓ own only	✓	403 if accessing another user’s
`PATCH /users/{user_id}/dependants/{id}`	✓ own only	✓	SELF not allowed
`DELETE /users/{user_id}/dependants/{id}`	✓ own only	✓	Sets `status → DISCARDED`. SELF not allowed

SELF Dependant

Every user has exactly one active relationship = SELF dependant. It is created automatically on POST /users/{user_id}/complete_onboarding (which takes a required salutation field) and re-versioned when PATCH /users/{user_id} changes first_name, last_name, dob, or gender. Attempting to create, update, or delete SELF via the dependants API returns 400 DE_603.

Exact-Duplicate Skip on Create

POST /users/{user_id}/dependants and POST /users/{user_id}/dependants/bulk both check, before inserting, whether an active row already exists with every field of the payload identical (relationship, salutation, first_name, last_name, date_of_birth, gender).

Exact match found → no row is inserted. The response (still 201) carries the existing row.
Any field differs (including date_of_birth) → a new row is inserted.

This makes draft re-submissions and network retries idempotent without requiring the client to handle a 4xx. Two SPOUSE entries with different DOBs are treated as two distinct dependants and both inserted.

Relationship Values

Value	Description
`SELF`	The user themselves (system-managed)
`SPOUSE`	Husband or wife
`MOTHER`	Mother
`FATHER`	Father
`CHILD`	Son or daughter
`FATHER_IN_LAW`	Father-in-law
`MOTHER_IN_LAW`	Mother-in-law
`SIBLING`	Brother or sister

Salutation Values

salutation is required on create and present on every response; it is optional on update (send it only to change it):

Value	Description
`MR`	Mr
`MRS`	Mrs
`MS`	Ms
`MASTER`	Master (typically for young males)

Endpoints

POST /users/{user_id}/dependants

Add a new dependant. relationship = SELF not allowed.

POST /users/{user_id}/dependants/bulk

Atomically insert up to 50 dependants in one request. relationship = SELF not allowed.

GET /users/{user_id}/dependants

Paginated list. Defaults to status = ACTIVE. JWT users see only their own.

GET /users/{user_id}/dependants/{id}

Fetch a single dependant by UUID.

PATCH /users/{user_id}/dependants/{id}

Update fields. Produces a new immutable row; old row is discarded.

DELETE /users/{user_id}/dependants/{id}

Discard a dependant (status → DISCARDED). SELF not allowed.

Request / Response Examples

curl -X POST http://localhost:8080/users/047382910564/dependants \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "relationship": "SPOUSE",
    "first_name": "Mary",
    "last_name": "Doe",
    "date_of_birth": "1992-08-20",
    "gender": "FEMALE",
    "salutation": "MRS"
  }'

{
  "id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001",
  "primary_user_id": "047382910564",
  "relationship": "SPOUSE",
  "first_name": "Mary",
  "last_name": "Doe",
  "date_of_birth": "1992-08-20",
  "gender": "FEMALE",
  "salutation": "MRS",
  "status": "ACTIVE",
  "previous_version_id": null,
  "created_at": "2026-04-12T10:00:00Z",
  "last_modified_at": "2026-04-12T10:00:00Z"
}

curl -X POST http://localhost:8080/users/047382910564/dependants/bulk \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "dependants": [
      {
        "relationship": "SPOUSE",
        "first_name": "Mary",
        "last_name": "Doe",
        "date_of_birth": "1992-08-20",
        "gender": "FEMALE",
        "salutation": "MRS"
      },
      {
        "relationship": "CHILD",
        "first_name": "James",
        "last_name": "Doe",
        "date_of_birth": "2015-03-10",
        "gender": "MALE",
        "salutation": "MASTER"
      }
    ]
  }'

{
  "data": [
    {
      "id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001",
      "primary_user_id": "047382910564",
      "relationship": "SPOUSE",
      "first_name": "Mary",
      "last_name": "Doe",
      "date_of_birth": "1992-08-20",
      "gender": "FEMALE",
      "salutation": "MRS",
      "status": "ACTIVE",
      "previous_version_id": null,
      "created_at": "2026-04-12T10:00:00Z",
      "last_modified_at": "2026-04-12T10:00:00Z"
    },
    {
      "id": "01926b3a-7c2e-7d4f-a1b2-c3d4e5f60002",
      "primary_user_id": "047382910564",
      "relationship": "CHILD",
      "first_name": "James",
      "last_name": "Doe",
      "date_of_birth": "2015-03-10",
      "gender": "MALE",
      "salutation": "MASTER",
      "status": "ACTIVE",
      "previous_version_id": null,
      "created_at": "2026-04-12T10:00:00Z",
      "last_modified_at": "2026-04-12T10:00:00Z"
    }
  ]
}

Error Codes

Code	HTTP	Description
`DE_600`	500	Internal server error
`DE_601`	404	Dependant not found
`DE_602`	403	JWT user accessing another user’s dependant
`DE_603`	400	Operation not allowed on SELF dependant
`DE_604`	400	No fields provided to update
`DE_605`	400	Validation error

Overview

Architecture

Decisions

Modules

Dependant Module

Overview

Immutability Model

Auth Guards by Endpoint

SELF Dependant

Exact-Duplicate Skip on Create

Relationship Values

Salutation Values

Endpoints

POST /users/{user_id}/dependants

POST /users/{user_id}/dependants/bulk

GET /users/{user_id}/dependants

GET /users/{user_id}/dependants/{id}

PATCH /users/{user_id}/dependants/{id}

DELETE /users/{user_id}/dependants/{id}

Request / Response Examples

Error Codes

​Overview

​Immutability Model

​Auth Guards by Endpoint

​SELF Dependant

​Exact-Duplicate Skip on Create

​Relationship Values

​Salutation Values

​Endpoints

POST /users/{user_id}/dependants

POST /users/{user_id}/dependants/bulk

GET /users/{user_id}/dependants

GET /users/{user_id}/dependants/{id}

PATCH /users/{user_id}/dependants/{id}

DELETE /users/{user_id}/dependants/{id}

​Request / Response Examples

​Error Codes

Overview

Immutability Model

Auth Guards by Endpoint

SELF Dependant

Exact-Duplicate Skip on Create

Relationship Values

Salutation Values

Endpoints

Request / Response Examples

Error Codes