Create Benefit Entity
Self or admin only. Gating on the body’s user_id carries the same
guarantee a path label would: an AppUser may mint one for itself and
nobody else, and an admin may mint one for anyone. Benefit-provider and
platform actors are refused — a benefit instance is the user’s own record,
and those identities create theirs inside the owning transaction rather
than through this endpoint. platform_id is resolved from the token (or an
admin’s x-platform-id), never from the body.
Authorizations
JWT bearer token. App-user tokens are issued by POST /auth/token (the partner backend calls it as its platform service account); admin and dashboard tokens are issued via OIDC login.
Body
A validated 12-digit numeric user identifier.
Every external entry point validates:
- JSON
Deserializeruns [UserId::parse] (outer whitespace trimmed, length and digit-only enforced) via#[serde(try_from = "String")]. - DB
FromSqlruns [UserId::parse] on every row read.
Display / Deref<Target = str> / AsRef<str> / Into<String> are
derived via derive_more — the inner String is pass-through for
every read-only borrow, display, and move-out.
"012345678901"
Response
The created benefit entity
Kind of benefit offered by a provider. Stored as TEXT — deliberately not a PostgreSQL enum, so adding a kind needs no migration.
CONSULTATION, INSURANCE_POLICY, HEALTH_CHECKUP Generic, coarsened lifecycle of a benefit_entity — a benefit-agnostic projection of each benefit's own status (mirrors ExternalMandateStatus -> MandateStatus), so goal/mandate reactions never see insurance/consultation vocabulary. CREATED = just recorded (insurance Pending, consultation Initiated). VERIFICATION = the member has reached the clinic and is being verified (insurance Verification); it is the entitlement's echo of the front desk, not the queue's own status. APPROVED = insurance Approved. ACTIVE = live (insurance Issued/renewal, consultation Active). REJECTED = never went active (insurance Rejected). COMPLETED = went active then ended (insurance Expired/Reissuance, consultation Completed/Closed). FAILED = a technical/operational failure distinct from a rejection (consultation Failed). REJECTED, COMPLETED and FAILED are terminal but drive different reactions.
CREATED, VERIFICATION, APPROVED, ACTIVE, REJECTED, COMPLETED, FAILED A validated 12-digit numeric user identifier.
Every external entry point validates:
- JSON
Deserializeruns [UserId::parse] (outer whitespace trimmed, length and digit-only enforced) via#[serde(try_from = "String")]. - DB
FromSqlruns [UserId::parse] on every row read.
Display / Deref<Target = str> / AsRef<str> / Into<String> are
derived via derive_more — the inner String is pass-through for
every read-only borrow, display, and move-out.
"012345678901"