MedBillAnalyzer

{'type': 'object', 'anyOf': [{'required': ['bill']}, {'required': ['bill_document']}], 'properties': {'eob': {'type': 'object', 'required': ['lines'], 'properties': {'lines': {'type': 'array', 'items': {'type': 'object', '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 — empty string then.'}, 'units': {'type': 'string', 'description': 'Units adjudicated, as printed. Empty string if not shown.'}, '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 — 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."}, '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’s 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.'}, 'copayCents': {'type': 'string', 'description': 'The copay. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'billedCents': {'type': 'string', 'description': 'What the provider submitted for this line. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, '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.'}, '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 — "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.'}, 'description': {'type': 'string', 'description': 'Service or type-of-service text as printed.'}, 'allowedCents': {'type': 'string', 'description': 'The allowed or eligible amount — the contracted rate. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'dateOfService': {'type': 'string', 'description': 'The service date for this line. If the line prints a span, such as "03/14/2026 - 03/16/2026", put the first date here and the last in dateOfServiceEnd. 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.'}, 'planPaidCents': {'type': 'string', 'description': 'What the plan paid. May be labelled plan liability or plan\'s share. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'dateOfServiceEnd': {'type': 'string', 'description': 'The last date, only when the line prints a span of dates. 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.'}, 'patientRespCents': {'type': 'string', 'description': 'What the plan says the patient owes for this line. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'additionalProperties': False}, 'description': 'One entry per adjudicated service line. Claim totals, subtotals and payment summaries are not service lines: leave them out. When the EOB shows a service in a summary and again in the claim detail, transcribe it once, from the claim detail.'}, '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 — this drives which protections apply, and a guess here produces a confidently wrong finding.'}, '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.'}, 'totalPatientRespCents': {'type': 'string', 'description': 'Total patient responsibility across the claim. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'description': 'A single Explanation of Benefits, already transcribed.', 'additionalProperties': False}, 'bill': {'type': 'object', 'required': ['lines'], 'properties': {'lines': {'type': 'array', 'items': {'type': 'object', '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 — write an empty string then, rather than inferring a code from the description. An invented code is worse than none.'}, 'units': {'type': 'string', 'description': 'Units, quantity or days billed, as printed. Empty string if no such column exists.'}, '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 — 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."}, 'chargeCents': {'type': 'string', 'description': 'The gross charge for this line, before any insurance adjustment. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'description': {'type': 'string', 'description': 'The service description exactly as printed on the line.'}, 'dateOfService': {'type': 'string', 'description': 'The date this service was provided. If the line prints a span, such as "03/14/2026 - 03/16/2026", put the first date here and the last in dateOfServiceEnd. 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 last date, only when the line prints a span of dates. 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.'}, '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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'additionalProperties': False}, 'description': 'One entry per service the statement charges for. Empty when the statement is not itemized. Payments, insurance payments, adjustments, write-offs, discounts, subtotals, totals and a previous or prior balance are not services: leave those rows out of lines. When the statement lists its services twice, in a summary and again in an itemized detail, transcribe each service once, from the itemized detail.'}, '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.'}, 'facilityName': {'type': 'string', 'description': 'The facility, if different from the provider. Empty string if the same or absent.'}, 'providerName': {'type': 'string', 'description': 'Who is billing, as printed.'}, '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.'}, 'amountDueCents': {'type': 'string', 'description': 'The balance the patient is being asked to pay now. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'totalChargedCents': {'type': 'string', 'description': 'The total charges on the statement. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'description': 'The bill already transcribed into structured form. Prefer `bill_document` when you can send the file itself or a link to it: the transcription is then done by a reader tuned for these forms and checked against a field-accuracy harness. Use this field when you can READ the bill but cannot send its bytes — for example, an assistant looking at a file the patient attached to the conversation. Copy what is printed: money and dates as the strings on the page ("$1,204.37", "03/14/2026"), every line, and nothing that is not there. File contents belong in `bill_document`.', 'additionalProperties': False}, 'eobs': {'type': 'array', 'items': {'type': 'object', 'required': ['lines'], 'properties': {'lines': {'type': 'array', 'items': {'type': 'object', '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 — empty string then.'}, 'units': {'type': 'string', 'description': 'Units adjudicated, as printed. Empty string if not shown.'}, '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 — 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."}, '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’s 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.'}, 'copayCents': {'type': 'string', 'description': 'The copay. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'billedCents': {'type': 'string', 'description': 'What the provider submitted for this line. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, '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.'}, '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 — "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.'}, 'description': {'type': 'string', 'description': 'Service or type-of-service text as printed.'}, 'allowedCents': {'type': 'string', 'description': 'The allowed or eligible amount — the contracted rate. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'dateOfService': {'type': 'string', 'description': 'The service date for this line. If the line prints a span, such as "03/14/2026 - 03/16/2026", put the first date here and the last in dateOfServiceEnd. 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.'}, 'planPaidCents': {'type': 'string', 'description': 'What the plan paid. May be labelled plan liability or plan\'s share. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. 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: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}, 'dateOfServiceEnd': {'type': 'string', 'description': 'The last date, only when the line prints a span of dates. 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.'}, 'patientRespCents': {'type': 'string', 'description': 'What the plan says the patient owes for this line. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'additionalProperties': False}, 'description': 'One entry per adjudicated service line. Claim totals, subtotals and payment summaries are not service lines: leave them out. When the EOB shows a service in a summary and again in the claim detail, transcribe it once, from the claim detail.'}, '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 — this drives which protections apply, and a guess here produces a confidently wrong finding.'}, '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.'}, 'totalPatientRespCents': {'type': 'string', 'description': 'Total patient responsibility across the claim. Transcribe exactly what is printed: the currency symbol, the separators as printed (a comma used as the decimal point stays a comma), and any parentheses, minus sign or "CR" marking a credit. If this document does not print the value, write an empty string — blank cells are common, and an empty string is always better than a plausible value. If it is printed but hard to read, write your best reading and score it 0.5 to 0.8 in confidence; write an empty string only if you cannot make it out at all. Never estimate, never calculate it from other fields, and never carry a value over from a different line.'}}, 'additionalProperties': False}, 'description': 'Every Explanation of Benefits covering this bill, already transcribed. Use this rather than `eob` whenever there is more than one — 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.'}, 'label': {'type': 'string', 'description': 'A short human label for this case.'}, 'eob_document': {'type': 'object', 'anyOf': [{'required': ['data_base64']}, {'required': ['url']}, {'required': ['upload_id']}], 'properties': {'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 — this service sends no cookies and no credentials of any kind — so for an Explanation of Benefits inside an insurer portal, the patient has to download it and send the bytes.'}, 'filename': {'type': 'string', 'description': 'Optional, for your own logs. Not used.'}, '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 — 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.'}, '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 — and a request claiming "application/pdf" over a JPEG would otherwise reach the reader as the wrong kind of thing.'}}, 'description': 'The Explanation of Benefits as a file, read for you. It usually sits behind the insurer’s login, which is what `upload_id` is for. Send it one of three ways: `data_base64` if you have the bytes; `upload_id` if the patient has to fetch the file themselves — reserve a slot with `POST /v1/uploads` and PUT the file there first; `url` if you only have a public https link. Send exactly one; if more than one is present, `data_base64` wins, then `upload_id`, then `url`. None of them is a promise the file is readable; that is decided from the bytes after they arrive.'}, 'bill_document': {'type': 'object', 'anyOf': [{'required': ['data_base64']}, {'required': ['url']}, {'required': ['upload_id']}], 'properties': {'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 — this service sends no cookies and no credentials of any kind — so for an Explanation of Benefits inside an insurer portal, the patient has to download it and send the bytes.'}, 'filename': {'type': 'string', 'description': 'Optional, for your own logs. Not used.'}, '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 — 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.'}, '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 — and a request claiming "application/pdf" over a JPEG would otherwise reach the reader as the wrong kind of thing.'}}, 'description': 'The bill as a file, read for you. Use this when you have the document itself — a photo, a scan, or a PDF from the provider’s portal. Send it one of three ways: `data_base64` if you have the bytes; `upload_id` if the patient has to fetch the file themselves — reserve a slot with `POST /v1/uploads` and PUT the file there first; `url` if you only have a public https link. Send exactly one; if more than one is present, `data_base64` wins, then `upload_id`, then `url`. None of them is a promise the file is readable; that is decided from the bytes after they arrive.'}, 'good_faith_estimate': {'type': 'string', 'description': 'The total on the written Good Faith Estimate the provider gave the patient before the care, as printed — "$1,204.37". Needed for the self-pay check: 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.'}}}

{'type': 'object', 'required': ['case_id', 'delete_token'], 'properties': {'case_id': {'type': 'string'}, '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.'}}}

{'type': 'object', 'required': ['case_id'], 'properties': {'case_id': {'type': 'string'}}}

{'type': 'object', 'required': ['case_id'], 'properties': {'case_id': {'type': 'string'}}}

{'type': 'object', 'required': ['case_id', 'patient_name'], 'properties': {'case_id': {'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.'}, '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."}, 'patient_name': {'type': 'string', 'description': 'As it should appear on the letter.'}, 'account_number': {'type': 'string'}, 'reply_to_lines': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Where the provider should write back.'}, 'provider_address_lines': {'type': 'array', 'items': {'type': 'string'}}}}

{'type': 'object', 'required': ['case_id', 'outcome'], 'properties': {'case_id': {'type': 'string'}, 'outcome': {'enum': ['corrected', 'reduced', 'refused', 'ignored', 'waiting', 'not_sent'], 'type': 'string', '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 — "$412.30". The one number that says whether any of this works. Omit if nothing came off or it is not known yet.'}}}

{'type': 'object', 'required': ['case_id'], 'properties': {'plan': {'enum': ['one_bill', 'subscription'], 'type': 'string', 'description': '"one_bill" is $10 for this bill. "subscription" is a $10-a-month membership that unlocks up to 25 bills a calendar month for anyone in a household.'}, 'case_id': {'type': 'string'}, '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 — a membership covers up to 25 bills a calendar month, including other people in the family. A membership that has used its 25 bills for the month answers membership_cap_reached; it is still valid, and a one-off unlock still works.'}}}