# eobs.claims: the Explanation of Benefits, as typed data > The Explanation of Benefits is the statement a health plan sends after it processes a claim: billed, allowed, plan paid, patient responsibility and remark codes. A free typed schema, remark-code decoding and an MCP server for agents. Source: https://eobs.claims/ ยท Updated 2026-10-09 ## The statement that explains the claim. After a plan processes a claim, it reports the outcome line by line: billed, allowed, plan paid and what the member may owe. The first thing an EOB says about itself is what it is not: **this is not a bill**. Any actual bill comes from the provider, and the EOB is the document to check it against. The plan's **allowed** amount is the negotiated rate, the contract number rather than the sticker number, and the gap between billed and allowed is the first thing worth reading on every line. The provider receives the same outcome in machine form as an electronic remittance advice, the X12 835. Member EOB and provider 835 describe one processing outcome, which is what makes the EOB parseable in the first place: under the letterhead it is already structured data. Every reduction or non-payment carries a remark code from the industry code sets (CARC and RARC): CO-45 for a charge over the fee schedule, CO-97 for a service bundled into another. When the plan does not cover a line, the member can appeal; most plans must allow at least 180 days from the notice of the decision for an internal appeal, and the plan's own notice states the deadline. A register note, stated plainly: the EOB is a health coverage document, not property and casualty. This family serves both registers with one design system: P&C claim documents like the [loss run](https://lossruns.claims) and the [loss notice](https://acords.co), and health revenue-cycle documents like the EOB. Same typed-schema discipline, different vocabulary, never blurred. - **Not a bill:** The provider sends the bill. The EOB is how you check it. - **Who gets it:** The member gets the EOB. The provider gets it as an X12 835. - **Remark codes:** A standard code on every reduction, explaining why. - **Appeal window:** At least 180 days for most plans, from the decision notice. - **Register:** A health document, not P&C, typed like the loss run. ## One statement, fourteen typed fields. The shape an EOB resolves to, from a member PDF or an 835. Free, with no key. | Field | Type | Meaning | Source | |---|---|---|---| | `payer` | string | The health plan that processed the claim. | Plan | | `member_id` | string | The member it was processed for. | Plan | | `claim_number` | string | The plan's claim ID. Appeals cite it. | Plan | | `provider` | string | Who rendered and billed the services. | Provider bill | | `date_processed` | date | When the plan finished processing. | Plan | | `lines[].date_of_service` | date | When the service was rendered. | Provider bill | | `lines[].procedure_code` | string | CPT or HCPCS code. | Provider bill | | `lines[].billed` | money | What the provider charged. | Provider bill | | `lines[].allowed` | money | The plan's contracted rate, not the sticker price. | Plan | | `lines[].plan_paid` | money | What the plan paid on the line. | Plan | | `lines[].patient_responsibility` | money | Copay, coinsurance or deductible the member may owe. | Plan | | `lines[].remark_codes` | string[] | CARC and RARC codes for every reduction. | Plan | | `totals` | object | Sums across the lines. | Derived | | `appeal_window` | object | The appeal deadline, when the EOB states it. | Plan | ### JSON Schema (https://eobs.claims/schema.json) ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://eobs.claims/schema.json", "title": "Eob", "type": "object", "description": "An Explanation of Benefits: the statement a health plan sends a member after it processes a claim. Not a bill; any bill comes from the provider.", "required": [ "payer", "member_id", "claim_number", "provider", "date_processed", "lines", "totals" ], "properties": { "payer": { "type": "string", "description": "The health plan that processed the claim." }, "member_id": { "type": "string" }, "claim_number": { "type": "string", "description": "The plan's claim identifier. Appeals reference it." }, "provider": { "type": "string", "description": "Who rendered and billed the services." }, "date_processed": { "type": "string", "format": "date", "description": "When the plan finished processing the claim." }, "lines": { "type": "array", "items": { "$ref": "#/$defs/EobServiceLine" } }, "totals": { "$ref": "#/$defs/EobTotals" }, "appeal_window": { "$ref": "#/$defs/EobAppealWindow" } }, "$defs": { "Eob": { "type": "object", "description": "An Explanation of Benefits: the statement a health plan sends a member after it processes a claim. Not a bill; any bill comes from the provider.", "required": [ "payer", "member_id", "claim_number", "provider", "date_processed", "lines", "totals" ], "properties": { "payer": { "type": "string", "description": "The health plan that processed the claim." }, "member_id": { "type": "string" }, "claim_number": { "type": "string", "description": "The plan's claim identifier. Appeals reference it." }, "provider": { "type": "string", "description": "Who rendered and billed the services." }, "date_processed": { "type": "string", "format": "date", "description": "When the plan finished processing the claim." }, "lines": { "type": "array", "items": { "$ref": "#/$defs/EobServiceLine" } }, "totals": { "$ref": "#/$defs/EobTotals" }, "appeal_window": { "$ref": "#/$defs/EobAppealWindow" } } }, "EobServiceLine": { "type": "object", "required": [ "date_of_service", "procedure_code", "billed", "allowed", "plan_paid", "patient_responsibility" ], "properties": { "date_of_service": { "type": "string", "format": "date" }, "procedure_code": { "type": "string", "description": "CPT or HCPCS code for the service line." }, "description": { "type": "string", "description": "Plain-language service description." }, "billed": { "type": "number", "minimum": 0, "description": "USD the provider charged." }, "allowed": { "type": "number", "minimum": 0, "description": "The plan's negotiated rate: the contract number, not the sticker number." }, "plan_paid": { "type": "number", "minimum": 0, "description": "USD the plan paid the provider on this line." }, "patient_responsibility": { "type": "number", "minimum": 0, "description": "Copay, coinsurance or deductible: what the member may owe the provider. The EOB itself is not a bill." }, "remark_codes": { "type": "array", "items": { "type": "string" }, "description": "CARC/RARC codes explaining any reduction or non-payment, e.g. CO-45, CO-97, PR-1." } } }, "EobTotals": { "type": "object", "required": [ "billed", "allowed", "plan_paid", "patient_responsibility" ], "properties": { "billed": { "type": "number" }, "allowed": { "type": "number" }, "plan_paid": { "type": "number" }, "patient_responsibility": { "type": "number" } } }, "EobAppealWindow": { "type": "object", "description": "The plan's appeal deadline and address, when stated on the document.", "properties": { "deadline": { "type": "string", "format": "date" }, "days": { "type": "integer", "description": "Days allowed for an internal appeal, counted from the notice of the decision; at least 180 for most plans." }, "address": { "type": "string" } } } } } ``` ### Example (https://eobs.claims/example.json) ```json { "payer": "Cascade Health Plan", "member_id": "CHP-88214307", "claim_number": "2026-183350021", "provider": "Lakeview Family Medicine", "date_processed": "2026-06-24", "lines": [ { "date_of_service": "2026-06-02", "procedure_code": "99214", "description": "Office visit", "billed": 240, "allowed": 132.4, "plan_paid": 107.4, "patient_responsibility": 25, "remark_codes": [ "CO-45", "PR-3" ] }, { "date_of_service": "2026-06-02", "procedure_code": "80053", "description": "Metabolic panel", "billed": 88, "allowed": 21.6, "plan_paid": 21.6, "patient_responsibility": 0, "remark_codes": [ "CO-45" ] }, { "date_of_service": "2026-06-02", "procedure_code": "36415", "description": "Blood draw", "billed": 24, "allowed": 0, "plan_paid": 0, "patient_responsibility": 0, "remark_codes": [ "CO-97" ] } ], "totals": { "billed": 352, "allowed": 154, "plan_paid": 129, "patient_responsibility": 25 }, "appeal_window": { "days": 180 } } ``` ## What your agent does with it - **parse** (Read the statement): A PDF or 835 remittance in, typed service lines out. Call: `POST /parse`, with an access key. - **reconcile** (Check the bill): The provider's bill against what the EOB says is owed. Call: `reconcile_eob_bill`. - **explain** (Decode remark codes): CO-45, PR-3 and the rest, in plain words a member can use. Call: `explain_remark_code`. - **draft** (Draft the appeal): A letter for a line the plan didn't cover, for a person to send. Call: `draft_eob_appeal`. ## MCP server Endpoint: https://eobs.claims/mcp (Streamable HTTP, JSON-RPC over POST; keyless and read-only; nothing is stored). ```json { "mcpServers": { "eobs.claims": { "url": "https://eobs.claims/mcp" } } } ``` ### `get_eob_schema` The JSON Schema (2020-12) for the Explanation of Benefits: every field, its type and what it means. Also served at https://eobs.claims/schema.json. Input: ```json {"type":"object","properties":{}} ``` ### `get_eob_example` A complete, valid example Eob record with fictional values. Also served at https://eobs.claims/example.json. Input: ```json {"type":"object","properties":{}} ``` ### `explain_eob_field` What one field of the Explanation of Benefits means, its type, and where the value comes from. Accepts paths like totals. Input: ```json {"type":"object","required":["field"],"properties":{"field":{"type":"string","description":"A field name or path."}}} ``` ### `validate_eob` Check a Eob record against the schema, then run the document's own checks (sums, dates). Returns valid (the shape matches), consistent (every check passes too), errors (schema) and warnings (checks). Nothing is stored. Input: ```json {"type":"object","required":["record"],"properties":{"record":{"type":"object","description":"The Eob record to check."}}} ``` ### `explain_remark_code` Decode a Claim Adjustment Reason Code (e.g. CO-45, PR-1, 97) into plain language: what the group code means for the member and what the reason code says. Input: ```json {"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"e.g. CO-45, PR-1, OA-23 or a bare reason code such as 97."}}} ``` ### `reconcile_eob_bill` Compare a provider's bill with the EOB, line by line: what the member may owe on each line (patient responsibility) against what was billed, flagging anything above it and any bill line with no matching EOB line. It compares numbers; it is not billing advice. Input: ```json {"type":"object","required":["eob","bill"],"properties":{"eob":{"type":"object","description":"An Eob record (see get_eob_schema)."},"bill":{"type":"array","items":{"type":"object","required":["procedure_code","amount_due"],"properties":{"procedure_code":{"type":"string"},"date_of_service":{"type":"string","format":"date"},"amount_due":{"type":"number"}}}}}} ``` ### `draft_eob_appeal` Draft an internal appeal letter for one service line of an EOB, for the member or their representative to review and send. It states the line, its remark codes in plain language and the member's reason. Nothing is sent. Input: ```json {"type":"object","required":["eob","line","member_name","reason"],"properties":{"eob":{"type":"object","description":"An Eob record."},"line":{"type":"integer","minimum":0,"description":"Index of the service line in eob.lines."},"member_name":{"type":"string"},"reason":{"type":"string","description":"Why the member believes the line should be covered, in their words."}}} ``` ## HTTP - `GET https://eobs.claims/schema.json`: the JSON Schema - `GET https://eobs.claims/example.json`: the example record - `POST https://eobs.claims/validate`: send a Eob as JSON; returns `{ valid, consistent, errors, warnings }` - `POST https://eobs.claims/parse`: a document in, a Eob out; requires an access key (`Authorization: Bearer `). Request one at https://eobs.claims/#access. - `GET https://eobs.claims/openapi.json`: OpenAPI 3.1 for all of the above ## Questions ### Is an EOB a bill? No. It is the plan's statement after it processes a claim. Any bill comes from the provider; the EOB is what you check it against. ### What is the allowed amount? The plan's contracted rate for the service. Plan paid plus the member's share normally adds up to it. ### What do codes like CO-45 mean? CO is a contractual write-off the member doesn't owe; PR is the member's share. CO-45 is a charge above the fee schedule, CO-97 a bundled service, PR-3 a copay. ### How long do I have to appeal? At least 180 days for most plans, from the notice of the decision. The plan's own notice states the deadline that applies. ## Family - https://api.insure: the insurance industry as one agent-first API - https://gigs.claims: flat-fee claim files for licensed adjusters - https://lossruns.claims: the loss run as typed data - https://acords.co: loss-notice data fields as a typed model Nothing on this site is medical, legal or billing advice. The plan processes and decides claims.