{ "openapi": "3.1.0", "info": { "title": "MedBillAnalyzer", "version": "1.0.0", "summary": "Check a medical bill against the insurer\u2019s Explanation of Benefits.", "description": "MedBillAnalyzer reconciles a medical bill against the Explanation of Benefits the patient\u2019s plan issued for the same care, line by line, and reports where the two disagree.\n\nTwo things are worth knowing before you call it.\n\n**The comparison is not done by a model.** A reader transcribes what is printed on the documents; fixed, deterministic rules decide what it means. The same documents always produce the same findings, and every finding names the rule that produced it.\n\n**Never add the findings together.** `amount_in_question_cents` is already the de-duplicated total. Two findings routinely describe the same dollars from different angles \u2014 a line billed above the contracted rate is usually also part of a bill that asks for more than the plan says is owed \u2014 so summing them overstates the problem, in a letter the patient signs and sends.\n\n**A clean result is not always an all-clear.** `how_completely_we_checked` is `partial` when the comparison could not be finished \u2014 no Explanation of Benefits, or fields the reader could not make out. A `partial` scan that found nothing means nobody looked, not that the bill is right, and telling the patient otherwise is how they end up paying a bill they could have disputed. When `you_can` is present, use it as written.\n\n**The first call after an idle period can take up to a minute.** The service sleeps when nothing is using it and wakes on the first request. Set a generous timeout and retry once on a timeout rather than reporting a failure to the patient.\n\n**There is no API key.** A case is reached by its id, which is 128 random bits and is issued only to whoever created it; treat it as a credential and do not log it. Deleting needs a second credential, below.\n\n**Keep `delete_token`.** It comes back once, at creation, and only its digest is stored \u2014 it cannot be looked up or resent. Without it the case can only be waited out or removed by support.\n\nThis is not legal, medical, or financial advice. This report compares documents you supplied and helps you ask questions about them.", "contact": { "email": "support@medbillanalyzer.com", "url": "https://medbillanalyzer.com" } }, "servers": [ { "url": "https://app.medbillanalyzer.com" } ], "paths": { "/v1/cases": { "post": { "operationId": "check_medical_bill", "summary": "Check a medical bill against its Explanation of Benefits", "description": "Compare a medical bill against the Explanation of Benefits the patient\u2019s insurer issued for the same care, and report where the two disagree. Use when someone shares a medical bill, hospital statement, doctor bill, lab bill or EOB and asks whether it is correct, what they actually owe, or how to dispute it. The bill is required; the EOB is strongly recommended and is what makes most of the checks possible. Free: returns a summary and the title of every finding, but not the detail behind them.", "responses": { "200": { "description": "The case summary, and the findings once unlocked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string" }, "documents": { "type": "string", "description": "Which documents the check ran against." }, "findings": { "description": "The number of findings until the case is unlocked; the findings themselves \u2014 an array of Finding \u2014 once it is. The free tier deliberately carries the count and not the detail.", "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } ] }, "what_we_found": { "type": "array", "description": "The free preview: one entry per finding, carrying only what it is about. Present while the case is locked, and absent once it is unlocked \u2014 at that point `findings` holds the same list with the detail attached. Show these titles to the patient before offering the unlock; they are what makes the offer legible. They are **not** a probability that the bill is wrong: use `tier` for that, and see its description.", "items": { "$ref": "#/components/schemas/FindingPreview" } }, "discrepancies": { "type": "integer" }, "worth_asking_about": { "type": "integer" }, "flagged_without_an_amount": { "type": "integer" }, "amount_in_question": { "type": "string", "description": "Formatted, e.g. \"$657.20\"." }, "amount_in_question_cents": { "type": "integer", "description": "The same figure in cents. **Do not add this to anything.** It is already de-duplicated: two findings routinely describe the same dollars at different altitudes, so the total is the larger of the document-level and per-line views, never the sum of the findings." }, "entitled": { "type": "boolean", "description": "Whether the full findings have been unlocked." }, "fields_we_could_not_read": { "type": "integer" }, "how_completely_we_checked": { "type": "string", "enum": [ "checked", "partial" ], "description": "`partial` means the comparison could not be finished \u2014 no Explanation of Benefits was supplied, or fields could not be read. A `partial` scan that found nothing does **not** mean the bill is correct, and must never be presented to the patient as an all-clear. Use `you_can` verbatim when it is present; it is already worded for this distinction." }, "you_can": { "type": "string", "description": "Present only when nothing was found. The patient-facing sentence for that result, worded to match `how_completely_we_checked`." }, "delete_token": { "type": "string", "description": "Returned **once**, here, and never again \u2014 only its digest is stored. It is required to delete the case, and deleting is deliberately a different capability from reading: a case link can end up in a browser history or a forwarded message. Keep it with the case id, or the case can only be waited out (30 days) or removed by support." }, "disclaimer": { "type": "string" }, "next_step": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "required": [ "bill" ] }, { "required": [ "bill_document" ] } ], "properties": { "bill_document": { "type": "object", "description": "The bill as a file, read for you. Use this when you have the document itself \u2014 a photo, a scan, or a PDF from the provider\u2019s portal.", "anyOf": [ { "required": [ "data_base64" ] }, { "required": [ "url" ] }, { "required": [ "upload_id" ] } ], "properties": { "data_base64": { "type": "string", "description": "The file itself, base64-encoded. PDF, JPEG, PNG or WebP. The media type is read from the bytes rather than taken on trust, so it does not need to be declared \u2014 and a request claiming \"application/pdf\" over a JPEG would otherwise reach the reader as the wrong kind of thing." }, "url": { "type": "string", "format": "uri", "description": "An https link to the file, which this service retrieves. Use it when you have a link rather than the bytes. Must be https and must resolve to a public address: links to private, loopback or link-local addresses are refused, including after a redirect, and so are links carrying credentials. At most 3 redirects, 12 MB, 20 seconds. A link behind a login will not work \u2014 this service sends no cookies and no credentials of any kind \u2014 so for an Explanation of Benefits inside an insurer portal, the patient has to download it and send the bytes." }, "upload_id": { "type": "string", "description": "A slot from `POST /v1/uploads` that the file has already been PUT into. Use this when you can neither attach the bytes nor give a link this service can follow \u2014 above all for an Explanation of Benefits inside an insurer portal, where the patient has to sign in and download it themselves. The id is good for one file and 15 minutes, and the bytes are held in memory only." }, "filename": { "type": "string", "description": "Optional, for your own logs. Not used." } } }, "eob_document": { "type": "object", "description": "The Explanation of Benefits as a file, read for you.", "anyOf": [ { "required": [ "data_base64" ] }, { "required": [ "url" ] }, { "required": [ "upload_id" ] } ], "properties": { "data_base64": { "type": "string", "description": "The file itself, base64-encoded. PDF, JPEG, PNG or WebP. The media type is read from the bytes rather than taken on trust, so it does not need to be declared \u2014 and a request claiming \"application/pdf\" over a JPEG would otherwise reach the reader as the wrong kind of thing." }, "url": { "type": "string", "format": "uri", "description": "An https link to the file, which this service retrieves. Use it when you have a link rather than the bytes. Must be https and must resolve to a public address: links to private, loopback or link-local addresses are refused, including after a redirect, and so are links carrying credentials. At most 3 redirects, 12 MB, 20 seconds. A link behind a login will not work \u2014 this service sends no cookies and no credentials of any kind \u2014 so for an Explanation of Benefits inside an insurer portal, the patient has to download it and send the bytes." }, "upload_id": { "type": "string", "description": "A slot from `POST /v1/uploads` that the file has already been PUT into. Use this when you can neither attach the bytes nor give a link this service can follow \u2014 above all for an Explanation of Benefits inside an insurer portal, where the patient has to sign in and download it themselves. The id is good for one file and 15 minutes, and the bytes are held in memory only." }, "filename": { "type": "string", "description": "Optional, for your own logs. Not used." } } }, "bill": { "type": "object", "additionalProperties": false, "required": [ "lines" ], "properties": { "providerName": { "type": "string", "description": "Who is billing, as printed." }, "facilityName": { "type": "string", "description": "The facility, if different from the provider. Empty string if the same or absent." }, "accountNumber": { "type": "string", "description": "Account or statement number." }, "statementDate": { "type": "string", "description": "The date printed on the statement. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "totalChargedCents": { "type": "string", "description": "The total charges on the statement. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "amountDueCents": { "type": "string", "description": "The balance the patient is being asked to pay now. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "isItemized": { "type": "boolean", "description": "True if the statement lists individual services. False if it shows only a summary or balance forward with no line detail." }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "codeType", "description", "dateOfService", "dateOfServiceEnd", "units", "chargeCents", "patientBalanceCents" ], "properties": { "code": { "type": "string", "description": "The CPT or HCPCS procedure code for this line, if one is printed. Many patient statements print no codes at all \u2014 write an empty string then, rather than inferring a code from the description. An invented code is worse than none." }, "codeType": { "type": "string", "description": "Which code set that code belongs to: 'cpt' for a five-digit CPT, 'hcpcs' for a letter followed by four digits, 'revenue' for a three or four digit hospital revenue code, or an empty string if you cannot tell. Do not guess from the description \u2014 say nothing rather than picking one. This decides which numeric ranges the rules are allowed to read the code against, and a revenue code read as a CPT once put a No Surprises Act claim in a letter about a hospital bed." }, "description": { "type": "string", "description": "The service description exactly as printed on the line." }, "dateOfService": { "type": "string", "description": "The date this service was provided. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "dateOfServiceEnd": { "type": "string", "description": "The end date, only if the line covers a range. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "units": { "type": "string", "description": "Units, quantity or days billed, as printed. Empty string if no such column exists." }, "chargeCents": { "type": "string", "description": "The gross charge for this line, before any insurance adjustment. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "patientBalanceCents": { "type": "string", "description": "The amount the PATIENT is asked to pay for this line, after insurance payment and adjustments. This is a different column from the gross charge and is often much smaller. If the statement shows only one amount per line and does not separate patient responsibility, write an empty string rather than repeating the charge. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." } } }, "description": "One entry per service line. Empty when the statement is not itemized." } }, "description": "The bill already transcribed into structured form. Use this instead of `bill_document` only when you have extracted it yourself; sending the document is both easier and more accurate, because the transcription is then done by a reader tuned for these forms and checked against a field-accuracy harness." }, "eob": { "type": "object", "additionalProperties": false, "required": [ "lines" ], "properties": { "processedDate": { "type": "string", "description": "The date the plan processed or finalised the claim. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "claimNumbers": { "type": "array", "items": { "type": "string" }, "description": "Every claim number the INSURER assigned, exactly as printed on the EOB. These are the ids a representative can look up when the patient calls, so they go on the letter verbatim. A provider-side identifier is NOT a claim number: do not take a visit number, encounter number, account number, guarantor number or statement number from a provider bill, even when the bill and the EOB arrive in the same upload. Empty array if the EOB prints none." }, "networkStatus": { "enum": [ "in", "out", "unknown" ], "description": "Whether the EOB states the provider was in or out of network. Use \"unknown\" unless the document says so explicitly \u2014 this drives which protections apply, and a guess here produces a confidently wrong finding." }, "totalPatientRespCents": { "type": "string", "description": "Total patient responsibility across the claim. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "codeType", "description", "dateOfService", "dateOfServiceEnd", "units", "billedCents", "allowedCents", "planPaidCents", "patientRespCents", "deductibleCents", "copayCents", "coinsuranceCents", "notCoveredCents", "denialCodes", "noteCodes", "claimNumber" ], "properties": { "code": { "type": "string", "description": "The procedure code, if printed. Many insurer EOBs show a \"Type of service\" description instead and carry no codes anywhere \u2014 empty string then." }, "codeType": { "type": "string", "description": "Which code set that code belongs to: 'cpt' for a five-digit CPT, 'hcpcs' for a letter followed by four digits, 'revenue' for a three or four digit hospital revenue code, or an empty string if you cannot tell. Do not guess from the description \u2014 say nothing rather than picking one. This decides which numeric ranges the rules are allowed to read the code against, and a revenue code read as a CPT once put a No Surprises Act claim in a letter about a hospital bed." }, "description": { "type": "string", "description": "Service or type-of-service text as printed." }, "dateOfService": { "type": "string", "description": "The service date for this line. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "dateOfServiceEnd": { "type": "string", "description": "The end date, only if the line covers a range. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "units": { "type": "string", "description": "Units adjudicated, as printed. Empty string if not shown." }, "billedCents": { "type": "string", "description": "What the provider submitted for this line. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "allowedCents": { "type": "string", "description": "The allowed or eligible amount \u2014 the contracted rate. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "planPaidCents": { "type": "string", "description": "What the plan paid. May be labelled plan liability or plan's share. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "patientRespCents": { "type": "string", "description": "What the plan says the patient owes for this line. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "deductibleCents": { "type": "string", "description": "The part applied to the deductible. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "copayCents": { "type": "string", "description": "The copay. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "coinsuranceCents": { "type": "string", "description": "The coinsurance. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "notCoveredCents": { "type": "string", "description": "Any amount shown as not covered or not eligible. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "denialCodes": { "type": "array", "items": { "type": "string" }, "description": "Adjustment or denial reason codes for this line, transcribed exactly, INCLUDING the two-letter group prefix where one is shown \u2014 \"CO-29\", not \"29\". The prefix decides who owes the money and the number alone is ambiguous: CO-96 and PR-96 are the same reason with opposite liability. Empty array when none are printed." }, "noteCodes": { "type": "array", "items": { "type": "string" }, "description": "Any footnote or note codes printed against this line, such as the letters in a \"see notes\" column. These are the plan\u2019s own codes and are separate from the adjustment reason codes above. Transcribe them exactly; do not expand them into the footnote text. Empty array when none." }, "claimNumber": { "type": "string", "description": "The insurer-assigned claim number this line belongs to, if the EOB prints one per line. Never a provider-side visit, encounter or account number." } } }, "description": "One entry per adjudicated service line." } }, "description": "A single Explanation of Benefits, already transcribed." }, "eobs": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "lines" ], "properties": { "processedDate": { "type": "string", "description": "The date the plan processed or finalised the claim. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "claimNumbers": { "type": "array", "items": { "type": "string" }, "description": "Every claim number the INSURER assigned, exactly as printed on the EOB. These are the ids a representative can look up when the patient calls, so they go on the letter verbatim. A provider-side identifier is NOT a claim number: do not take a visit number, encounter number, account number, guarantor number or statement number from a provider bill, even when the bill and the EOB arrive in the same upload. Empty array if the EOB prints none." }, "networkStatus": { "enum": [ "in", "out", "unknown" ], "description": "Whether the EOB states the provider was in or out of network. Use \"unknown\" unless the document says so explicitly \u2014 this drives which protections apply, and a guess here produces a confidently wrong finding." }, "totalPatientRespCents": { "type": "string", "description": "Total patient responsibility across the claim. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "code", "codeType", "description", "dateOfService", "dateOfServiceEnd", "units", "billedCents", "allowedCents", "planPaidCents", "patientRespCents", "deductibleCents", "copayCents", "coinsuranceCents", "notCoveredCents", "denialCodes", "noteCodes", "claimNumber" ], "properties": { "code": { "type": "string", "description": "The procedure code, if printed. Many insurer EOBs show a \"Type of service\" description instead and carry no codes anywhere \u2014 empty string then." }, "codeType": { "type": "string", "description": "Which code set that code belongs to: 'cpt' for a five-digit CPT, 'hcpcs' for a letter followed by four digits, 'revenue' for a three or four digit hospital revenue code, or an empty string if you cannot tell. Do not guess from the description \u2014 say nothing rather than picking one. This decides which numeric ranges the rules are allowed to read the code against, and a revenue code read as a CPT once put a No Surprises Act claim in a letter about a hospital bed." }, "description": { "type": "string", "description": "Service or type-of-service text as printed." }, "dateOfService": { "type": "string", "description": "The service date for this line. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "dateOfServiceEnd": { "type": "string", "description": "The end date, only if the line covers a range. Transcribe exactly as printed, e.g. \"03/14/2026\" or \"2026-03-14\". Write an empty string if it is absent or unreadable. Never infer a date from context." }, "units": { "type": "string", "description": "Units adjudicated, as printed. Empty string if not shown." }, "billedCents": { "type": "string", "description": "What the provider submitted for this line. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "allowedCents": { "type": "string", "description": "The allowed or eligible amount \u2014 the contracted rate. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "planPaidCents": { "type": "string", "description": "What the plan paid. May be labelled plan liability or plan's share. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "patientRespCents": { "type": "string", "description": "What the plan says the patient owes for this line. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "deductibleCents": { "type": "string", "description": "The part applied to the deductible. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "copayCents": { "type": "string", "description": "The copay. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "coinsuranceCents": { "type": "string", "description": "The coinsurance. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "notCoveredCents": { "type": "string", "description": "Any amount shown as not covered or not eligible. Transcribe exactly what is printed, including the currency symbol and any separators. WRITE AN EMPTY STRING if it is not present on the document or you cannot read it clearly \u2014 an empty string is the right answer far more often than you expect, and is always better than a plausible guess. Never estimate, never calculate it from other fields, and never carry a value over from a different line." }, "denialCodes": { "type": "array", "items": { "type": "string" }, "description": "Adjustment or denial reason codes for this line, transcribed exactly, INCLUDING the two-letter group prefix where one is shown \u2014 \"CO-29\", not \"29\". The prefix decides who owes the money and the number alone is ambiguous: CO-96 and PR-96 are the same reason with opposite liability. Empty array when none are printed." }, "noteCodes": { "type": "array", "items": { "type": "string" }, "description": "Any footnote or note codes printed against this line, such as the letters in a \"see notes\" column. These are the plan\u2019s own codes and are separate from the adjustment reason codes above. Transcribe them exactly; do not expand them into the footnote text. Empty array when none." }, "claimNumber": { "type": "string", "description": "The insurer-assigned claim number this line belongs to, if the EOB prints one per line. Never a provider-side visit, encounter or account number." } } }, "description": "One entry per adjudicated service line." } } }, "description": "Every Explanation of Benefits covering this bill, already transcribed. Use this rather than `eob` whenever there is more than one \u2014 a hospital statement usually spans several claims and each claim has its own EOB. Supplying only one of them leaves the rest of the bill looking unmatched, which produces findings about charges the plan did in fact process." }, "good_faith_estimate": { "type": "string", "description": "The total on the written Good Faith Estimate the provider gave the patient before the care, as printed \u2014 \"$1,204.37\". Ask for it whenever the patient is paying without insurance: under the No Surprises Act a self-pay bill that comes in $400 or more above the written estimate can be disputed through the federal patient-provider dispute resolution process, and that check cannot run without this figure. Leave it out if there was no written estimate." }, "label": { "type": "string", "description": "A short human label for this case." } } } } } } } }, "/v1/cases/{case_id}": { "get": { "operationId": "get_case", "summary": "Read a case", "description": "Retrieve a case by id. Returns the same free summary, plus every finding in detail once the case has been unlocked.", "responses": { "200": { "description": "The case summary, and the findings once unlocked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string" }, "documents": { "type": "string", "description": "Which documents the check ran against." }, "findings": { "description": "The number of findings until the case is unlocked; the findings themselves \u2014 an array of Finding \u2014 once it is. The free tier deliberately carries the count and not the detail.", "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } ] }, "what_we_found": { "type": "array", "description": "The free preview: one entry per finding, carrying only what it is about. Present while the case is locked, and absent once it is unlocked \u2014 at that point `findings` holds the same list with the detail attached. Show these titles to the patient before offering the unlock; they are what makes the offer legible. They are **not** a probability that the bill is wrong: use `tier` for that, and see its description.", "items": { "$ref": "#/components/schemas/FindingPreview" } }, "discrepancies": { "type": "integer" }, "worth_asking_about": { "type": "integer" }, "flagged_without_an_amount": { "type": "integer" }, "amount_in_question": { "type": "string", "description": "Formatted, e.g. \"$657.20\"." }, "amount_in_question_cents": { "type": "integer", "description": "The same figure in cents. **Do not add this to anything.** It is already de-duplicated: two findings routinely describe the same dollars at different altitudes, so the total is the larger of the document-level and per-line views, never the sum of the findings." }, "entitled": { "type": "boolean", "description": "Whether the full findings have been unlocked." }, "fields_we_could_not_read": { "type": "integer" }, "how_completely_we_checked": { "type": "string", "enum": [ "checked", "partial" ], "description": "`partial` means the comparison could not be finished \u2014 no Explanation of Benefits was supplied, or fields could not be read. A `partial` scan that found nothing does **not** mean the bill is correct, and must never be presented to the patient as an all-clear. Use `you_can` verbatim when it is present; it is already worded for this distinction." }, "you_can": { "type": "string", "description": "Present only when nothing was found. The patient-facing sentence for that result, worded to match `how_completely_we_checked`." }, "delete_token": { "type": "string", "description": "Returned **once**, here, and never again \u2014 only its digest is stored. It is required to delete the case, and deleting is deliberately a different capability from reading: a case link can end up in a browser history or a forwarded message. Keep it with the case id, or the case can only be waited out (30 days) or removed by support." }, "disclaimer": { "type": "string" }, "next_step": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "operationId": "delete_case", "summary": "Delete a case permanently", "description": "Delete everything held about a case, immediately and permanently. The record is removed, not flagged, and it cannot be recovered afterwards \u2014 not by us either. This is the promise the privacy policy makes, and it needs no account. It does need the delete token issued when the case was created: reading a case and destroying it are deliberately different capabilities.", "responses": { "200": { "description": "Confirmation that the case is gone. It cannot be recovered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string" }, "deleted": { "type": "boolean" }, "next_step": { "type": "string" }, "you_can": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Delete-Token", "in": "header", "required": false, "description": "The one-time delete token, as an alternative to the request body. Use this if your client cannot send a body on a DELETE \u2014 many cannot. Send it one way or the other; the body wins if both are present.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "delete_token" ], "properties": { "delete_token": { "type": "string", "description": "The one-time token returned by check_medical_bill. Deleting is a separate capability from reading on purpose: a case link can end up in a browser history or a forwarded message, and whoever finds it should not be able to destroy the record." } } } } } } } }, "/v1/cases/{case_id}/unlock": { "post": { "operationId": "unlock_case", "summary": "Start checkout for the full findings", "description": "Begin payment to unlock the full findings, the dispute letter and the phone script. Returns a checkout URL; it never charges anything itself. Only offer this when the case actually has findings \u2014 there is nothing to buy otherwise, and the user is told they pay nothing when nothing is found.", "responses": { "200": { "description": "Either the case is unlocked outright by a membership, or a URL to send the patient to. Nothing is charged by this call.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string" }, "checkout_url": { "type": "string", "description": "A Stripe Checkout URL. Send the patient here; do not try to complete payment on their behalf. Absent when `already_unlocked` is true." }, "plan": { "type": "string", "enum": [ "single", "subscription" ] }, "price": { "type": "string", "description": "Formatted, e.g. \"$10.00 for this bill\"." }, "already_unlocked": { "type": "boolean", "description": "True when the case was already paid for. There is nothing to buy again." }, "unlocked_by": { "type": "string", "enum": [ "membership" ], "description": "Present when a membership_token covered this bill. There is no checkout_url in that case, because nothing was charged." }, "membership_token": { "type": "string", "description": "Present only when starting a subscription. **Shown once and never again** \u2014 there is no account to recover it from, because a membership records nobody. Give it to the user to keep, and pass it back as `membership_token` to unlock their later bills. It is inert until the payment completes." }, "membership_note": { "type": "string", "description": "Say this to the user, verbatim." }, "next_step": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "one_bill", "subscription" ], "description": "$10 for this bill, or $10 per month for a membership that unlocks up to 25 bills a calendar month. Offer the membership to someone with several bills, or a family \u2014 25 is far more than a household runs in a year." }, "membership_token": { "type": "string", "description": "An existing membership. If the user already subscribed, pass the token they were given and this bill unlocks immediately with nothing charged \u2014 a membership covers up to 25 bills a calendar month, including other people in the family. Ask for it before offering to charge them again. If it answers membership_cap_reached the membership is fine and simply used up for the month; offer the one-off unlock for this bill." } } } } } } } }, "/v1/cases/{case_id}/outputs": { "post": { "operationId": "get_case_outputs", "summary": "Get the dispute letter and phone script", "description": "Get the dispute letter and the phone script for an unlocked case. The letter is a template the patient sends in their own name.", "responses": { "200": { "description": "The two documents the patient sends and says. This is what the $10 buys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case_id": { "type": "string" }, "portal_message": { "type": "string", "description": "The same ask, short enough to paste into a portal chat box (255 characters). Insurer and provider portals put a live person behind a single-line box with a hard cap, and both the letter and the script are far past it \u2014 a message that overflows is silently cut mid-sentence and the agent answers a question the patient did not ask. Absent when nothing is worth asking. Give it to the user to paste; do not send it anywhere yourself." }, "portal_message_to": { "type": "string", "enum": [ "provider", "plan" ], "description": "Which portal the message belongs in. They are different accounts, and the billing office cannot act on the insurer's adjudication." }, "mailable": { "type": "boolean", "description": "Whether this letter has somewhere to go. False when no usable recipient address was supplied \u2014 nothing in the product derives one from the documents, so the caller is the only one who can. Read it: a false here means ask the user for the billing address printed on their statement, pass it as provider_address_lines and generate again. The letter is still returned either way; the patient can address an envelope by hand." }, "mailable_note": { "type": "string", "description": "Present only when mailable is false: what is missing, written for YOU rather than the patient. Do not read it aloud \u2014 it names request parameters." }, "dispute_letter": { "type": "string", "description": "The full letter, ready to send, written in the patient\u2019s own name and over their signature. Give it to them to read and check before it goes anywhere." }, "dispute_letter_pdf": { "type": "string", "description": "The same letter as a print-ready PDF, base64. Present only when `include_pdf` was true. Save it as .pdf \u2014 do not try to render it as text." }, "phone_script": { "type": "string", "description": "The same case as something to say aloud to the billing office." }, "next_step": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "patient_name" ], "properties": { "patient_name": { "type": "string", "description": "As it should appear on the letter." }, "account_number": { "type": "string" }, "provider_address_lines": { "type": "array", "items": { "type": "string" } }, "include_pdf": { "type": "boolean", "description": "Also return the letter as a print-ready PDF (base64). One page where it fits, addressed for a #10 window envelope, with fold marks. Ask for it whenever the user can print \u2014 a page that folds and posts is far likelier to be sent than text they have to lay out themselves." }, "reply_to_lines": { "type": "array", "items": { "type": "string" }, "description": "Where the provider should write back." }, "letter_date": { "type": "string", "description": "The date to print on the letter, as MM/DD/YYYY. Send the USER's local date: the server runs in UTC, so without this a patient in a western timezone can be handed a letter dated tomorrow, and it is the date the 30-day response window is counted from. Omit it to use the server's date." } } } } } } } }, "/v1/cases/{case_id}/outcome": { "post": { "operationId": "report_outcome", "summary": "Say what came of the letter", "description": "Report what happened after the patient sent the dispute letter. Free, and the single most useful thing a user can do \u2014 this product can tell that two documents disagreed, but it has no way to know whether saying so to a billing office changes anything. Ask a few weeks after the letter went out. \"They ignored it\" and \"I decided not to send it\" are as valuable as a win, and should be offered as answers without any hint that they are lesser ones.", "responses": { "200": { "description": "Acknowledgement. Nothing about the answer is stored against the case.", "content": { "application/json": { "schema": { "type": "object", "properties": { "recorded": { "type": "boolean" }, "already_reported": { "type": "boolean", "description": "True when this case had already been reported. Counted once, never twice." }, "next_step": { "type": "string" }, "you_can": { "type": "string" } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "corrected", "reduced", "refused", "ignored", "waiting", "not_sent" ], "description": "`corrected` the charge was removed in full; `reduced` some of it came off; `refused` they said no; `ignored` no reply at all; `waiting` sent but nothing back yet; `not_sent` the patient decided not to send it." }, "amount_written_off": { "type": "string", "description": "What the provider actually took off the bill, as printed \u2014 \"$412.30\". The one number that says whether any of this works. Omit if nothing came off or it is not known yet." } } } } } } } }, "/v1/cases/{case_id}/export": { "get": { "operationId": "export_case", "summary": "Download everything held about a case", "description": "Everything stored about a case, as JSON, in one response. This is the portable copy the privacy policy offers. It is deliberately the whole record rather than a summary, so that what is returned here can be compared against what the policy says is kept.", "responses": { "200": { "description": "Everything held about the case. Free, and needs no token: nobody should have to pay to see what is held about them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "exported_at": { "type": "string", "format": "date-time" }, "case_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "deleted_after": { "type": "string", "format": "date-time", "description": "When the case deletes itself, whatever else happens." }, "entitled": { "type": "boolean" }, "name": { "type": "string" }, "provider_name": { "type": "string", "nullable": true }, "account_number": { "type": "string", "nullable": true }, "claim_numbers": { "type": "array", "items": { "type": "string" } }, "ran_bill_only": { "type": "boolean" }, "fields_we_could_not_read": { "type": "integer" }, "how_completely_we_checked": { "type": "string", "enum": [ "checked", "partial" ] }, "headline": { "type": "object", "description": "The totals, as the scan computed them." }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Present only when the case is unlocked." }, "findings_withheld": { "type": "integer", "description": "How many findings exist but are not included, because the detail is the part that is paid for. Present instead of `findings` on a locked case, alongside `what_we_found`, which names each one." }, "what_we_found": { "type": "array", "items": { "$ref": "#/components/schemas/FindingPreview" }, "description": "The free preview of each finding \u2014 title, tier and amount. Present on a locked case; once unlocked, `findings` carries the same list with the detail attached." }, "why_withheld": { "type": "string" }, "not_held": { "type": "array", "items": { "type": "string" }, "description": "What we never had, said out loud so an absence need not be inferred." } } } } } }, "400": { "description": "The request was missing something.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "402": { "description": "The case has not been unlocked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "403": { "description": "The case id and delete token do not match a case we hold. Deliberately the same answer whether the token was wrong or the case never existed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "404": { "description": "No such case.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "405": { "description": "The path exists but not with this method. The Allow header lists the methods that work.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "409": { "description": "There is nothing to unlock, because nothing was found.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "413": { "description": "The upload is larger than we accept.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "415": { "description": "We cannot read that kind of file.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "422": { "description": "The document could not be read well enough to check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "429": { "description": "Too many requests. Back off and retry.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "500": { "description": "Something went wrong on our side. Not the caller\u2019s fault; retryable once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "502": { "description": "A dependency (the payment processor, the document reader) answered badly. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "503": { "description": "A dependency is unavailable. Retryable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } }, "504": { "description": "Reading the document took too long. Retryable; a PDF reads faster than a photo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } } } } } }, "parameters": [ { "name": "case_id", "in": "path", "required": true, "schema": { "type": "string" } } ] } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "A stable machine-readable code. Branch on this, never on the message text." }, "message": { "type": "string", "description": "One sentence, safe to show the person who uploaded the document." } } }, "next_step": { "type": "string", "description": "What you should do or say next, in plain English. Addressed to YOU, the caller \u2014 it says things like \"Ask the patient for a clearer copy\". Do not show it to the patient verbatim; use `you_can` for that." }, "you_can": { "type": "string", "description": "The same guidance written in the second person, safe to show the patient directly." } } }, "CaseSummary": { "type": "object", "properties": { "case_id": { "type": "string" }, "documents": { "type": "string", "description": "Which documents the check ran against." }, "findings": { "description": "The number of findings until the case is unlocked; the findings themselves \u2014 an array of Finding \u2014 once it is. The free tier deliberately carries the count and not the detail.", "oneOf": [ { "type": "integer" }, { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } ] }, "what_we_found": { "type": "array", "description": "The free preview: one entry per finding, carrying only what it is about. Present while the case is locked, and absent once it is unlocked \u2014 at that point `findings` holds the same list with the detail attached. Show these titles to the patient before offering the unlock; they are what makes the offer legible. They are **not** a probability that the bill is wrong: use `tier` for that, and see its description.", "items": { "$ref": "#/components/schemas/FindingPreview" } }, "discrepancies": { "type": "integer" }, "worth_asking_about": { "type": "integer" }, "flagged_without_an_amount": { "type": "integer" }, "amount_in_question": { "type": "string", "description": "Formatted, e.g. \"$657.20\"." }, "amount_in_question_cents": { "type": "integer", "description": "The same figure in cents. **Do not add this to anything.** It is already de-duplicated: two findings routinely describe the same dollars at different altitudes, so the total is the larger of the document-level and per-line views, never the sum of the findings." }, "entitled": { "type": "boolean", "description": "Whether the full findings have been unlocked." }, "fields_we_could_not_read": { "type": "integer" }, "how_completely_we_checked": { "type": "string", "enum": [ "checked", "partial" ], "description": "`partial` means the comparison could not be finished \u2014 no Explanation of Benefits was supplied, or fields could not be read. A `partial` scan that found nothing does **not** mean the bill is correct, and must never be presented to the patient as an all-clear. Use `you_can` verbatim when it is present; it is already worded for this distinction." }, "you_can": { "type": "string", "description": "Present only when nothing was found. The patient-facing sentence for that result, worded to match `how_completely_we_checked`." }, "delete_token": { "type": "string", "description": "Returned **once**, here, and never again \u2014 only its digest is stored. It is required to delete the case, and deleting is deliberately a different capability from reading: a case link can end up in a browser history or a forwarded message. Keep it with the case id, or the case can only be waited out (30 days) or removed by support." }, "disclaimer": { "type": "string" }, "next_step": { "type": "string" } } }, "FindingPreview": { "type": "object", "description": "One finding, as it appears before the case is unlocked. Three fields, all free: what it is about, how firm it is, and how much it concerns. The explanation, what to ask for, who to ask and the statute are the paid part and are absent here.", "required": [ "title", "tier", "amount" ], "properties": { "title": { "type": "string", "description": "What the finding is about, in the patient's terms, e.g. \"The bill asks for more than your plan says you owe\". It names the disagreement; it does not resolve it." }, "tier": { "type": "string", "enum": [ "discrepancy", "worth_asking" ], "description": "The only confidence signal this product publishes, and a grounded one: `discrepancy` means the two documents state different things and the patient can verify that against their own paper; `worth_asking` means it is a question, not a contradiction. Neither is a claim that the provider is wrong \u2014 a bill can be correct and still produce findings. Do not convert these into a percentage." }, "amount": { "type": [ "string", "null" ], "description": "Formatted, e.g. \"$200.00\", or null when the finding carries no amount. Never sum these." } } }, "Finding": { "type": "object", "description": "One thing the two documents disagree about, or one thing worth asking.", "required": [ "rule", "title", "tier", "confidence", "amount", "explanation", "ask_this", "directed_at", "cites" ], "properties": { "rule": { "type": "string", "description": "The deterministic rule that produced it, e.g. \"F07\"." }, "title": { "type": "string" }, "tier": { "type": "string", "enum": [ "discrepancy", "worth_asking" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "amount": { "type": [ "string", "null" ], "description": "Formatted, e.g. \"$200.00\", or null when the finding carries no amount. Never sum these." }, "explanation": { "type": "string", "description": "Addressed to the patient." }, "ask_this": { "type": "string", "description": "What to ask, addressed to the patient." }, "directed_at": { "type": "string", "enum": [ "provider", "plan" ] }, "cites": { "type": [ "string", "null" ], "description": "A statute label, only where it plainly applies." } } } } } }