API reference
The HTTP surface behind Beacon Claims. Two upstream lookups (provider identity, procedure codes) hit real public government data; enrollment, eligibility, rates, claims, and remittance are simulated, since real claims data is PHI with no public equivalent to point at.
What's real vs. simulated
Real, public, no-auth data
- CMS NPPES NPI Registry resolves a real provider's identity by name/state.
- NIH/NLM Clinical Table Search validates real HCPCS Level II procedure codes.
Simulated, deliberately
- Member, eligibility, contract rate, claim, and remittance data.
- Swap this mock's base URL for a real claims API and nothing else changes.
Endpoints
| Method | Path | What it does | UI page |
|---|---|---|---|
| POST | /members | Create a test member, seeded with active coverage, a copay, and remaining deductible | /members/new |
| GET | /eligibility/{memberId} | Coverage status, copay, deductible remaining | /eligibility/{memberId}/view |
| GET | /contracts/{providerNpi}?procedureCode= | Contracted rate for one procedure | /contracts/lookup |
| POST | /claims | Submit a multi-line claim; runs the full adjudication waterfall | /claims/new |
| POST | /claims/{claimId}/documents | Attach a supporting document to an adjudicated claim | /claims/{claimId}/view |
| GET | /claims/{claimId} | Adjudication result: allowed, deductible applied, copay applied, payment | /claims/{claimId}/view |
| GET | /remittance/{claimId} | Final remittance payment | /remittance/{claimId}/view |
Quickstart
# 1. create a member
curl -s -X POST $API/members -H 'Content-Type: application/json' \
-d '{"firstName":"Jane","lastName":"Doe","dob":"1990-05-14","planCode":"PPO-GOLD"}'
# 2. check eligibility (use the memberId from step 1)
curl -s $API/eligibility/M-1001
# 3. submit a two-line claim
curl -s -X POST $API/claims -H 'Content-Type: application/json' \
-d '{"memberId":"M-1001","providerNpi":"1881018208",
"lines":[{"procedureCode":"G0438","units":1},{"procedureCode":"G0439","units":1}]}'
# 4. read back the remittance (use the claimId from step 3)
curl -s $API/remittance/CLM-1