Plansight's outbound REST API. Where the other integrations on this site are inbound — Plansight reading from external systems — the Open API is the inverse: partner systems calling into Plansight for read access to employer and plan data.
Token-authenticated REST API that lets brokers' downstream systems (carriers, BI tools, broker-built dashboards) query employer and plan data programmatically. Read-only today; brokerage-isolated; throttled.
/v1/)throttle:100)Tokens generated in Plansight UI under Settings → Brokerage Info → API Keys. Token is a composite of brokerageId + apiToken — looking up by token also identifies the brokerage in one query.
Every query filters by the authenticated user's brokerageId. No way to see another brokerage's data even with a valid token. Cross-brokerage data leakage is not possible by design.
The employer list endpoint queries Elasticsearch (not raw DB) so partners can search by name, tax ID, or partial match without needing exact identifiers.
Five data endpoints plus a healthcheck. All under /v1/.
id, taxId, name, page, perPage. Default 10/page; max 100.The API is currently read-only — no POST / PUT / DELETE endpoints. Partners can pull data into their systems, but writes to Plansight remain through the UI and the inbound integrations (BenefitPoint, Employee Navigator). Adding write support is feasible but hasn't been needed by current partners.
| Setting | Value / Source |
|---|---|
| Auth scheme | Bearer token in Authorization: Bearer {token} header |
| Token format | Composite of brokerageId + apiToken from the ApiToken table |
| Token storage | app/Models/ApiToken.php — DynamoDB composite keys, indexes on id and carrierId |
| Token issuance | Plansight UI: Settings → Brokerage Info → API Keys |
| Rate limit | Laravel throttle:100 middleware (100 requests/minute per token) |
| Versioning | URL prefix /v1/. No deprecation policy formalized yet. |
| OpenAPI spec | swagger-api.json at repo root — manually maintained, not auto-generated |
| File | Purpose |
|---|---|
routes/api.php:15–23 | 6 API routes — healthcheck + 5 data endpoints |
app/Http/Controllers/ApiController.php:42–85 | Pagination validator — extracts page/perPage with defaults |
app/Http/Controllers/ApiController.php:87–192 | employerList() — Elasticsearch query builder, search filters, result mapping |
app/Http/Controllers/ApiController.php:194–240+ | employerPlanTypes() and employerPlans() handlers |
app/Models/ApiToken.php:10–14 | Token model — composite key (brokerageId + apiToken), DynamoDB indexes |
app/Models/Group.php | apiAttributes + apiModel() method for API response mapping |
swagger-api.json | OpenAPI 3.0 spec — describes every route, params, response schema |
app/Http/Controllers/RestController.php | Generic REST CRUD base — used for internal admin APIs, not the public Open API |
Token is not a simple UUID but a concatenation of brokerageId + apiToken. Looking up a token also identifies the brokerage in one DynamoDB query. Slightly unusual but efficient.
The employer list endpoint queries Elasticsearch rather than the primary database — supports flexible name/taxId matching and faceted filtering. Trade-off: ES needs to stay in sync with employer data.
The swagger-api.json is hand-maintained, not generated from code. Keeps full control over what's exposed but creates a sync risk — endpoints can drift from spec if maintenance lapses.
/v1/swagger/{planType} dynamically returns field metadata for the given plan type. Partners consume it programmatically rather than hardcoding the field list. Resilient to plan-type schema changes.
Strategic questions and edge cases more than code-level bugs. The API works in production; these are areas worth a product / platform decision when partners start putting more load on it.
app/Http/Controllers/Rest/App/ApiTokenController.php at line 34 (the create() method) calls auth()->user() and proceeds to mint a token without checking the user's role beyond the broker/carrier branch on lines 47-55. Today, any broker-side user with a Plansight session can POST /rest/app/apiToken and receive a working API token scoped to their entire brokerage. There's no "Brokerage Admin" role check. The intended behavior is that only Plansight admins (or at minimum brokerage admins) should be able to create tokens for their org. Worth adding a role guard at the top of create() + delete().
API is at /v1/ but no formal policy for sunsetting endpoints, breaking changes, or v2 migration. Partners may build assumptions that constrain future changes. Worth defining a versioning + deprecation policy.
Partners can pull but not push. Limits use cases (e.g., a partner can't sync changes back to Plansight via API). Adding write support is feasible if a partner has a real need.
All data fetches are polling. High-volume partners will hit rate limits or incur latency keeping data current. A webhook surface for "employer updated" / "plan changed" events would scale better.
Manual spec maintenance creates drift risk. Worth considering: generate the spec from route annotations, OR make the spec the source of truth with code generation. Either reduces ongoing reconciliation.
Tokens are issued, but no per-token usage tracking, no analytics dashboard, no billing model. As partner adoption grows this becomes increasingly important — both for capacity planning and for any future tiered access.
Spec covers 200 / 401 / 422 but not 5xx specifics or domain errors. Partners building robust integrations need richer error documentation.