Auth guard: admin-api-key header required for all endpoints. No JWT/user access.

​
Overview

A benefit provider is a company or entity (e.g. a diagnostic chain, an insurance company, a telemedicine platform) that offers one or more benefits to Aarokya users. Providers are the top-level grouping in the benefit catalogue — every Benefit row has a provider_id foreign key referencing a BenefitProvider. Providers are managed exclusively by system admins. There is no partner or user path.

​
Key Rules

  • Name uniqueness is global. No two active providers may share the same name.
  • Soft delete is guarded. A provider with associated benefits (active or inactive) cannot be deleted. Remove all benefits first via DELETE /benefits/{benefit_id}.
  • Update is name-only. Only name can be changed. Passing null for name is a no-op (returns the current provider unchanged).

​
Endpoints

POST /benefit_providers

Create a new benefit provider. Name must be unique across all active providers.

GET /benefit_providers

Paginated list of benefit providers. Supports filtering by status, start_time, end_time.

GET /benefit_providers/{benefit_provider_id}

Fetch a single provider by UUID.

PATCH /benefit_providers/{benefit_provider_id}

Rename a provider. The new name must not conflict with any other active provider.

DELETE /benefit_providers/{benefit_provider_id}

Soft-delete a provider (sets status = inactive). Fails if the provider has any benefits.

​
Request / Response Examples

curl -X POST http://localhost:8080/benefit_providers \
  -H 'admin-api-key: your-admin-key' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Apollo Diagnostics" }'

curl -X DELETE http://localhost:8080/benefit_providers/018f4c2a-1b3e-7d8f-9a0b-2c3d4e5f6a7b \
  -H 'admin-api-key: your-admin-key'

​
Error Codes

CodeHTTPDescription
BPE_400500Internal server error
BPE_401404Provider not found
BPE_402409Name already exists
BPE_403409Provider has associated benefits
BPE_404400Validation error (e.g. empty name)