Salvos Health Insurance API Docs

Authentication

All platform-facing endpoints require an X-API-Key header. Your API key is returned on registration and starts with pk_live_. Admin endpoints use Backend admin JWT (Authorization: Bearer <token>).

X-API-Key: pk_live_your32charkey

Pricing Model

Each event uses either fixed or percentage pricing — never both.
Fixed: A flat amount charged regardless of attendance or revenue.
Percentage: A % of total event revenue, capped at percentage_cap to prevent runaway costs. Formula: min(total_revenue × rate, percentage_cap)

Public Endpoints

GET /api/health

Returns the health status of the API server. Use this to verify the service is reachable. Response 200:

{
  "message": "API is healthy",
  "code": 200
}

POST /api/v1/platforms/register

{
  "name": "Acme Events",
  "email": "billing@acme.com",
  "password": "securepassword",
  "passwordConfirm": "securepassword",
  "phone": "+1234567890"
}

Response 200:

{
  "id": "abc123",
  "name": "Acme Events",
  "email": "billing@acme.com",
  "api_key": "pk_live_a1b2c3d4...",
  "status": "active"
}

Platform Endpoints

POST /api/v1/events X-API-Key

Create a new event. Pricing is set upfront and cannot be both fixed and percentage.

{
  "name": "Tech Summit 2026",
  "description": "Annual technology conference",
  "start_date": "2026-06-01 09:00:00",
  "end_date": "2026-06-01 18:00:00",
  "pricing_type": "percentage",
  "pricing_value": 5,
  "percentage_cap": 2000,
  "ticket_price": 100,
  "expected_attendees": 300
}

Field	Required	Notes
`pricing_type`	Yes	`fixed` or `percentage`
`pricing_value`	Yes	Naira amount (fixed) or rate % (percentage)
`percentage_cap`	If percentage	Max charge ceiling in Naira
`ticket_price`	No	Stored for reference

GET /api/v1/events X-API-Key

Returns a paginated list of events belonging to the authenticated platform, ordered newest first.

Query param	Default	Notes
`page`	1	Page number (1-based)
`per_page`	20	Items per page (max 100)

Response 200:

{
  "page": 1,
  "per_page": 20,
  "total": 42,
  "total_pages": 3,
  "items": [
    {
      "id": "evt_abc",
      "name": "Tech Summit 2026",
      "status": "upcoming",
      "pricing_type": "percentage",
      "pricing_value": 5,
      "percentage_cap": 2000,
      "start_date": "2026-06-01 09:00:00",
      "end_date": "2026-06-01 18:00:00",
      "created": "2026-04-10 12:00:00"
    }
  ]
}

GET /api/v1/events/:id X-API-Key

Retrieve event details. Only accessible by the platform that created it.

POST /api/v1/events/:id/finalize X-API-Key

Submit final attendance and revenue after event ends. Event must have status completed.

{
  "final_attendance": 245,
  "total_revenue": 24500
}

Response 200:

{
  "invoice_id": "inv_abc",
  "final_attendance": 245,
  "total_revenue": 24500,
  "amount_charged": 1225,
  "status": "pending"
}

POST /api/v1/events/:id/cancel X-API-Key

Notify that an event has been cancelled. Any pending invoice is also cancelled. No charge applies.

// No request body required

Admin Endpoints

POST /api/v1/admin/invoices/:id/pdf Admin JWT

Generates (or regenerates) the HTML invoice file. Does not send an email. Use the download endpoint to view/print.

GET /api/v1/admin/invoices/:id/download Admin JWT

Serves the generated HTML invoice. Open in browser and use Print → Save as PDF.

POST /api/v1/admin/invoices/:id/send Admin JWT

Resends the invoice email to the platform's registered email. Requires HTML to be generated first.

Event Lifecycle

Platform creates event → status: "upcoming"
         ↓
 end_date passes (auto, every minute)
         ↓
 status: "completed" + invoice created (status: "pending")
         ↓
 Platform sends POST /events/:id/finalize
   → amount_charged calculated
         ↓
 Admin approves invoice in Backend UI
   → status: "approved" → HTML generated → email sent
         ↓
 status: "sent"