Survivors API

Survivor endpoints manage the people who can access your will. All endpoints require authentication.

Base: /api/survivors

GET /api/survivors

List all Survivors for the authenticated Host.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "survivors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Jane Doe",
      "relationship": "spouse",
      "contact_methods": [
        { "type": "email", "value": "jane@example.com" },
        { "type": "sms", "value": "+1234567890" }
      ],
      "connector_priority": ["email", "sms", "whatsapp", "telegram"],
      "has_personal_message": true,
      "backup_codes_remaining": 5,
      "created_at": "2026-02-21T10:00:00Z"
    }
  ],
  "count": 1,
  "threshold": 3
}

Response Fields

Field	Type	Description
id	uuid	Unique identifier
name	string	Survivor's name
relationship	string	Relationship to host
contact_methods	array	Contact options
connector_priority	array	OTP delivery order
has_personal_message	boolean	Whether message exists
backup_codes_remaining	integer	Unused backup codes
created_at	timestamp	When added
count	integer	Total survivors
threshold	integer	Minimum to access

---

POST /api/survivors

Add a new Survivor.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request

{
  "name": "Jane Doe",
  "relationship": "spouse",
  "contact_methods": [
    { "type": "email", "value": "jane@example.com" },
    { "type": "sms", "value": "+1234567890" }
  ],
  "connector_priority": ["email", "sms"],
  "personal_message": "Dear Jane, if you're reading this..."
}

Contact Method Types

Type	Value Format
email	email@example.com
sms	+1234567890 (E.164)
whatsapp	+1234567890
telegram	@username

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Jane Doe",
  "relationship": "spouse",
  "backup_codes": ["A3F7-K9M2", "B5H2-L4N8", "C7J3-M6P1", "D9K5-N8R3", "E1L7-P2S5"],
  "message": "Please print these backup codes and give them to Jane in a sealed envelope."
}

⚠️ Important: Backup codes are returned only on creation. Write them down immediately.

Errors

• 400 — Validation error (invalid phone format, missing required fields)
• 409 — Survivor limit reached (max 10)

---

PUT /api/survivors/:id

Update Survivor details.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request

Partial update:

{
  "name": "Jane Smith",
  "connector_priority": ["sms", "email"]
}

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Jane Smith",
  "relationship": "spouse",
  "contact_methods": [
    { "type": "email", "value": "jane@example.com" },
    { "type": "sms", "value": "+1234567890" }
  ],
  "connector_priority": ["sms", "email"],
  "has_personal_message": true,
  "backup_codes_remaining": 5,
  "created_at": "2026-02-21T10:00:00Z"
}

⚠️ Note: If will is active, updating contact methods triggers SSS share re-encryption.

---

DELETE /api/survivors/:id

Remove a Survivor.

Headers

Authorization: Bearer <access_token>

Response (204 No Content)

No body returned.

Errors

• 409 — Removing would drop below threshold

---

PUT /api/survivors/minimum-count

Update the threshold (K) for SSS.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request

{
  "threshold": 2
}

Response (200 OK)

{
  "threshold": 2,
  "survivor_count": 3,
  "message": "Will must be re-encrypted to apply new threshold."
}

Errors

• 400 — Threshold < 2 or > survivor count

---

POST /api/survivors/:id/regenerate-codes

Regenerate backup codes for a Survivor.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "backup_codes": ["F2M8-Q4T6", "G4N1-R6V8", "H6P3-S8W1", "J8Q5-T1X3", "K1R7-V3Y5"]
}

⚠️ Warning: Regenerating codes invalidates all previous codes.

---

Rate Limits

Endpoint	Limit	Window
GET /survivors	100 requests	1 minute
POST /survivors	10 requests	1 hour
PUT /survivors/:id	20 requests	1 hour
DELETE /survivors/:id	10 requests	1 hour
POST /survivors/:id/regenerate-codes	5 requests	1 hour

---

Example: Add Survivor

curl -X POST "https://api.example.com/api/survivors" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "relationship": "spouse",
    "contact_methods": [
      {"type": "email", "value": "jane@example.com"},
      {"type": "sms", "value": "+1234567890"}
    ],
    "connector_priority": ["email", "sms"],
    "personal_message": "Dear Jane, I love you..."
  }'

Example: Update Threshold

curl -X PUT "https://api.example.com/api/survivors/minimum-count" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"threshold": 2}'

Example: Regenerate Backup Codes

curl -X POST "https://api.example.com/api/survivors/550e8400-e29b-41d4-a716-446655440001/regenerate-codes" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

---

Related Endpoints

• Will API — Will management
• Authentication — Login