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 /dependants/{id}, the server:
  1. Sets the old row status → discarded
  2. Inserts a new row with a fresh UUID and previous_version_id = old_id
  3. Returns the new (current) row

​
Auth Guards by Endpoint

EndpointJWT userAdmin keyNotes
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✓Defaults to status = active
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 also accepts an optional 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

ValueDescription
selfThe user themselves (system-managed)
spouseHusband or wife
motherMother
fatherFather
childSon or daughter
father_in_lawFather-in-law
mother_in_lawMother-in-law
siblingBrother or sister

​
Salutation Values

An optional salutation field is available on create, update, and response objects:
ValueDescription
mrMr
mrsMrs
msMs
masterMaster (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"
  }'

​
Error Codes

CodeHTTPDescription
DE-600500Internal server error
DE-601404Dependant not found
DE-602403JWT user accessing another user’s dependant
DE-603400Operation not allowed on SELF dependant
DE-604400No fields provided to update
DE-605400Validation error