Immutable rows — dependant fields are never updated in place. Every change produces a new row with status = active; the old row is set to status = discarded. Use previous_version_id to walk the 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

                 previous_version_id
┌─────────────┐ ◄──────────────────── ┌─────────────┐
│ id: uuid-A  │                        │ id: uuid-B  │
│ status: discarded │               │ status: active  │
│ first_name: Ravi  │               │ first_name: Ravi K │
└─────────────┘                        └─────────────┘
     v1                                     v2 (current)
When you PATCH /dependants/{id}, the server:
  1. Sets the old row’s status → discarded
  2. Inserts a new row with a new UUID and previous_version_id = old_id
  3. Returns the new (current) row
To query only current rows, filter status = active (the default).

​
SELF dependant

Every user has exactly one active relationship = self dependant at any time. It is automatically created on POST /users/{user_id}/complete_onboarding and re-versioned when PATCH /users/{user_id} changes first_name, last_name, dob, or gender. The SELF row cannot be created, updated, or deleted via the dependants API. Attempting to do so returns 400 SelfDependantNotAllowed.

​
Auth Guards by Endpoint

EndpointJWT userAdmin keyNotes
POST /dependants✓ (own dependants only)✓primary_user_id must match JWT
GET /dependants✓ (own dependants only)✓Admin can filter any user
GET /dependants/{id}✓ (own dependants only)✓403 if accessing another user’s
PATCH /dependants/{id}✓ (own dependants only)✓
DELETE /dependants/{id}✓ (own dependants only)✓Sets status → discarded

​
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

​
Endpoints

POST /dependants

Add a new dependant for a user. relationship = self is not allowed.

GET /dependants

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

GET /dependants/{id}

Fetch a single dependant by UUID.

PATCH /dependants/{id}

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

DELETE /dependants/{id}

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

​
Request / Response Examples

curl -X POST http://localhost:8080/dependants \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "primary_user_id": "usr_7Hq4nMdKpRsXwYzA1b",
    "relationship": "spouse",
    "first_name": "Priya",
    "last_name": "Kumar",
    "date_of_birth": "1992-08-20",
    "gender": "female"
  }'

curl -X PATCH http://localhost:8080/dependants/01926b3a-7c2e-7d4f-a1b2-c3d4e5f60001 \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{
    "last_name": "Sharma"
  }'

curl http://localhost:8080/dependants \
  -H 'Authorization: Bearer eyJhbGci...'

​
Version history

To retrieve the full history of a dependant (all past versions), list with status = discarded and filter by primary_user_id, then follow previous_version_id links. Each active row is the current head of its version chain.