# Documents and attachments > The paper side of the same claims and answers: PDFs drawn from what you send, a 275 for attachments, and two picture reads behind their switches. Page: https://payerworks.com/docs/documents · Markdown: https://payerworks.com/docs/documents.md > Payerworks writes and explains files; it sends nothing to a payer. Every file a route writes says `transmitted: false`, and is yours to send on your own connection. A test key is for invented data only, never a real patient. The paper side of the same claims and answers. A claim is drawn on the CMS-1500 after the same checks POST /v1/claims/837p makes; a remittance and an eligibility answer are drawn as the explain routes read them; Medicare’s redetermination and reconsideration forms are CMS’s own files, filled in. Each PDF comes back in the answer as base64 with its SHA-256, and Payerworks keeps no copy. POST /v1/attachments/275 writes a claim’s attachments as an X12 275 under the control number the claim’s PWK segment announced. A payer that wants more before it decides a claim sends a 277 request for additional information. POST /v1/attachments/requests/explain says it claim by claim (each LOINC code it asks for, about which claim and line, and by when) and lays out the solicited 275 that answers it; POST /v1/attachments/275 writes that 275 from those values, and POST /v1/attachments/requests/check holds it to the request before you send it. In the claims sandbox, a member ID ending in RFAI is held for a document, and the same claims sent again with the 275 are paid. The two picture reads (a paper EOB into a draft 835, a card photo into the payer and member ID) are built and switched off until Payerworks turns them on. New here? Start with [A first 275](https://payerworks.com/docs/quickstart-first-275). ## Routes - [POST /v1/claims/cms1500](#post-v1-claims-cms1500): Draw claims on the CMS-1500 - [POST /v1/remittances/pdf](#post-v1-remittances-pdf): Print a remittance - [POST /v1/eligibility/pdf](#post-v1-eligibility-pdf): Print an eligibility answer - [POST /v1/appeals/form](#post-v1-appeals-form): Fill a Medicare appeal form - [POST /v1/attachments/275](#post-v1-attachments-275): Write a 275 attachment - [POST /v1/attachments/requests/explain](#post-v1-attachments-requests-explain): Read a request for more information - [POST /v1/attachments/requests/check](#post-v1-attachments-requests-check): Check a 275 against its request - [POST /v1/remittances/from-image](#post-v1-remittances-from-image): Read a paper EOB into a draft 835 - [POST /v1/payers/from-card](#post-v1-payers-from-card): Look up a payer from a card photo Each route shows its call with curl and with the two clients, then its real answer, shortened, and the fields it holds. The client calls assume one client made once, `const pw = new Payerworks()` in JavaScript or `pw = payerworks.Payerworks()` in Python, each reading PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL, and `body` is the request.json shown. ### POST /v1/claims/cms1500 **Draw claims on the CMS-1500.** Up to one hundred claims in the 837P’s JSON, checked by the same claim checks as POST /v1/claims/837p (your own rules are not applied here) and drawn on the CMS-1500 (02/12): six service lines a form, as many forms as a claim needs (at most 200 a call), each form’s Box 28 the total of its own lines. form: full puts CMS’s own form under the data; data_only prints the data alone, to print onto pre-printed red forms (print one on plain paper and hold it against a form first). Send signed_on to date Boxes 12 and 31, which are otherwise left undated, and payer_address for the carrier block. The answer is your PDF as base64; nothing is sent or kept. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/cms1500" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postClaimsCms1500(body); ``` With the Python client ```python answer = pw.post_claims_cms1500(body) ``` request.json ```json { "claim": { "tradingPartnerServiceId": "99999", "submitter": { "organizationName": "Sample Family Medicine", "contactInformation": { "name": "Billing Office", "phoneNumber": "5555550100" } }, "receiver": { "organizationName": "Sample Health Plan" }, "billing": { "npi": "1234567893", "employerId": "123456789", "organizationName": "Sample Family Medicine", "taxonomyCode": "207Q00000X", "address": { "address1": "100 Main Street", "city": "Springfield", "state": "IL", "postalCode": "627011234" } }, "subscriber": { "memberId": "W123456789", "paymentResponsibilityLevelCode": "P", "firstName": "Sample", "lastName": "Patient", "gender": "F", "dateOfBirth": "19800214", "address": { "address1": "9 Elm Street", "city": "Springfield", "state": "IL", "postalCode": "62701" } }, "claimInformation": { "claimFilingCode": "CI", "patientControlNumber": "PW-2001", "claimChargeAmount": "215.00", "placeOfServiceCode": "11", "claimFrequencyCode": "1", "signatureIndicator": "Y", "planParticipationCode": "A", "benefitsAssignmentCertificationIndicator": "Y", "releaseInformationCode": "Y", "healthCareCodeInformation": [ { "diagnosisTypeCode": "ABK", "diagnosisCode": "J029" }, { "diagnosisTypeCode": "ABF", "diagnosisCode": "R509" } ], "serviceLines": [ { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "99213", "lineItemChargeAmount": "150.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1", "2" ] } } }, { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "87880", "lineItemChargeAmount": "65.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] } } } ] } }, "form": "full", "signed_on": "2026-10-19", "payer_address": { "address1": "PO Box 100", "city": "Springfield", "state": "IL", "postalCode": "62701" } } ``` The answer (200) ```json { "document": "cms1500", "content_type": "application/pdf", "filename": "cms1500-20261019.pdf", "pages": 1, "bytes": 198311, "sha256": "ddf6013e3b086ddb5b6ae2e5c3bcf5484015ffa022ab78ce1ae9409099b96703", "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL1R5cGUgL1hPYmplY3QKL1N1YnR5...", "notice": "Your document: Payerworks drew it from what you sent. Payerworks sent nothing to any payer and kept no copy.", "form": "full", "forms": [ { "claim": 0, "reference": "PW-2001", "page": 1, "lines": [ 1, 2 ] } ], "shrunk": [], "claims": [ { "index": 0, "reference": "PW-2001", "errors": [], "warnings": [], "repairs": [], "not_checked": [] } ], "dated": "Boxes 12 and 31 are dated 10/19/2026.", "sources": [ { "name": "CMS, Medicare Claims Processing Manual, chapter 26 (Item 24F and Item 28)", "url": "https://www.cms.gov/regulations-and-guidance/guidance/manuals/downloads/clm104c26pdf.pdf", "read_on": "10/19/2026" } ], "stored": false, "transmitted": false } ``` | Field | Type | What it is | | --- | --- | --- | | `document` | string | Which document: cms1500, remittance, eligibility, cms-20027 or cms-20033. | | `content_type` | the value "application/pdf" | | | `filename` | string | A name to save it under. | | `pages` | integer | | | `bytes` | integer | The PDF’s size. | | `sha256` | string | The PDF’s SHA-256, in hex. | | `pdf_base64` | string | The PDF, base64. The examples here show only its start. | | `notice` | string | Printed on every page Payerworks draws and in the file’s subject: the document is yours, nothing was sent and no copy was kept. | | `stored` | the value false | | | `transmitted` | the value false | Payerworks drew the document and sent it nowhere. | | `form` | one of "full", "data_only" | | | `forms` | list of object | Each form, the claim it draws and its lines: Box 28 is the total of its own lines. | | `shrunk` | list of string | Each value set smaller to fit its box, never cut. | | `claims` | list of ClaimChecks | Each claim as POST /v1/claims/837p checks it: the form draws the repaired claim. | | `dated` | string | | | `sources` | list of object | | ### POST /v1/remittances/pdf **Print a remittance.** An 835 laid out the way Medicare’s Standard Paper Remittance is read: each check, each claim and its service lines with what was billed, allowed, applied to the deductible and coinsurance, adjusted and paid, the check’s totals and provider-level adjustments, and a glossary of every code on the file. Up to 500 claims and 3,000 service lines a call. The answer is your PDF as base64. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/remittances/pdf" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postRemittancesPdf(body); ``` With the Python client ```python answer = pw.post_remittances_pdf(body) ``` request.json ```json { "x12": "ISA*00* *00* *ZZ*SAMPLEPAYER *ZZ*SAMPLEBILLER *261018*0900*^*00501*000000001*0*T*:~\nGS*HP*SAMPLEPAYER*SAMPLEBILLER*20261018*0900*1*X*005010X221A1~\nST*835*0001~\nBPR*I*1260*C*ACH*CCP*01*999999999*DA*123456*1234567890**01*999999999*DA*654321*20261018~\nTRN*1*EFT-20261018-01*1234567890~\nN1*PR*SAMPLE HEALTH PLAN*PI*99999~\nN1*PE*SAMPLE SLEEP DENTISTRY*XX*1234567893~\nLX*1~\nCLP*PW-1001*1*2900*1260*240*12*PAYER-CN-1*11~\nCAS*CO*45*1400~\nCAS*PR*2*240~\nNM1*QC*1*PATIENT*SAMPLE~\nDTM*472*20261001~\nSVC*HC:E0486*2900*1260~\nAMT*B6*1500~\nCLP*PW-1002*4*350*0*0*12*PAYER-CN-2*11~\nCAS*CO*50*350~\nNM1*QC*1*PATIENT*SECOND~\nDTM*472*20261002~\nSVC*HC:95800*350*0~\nLQ*HE*N115~\nSE*20*0001~\nGE*1*1~\nIEA*1*000000001~" } ``` The answer (200) ```json { "document": "remittance", "content_type": "application/pdf", "filename": "remittance-20261019.pdf", "pages": 1, "bytes": 5142, "sha256": "be50686577c0787609da31857e494a6a3e1f8c94e290bfd62d528709f26bb0d0", "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK...", "notice": "Your document: Payerworks drew it from what you sent. Payerworks sent nothing to any payer and kept no copy.", "checks": 1, "claims": 2, "service_lines": 2, "sources": [ { "name": "CMS, Remittance Advice Resources and FAQs (MLN booklet ICN 905367)", "url": "https://www.cms.gov/Outreach-and-Education/Medicare-Learning-Network-MLN/MLNProducts/Downloads/ICN905367TextOnly.pdf", "read_on": "10/19/2026" }, { "name": "CMS, Medicare Claims Processing Manual, chapter 22, section 50 (Standard Paper Remittance)", "url": "https://www.cms.gov/regulations-and-guidance/guidance/manuals/downloads/clm104c22.pdf", "read_on": "10/19/2026" } ], "stored": false, "transmitted": false } ``` | Field | Type | What it is | | --- | --- | --- | | `document` | string | Which document: cms1500, remittance, eligibility, cms-20027 or cms-20033. | | `content_type` | the value "application/pdf" | | | `filename` | string | A name to save it under. | | `pages` | integer | | | `bytes` | integer | The PDF’s size. | | `sha256` | string | The PDF’s SHA-256, in hex. | | `pdf_base64` | string | The PDF, base64. The examples here show only its start. | | `notice` | string | Printed on every page Payerworks draws and in the file’s subject: the document is yours, nothing was sent and no copy was kept. | | `stored` | the value false | | | `transmitted` | the value false | Payerworks drew the document and sent it nowhere. | | `checks` | integer | | | `claims` | integer | | | `service_lines` | integer | | | `sources` | list of object | | ### POST /v1/eligibility/pdf **Print an eligibility answer.** A 271, as POST /v1/eligibility/explain takes it, as a summary per patient: what was asked and what the answer echoes back, whether the coverage is active, the plan’s figures in and out of network, each service type asked, and every benefit line by plan and then service type. Up to 50 patients and 3,000 benefit lines a call, and 3,000 rows as drawn: a benefit line is listed under each service type it names, so a line naming ten service types is ten rows (and each of its messages one more under each). The answer is your PDF as base64. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/eligibility/pdf" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postEligibilityPdf(body); ``` With the Python client ```python answer = pw.post_eligibility_pdf(body) ``` request.json ```json { "x12": "ISA*00* *00* *ZZ*SAMPLEPAYER *ZZ*SAMPLEBILLER *261018*0900*^*00501*000000091*0*T*:~\nGS*HB*SAMPLEPAYER*SAMPLEBILLER*20261018*0900*91*X*005010X279A1~\nST*271*0001*005010X279A1~\nBHT*0022*11*ELIG-0001*20261018*0900~\nHL*1**20*1~\nNM1*PR*2*SAMPLE HEALTH PLAN*****PI*99999~\nHL*2*1*21*1~\nNM1*1P*2*SAMPLE FAMILY MEDICINE*****XX*1234567893~\nHL*3*2*22*0~\nTRN*2*ELIG-0001*9SAMPLEBIL~\nNM1*IL*1*PATIENT*SAMPLE****MI*W123456789~\nREF*6P*G7700*SAMPLE EMPLOYER GROUP~\nDMG*D8*19800214*F~\nDTP*346*D8*20260101~\nEB*1*IND*30*PR*SAMPLE PPO~\nEB*C*IND*30***23*1500*****Y~\nEB*C*IND*30***29*600*****Y~\nEB*G*IND*30***23*6000*****Y~\nEB*G*IND*30***29*4100*****Y~\nEB*C*FAM*30***23*3000*****Y~\nEB*C*FAM*30***29*1800*****Y~\nEB*A*IND*30*****.2****Y~\nEB*C*IND*30***23*3000*****N~\nEB*C*IND*30***29*3000*****N~\nEB*A*IND*30*****.4****N~\nEB*B*IND*98****25*****Y~\nEB*A*IND*98*****.4****N~\nEB*1*IND*62********Y~\nSE*27*0001~\nGE*1*91~\nIEA*1*000000091~", "asked": { "service_type_codes": [ "30", "98", "62" ], "date_of_service": "2026-10-20" } } ``` The answer (200) ```json { "document": "eligibility", "content_type": "application/pdf", "filename": "eligibility-20261019.pdf", "pages": 1, "bytes": 6999, "sha256": "03927a87f1174d778f9953402d7ee60106b93ae3d09e7501325ffb0776444961", "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUK...", "notice": "Your document: Payerworks drew it from what you sent. Payerworks sent nothing to any payer and kept no copy.", "patients": 1, "benefit_lines": 14, "stored": false, "transmitted": false } ``` | Field | Type | What it is | | --- | --- | --- | | `document` | string | Which document: cms1500, remittance, eligibility, cms-20027 or cms-20033. | | `content_type` | the value "application/pdf" | | | `filename` | string | A name to save it under. | | `pages` | integer | | | `bytes` | integer | The PDF’s size. | | `sha256` | string | The PDF’s SHA-256, in hex. | | `pdf_base64` | string | The PDF, base64. The examples here show only its start. | | `notice` | string | Printed on every page Payerworks draws and in the file’s subject: the document is yours, nothing was sent and no copy was kept. | | `stored` | the value false | | | `transmitted` | the value false | Payerworks drew the document and sent it nowhere. | | `patients` | integer | | | `benefit_lines` | integer | | ### POST /v1/appeals/form **Fill a Medicare appeal form.** CMS’s own redetermination request (CMS-20027) or reconsideration request (CMS-20033), the file CMS publishes, filled from the claim and the 835 that denied it: the beneficiary, the Medicare number, the codes of the lines the payer denied (a line it paid is never listed) and their dates of service, the notice date, and why you disagree in your words. Original Medicare only. Nothing is signed, dated or chosen for you, the deadline comes with its regulation, and the form is yours to review and send. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/appeals/form" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postAppealsForm(body); ``` With the Python client ```python answer = pw.post_appeals_form(body) ``` request.json ```json { "form": "redetermination", "x12": "ISA*00* *00* *ZZ*SAMPLEPAYER *ZZ*SAMPLEBILLER *261018*0900*^*00501*000000001*0*T*:~\nGS*HP*SAMPLEPAYER*SAMPLEBILLER*20261018*0900*1*X*005010X221A1~\nST*835*0001~\nBPR*I*1260*C*ACH*CCP*01*999999999*DA*123456*1234567890**01*999999999*DA*654321*20261018~\nTRN*1*EFT-20261018-01*1234567890~\nDTM*405*20261016~\nN1*PR*SAMPLE HEALTH PLAN*PI*99999~\nN1*PE*SAMPLE SLEEP DENTISTRY*XX*1234567893~\nLX*1~\nCLP*PW-1001*1*2900*1260*240*12*PAYER-CN-1*11~\nCAS*CO*45*1400~\nCAS*PR*2*240~\nNM1*QC*1*PATIENT*SAMPLE~\nDTM*472*20261001~\nSVC*HC:E0486*2900*1260~\nAMT*B6*1500~\nCLP*PW-1002*4*350*0*0*MB*PAYER-CN-2*11~\nCAS*CO*50*350~\nNM1*QC*1*PATIENT*SECOND~\nDTM*472*20261002~\nSVC*HC:95800*350*0~\nLQ*HE*N115~\nSE*20*0001~\nGE*1*1~\nIEA*1*000000001~", "reference": "PW-1002", "claim": { "tradingPartnerServiceId": "99999", "submitter": { "organizationName": "Sample Family Medicine", "contactInformation": { "name": "Billing Office", "phoneNumber": "5555550100" } }, "receiver": { "organizationName": "Sample Health Plan" }, "billing": { "npi": "1234567893", "employerId": "123456789", "organizationName": "Sample Family Medicine", "taxonomyCode": "207Q00000X", "address": { "address1": "100 Main Street", "city": "Springfield", "state": "IL", "postalCode": "627011234" } }, "subscriber": { "memberId": "1EG4TE5MK73", "paymentResponsibilityLevelCode": "P", "firstName": "Sample", "lastName": "Patient", "gender": "F", "dateOfBirth": "19800214", "address": { "address1": "9 Elm Street", "city": "Springfield", "state": "IL", "postalCode": "62701" } }, "claimInformation": { "claimFilingCode": "CI", "patientControlNumber": "PW-1002", "claimChargeAmount": "215.00", "placeOfServiceCode": "11", "claimFrequencyCode": "1", "signatureIndicator": "Y", "planParticipationCode": "A", "benefitsAssignmentCertificationIndicator": "Y", "releaseInformationCode": "Y", "healthCareCodeInformation": [ { "diagnosisTypeCode": "ABK", "diagnosisCode": "J029" }, { "diagnosisTypeCode": "ABF", "diagnosisCode": "R509" } ], "serviceLines": [ { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "99213", "lineItemChargeAmount": "150.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1", "2" ] } } }, { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "87880", "lineItemChargeAmount": "65.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] } } } ] } }, "reason": "The study was ordered for a documented condition; the order and the visit note are enclosed.", "evidence": true } ``` The answer (200) ```json { "document": "cms-20027", "content_type": "application/pdf", "filename": "cms-20027-PW-1002.pdf", "pages": 1, "bytes": 55228, "sha256": "634e37b62abac326693c63c4d431f8618c41ee9bca5c9a1a997d05a38e3f27ee", "pdf_base64": "JVBERi0xLjcKJYGBgYEKCjEgMCBvYmoKPDwKL0JCb3ggWyAwIDAgNy42ODAwMiA3...", "notice": "Your document: Payerworks drew it from what you sent. Payerworks sent nothing to any payer and kept no copy.", "form": { "id": "cms-20027", "form_number": "CMS-20027", "revision": "01/20", "level": 1, "name": "Medicare Redetermination Request Form (1st level of appeal)", "source_url": "https://www.cms.gov/medicare/cms-forms/cms-forms/downloads/cms20027.pdf", "sha256": "bc80ed47453ddabf3628106fbdf6151c13951be697a2098d548fa7f7be92f09c", "retrieved_on": "10/19/2026", "fillable": true }, "claim": { "reference": "PW-1002", "index": 1, "payer_claim_number": "PAYER-CN-2", "claim_filing_indicator": "MB", "verdict": "denied", "verdict_words": "Refused: the payer paid nothing. The refusing adjustment is CO-50 (Non-covered: not deemed a medical necessity).", "lines_appealed": [ 0 ] }, "filled": { "beneficiary_name": "Sample Patient", "medicare_number": "1EG4TE5MK73", "item_or_service": "95800", "date_received": "10/02/2026", "notice_date": "10/16/2026", "contractor": "SAMPLE HEALTH PLAN", "reason": "The study was ordered for a documented condition; the order and the visit note are enclosed.", "appellant_name": "Sample Family Medicine", "appellant_street": "100 Main Street", "appellant_city": "Springfield", "appellant_state": "IL", "appellant_zip": "62701-1234", "appellant_phone": "(555) 555-0100", "evidence": "I have evidence to submit", "appellant_type": "Person appealing - Provider/Supplier" }, "filled_from": { "beneficiary": "claim (the patient)", "item_or_service": "the 835's lines for this claim payment (procedure codes only)", "notice_date": "the 835: the remittance advice's date (DTM*405)", "contractor": "the 835's payer name (N1*PR); CMS marks the box not required", "appellant": "claim (its billing provider, as the provider or supplier)" }, "deadline": { "date": "2027-02-18", "days": 120, "presumed_receipt_days": 5, "counted_from": "receipt of the initial determination", "citation": "42 CFR 405.942(a)", "url": "https://www.ecfr.gov/current/title-42/section-405.942", "late": false, "today": "2026-10-19" }, "where_to_send": "Send it to the Medicare contractor named on the notice, at the address the notice gives, with a copy of the notice and your evidence. Nothing is signed here: the form has no signature box, and the person appealing reviews it before it goes.", "warnings": [], "stored": false, "transmitted": false } ``` | Field | Type | What it is | | --- | --- | --- | | `document` | string | Which document: cms1500, remittance, eligibility, cms-20027 or cms-20033. | | `content_type` | the value "application/pdf" | | | `filename` | string | A name to save it under. | | `pages` | integer | | | `bytes` | integer | The PDF’s size. | | `sha256` | string | The PDF’s SHA-256, in hex. | | `pdf_base64` | string | The PDF, base64. The examples here show only its start. | | `notice` | string | Printed on every page Payerworks draws and in the file’s subject: the document is yours, nothing was sent and no copy was kept. | | `stored` | the value false | | | `transmitted` | the value false | Payerworks drew the document and sent it nowhere. | | `form` | object | | | `claim` | object | | | `filled` | object | Each field typed into the form, by name. | | `filled_from` | object | Where each filled value came from. | | `deadline` | object or null | | | `where_to_send` | string | | | `warnings` | list of FieldProblem | | ### POST /v1/attachments/275 **Write a 275 attachment.** A claim’s attachments as an X12 275 (005010X210): each file (PDF, TIFF, JPEG, PNG or a CDA document, up to ten and 1.4 MB in all) base64 in its own BIN, under the control number the claim’s PWK segment announced with transmission EL, so the payer can match the two; a control number the claim does not announce is refused. A control number is 2 to 50 letters, digits, dots, dashes or underscores, the same in the claim’s PWK06 and the 275’s TRN02. Written as public payer companion guides show the 275, not from the licensed implementation guide, and the answer says so: check your payer’s own. A test key writes test files only. Names an attachment’s LOINC document type when you give one. A solicited 275 answers a payer’s request: send `request` with the request’s trace, and each attachment may echo its own requested code (stc01) and name its service line (line_control_number); POST /v1/attachments/requests/explain gives every value from the request. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/attachments/275" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postAttachments275(body); ``` With the Python client ```python answer = pw.post_attachments_275(body) ``` request.json ```json { "sender_id": "SAMPLEBILLER", "receiver_id": "99999", "control_number": 7, "claim": { "tradingPartnerServiceId": "99999", "submitter": { "organizationName": "Sample Family Medicine", "contactInformation": { "name": "Billing Office", "phoneNumber": "5555550100" } }, "receiver": { "organizationName": "Sample Health Plan" }, "billing": { "npi": "1234567893", "employerId": "123456789", "organizationName": "Sample Family Medicine", "taxonomyCode": "207Q00000X", "address": { "address1": "100 Main Street", "city": "Springfield", "state": "IL", "postalCode": "627011234" } }, "subscriber": { "memberId": "W123456789", "paymentResponsibilityLevelCode": "P", "firstName": "Sample", "lastName": "Patient", "gender": "F", "dateOfBirth": "19800214", "address": { "address1": "9 Elm Street", "city": "Springfield", "state": "IL", "postalCode": "62701" } }, "claimInformation": { "claimFilingCode": "CI", "patientControlNumber": "PW-2001", "claimChargeAmount": "215.00", "placeOfServiceCode": "11", "claimFrequencyCode": "1", "signatureIndicator": "Y", "planParticipationCode": "A", "benefitsAssignmentCertificationIndicator": "Y", "releaseInformationCode": "Y", "healthCareCodeInformation": [ { "diagnosisTypeCode": "ABK", "diagnosisCode": "J029" }, { "diagnosisTypeCode": "ABF", "diagnosisCode": "R509" } ], "serviceLines": [ { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "99213", "lineItemChargeAmount": "150.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1", "2" ] } } }, { "serviceDate": "20261001", "professionalService": { "procedureIdentifier": "HC", "procedureCode": "87880", "lineItemChargeAmount": "65.00", "measurementUnit": "UN", "serviceUnitCount": "1", "compositeDiagnosisCodePointers": { "diagnosisCodePointers": [ "1" ] } } } ], "claimSupplementalInformation": { "reportInformations": [ { "attachmentReportTypeCode": "09", "attachmentTransmissionCode": "EL", "attachmentControlNumber": "PWATT0001" } ] } } }, "attachments": [ { "control_number": "PWATT0001", "content_type": "application/pdf", "content_base64": "JVBERi0xLjQKJSBhbiBpbnZlbnRlZCBhdHRhY2htZW50CjEgMCBvYmo8PD4+ZW5kb2JqCnRyYWlsZXI8PD4+CiUlRU9GCg==", "filename": "progress note.pdf", "loinc": "11506-3" } ] } ``` The answer (200) ```json { "version": "005010X210", "usage": "T", "solicited": false, "x12": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*99999 *261019*1500*^*00501*000000007*0*T*:~GS*PI*SAMPLEBILLER*99999*20261019*1500*7*X*005010X210~ST*275*0001*005010X210~BGN*02*PW-2001*20261019~NM1*PR*2*Sample Health Plan*****P…", "interchange_control_number": "000000007", "group_control_number": "7", "transaction_set_control_number": "0001", "bgn02": "PW-2001", "segments": 23, "attachments": [ { "control_number": "PWATT0001", "trn02": "PWATT0001", "content_type": "application/pdf", "format_code": "IA", "filename": "progress_note.pdf", "bytes": 70, "loinc": { "code": "11506-3", "valid": true, "known": true, "long_common_name": "Progress Note", "short_name": "Prog Note", "label_source": "loinc", "notice": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http:/…" } } ], "warnings": [], "shape": { "verified": false, "words": "Written as the public companion guides of the VA, Texas Medicaid and CMS's esMD profile show a 275; the ASC X12 TR3 for 005010X210 was not read. Check the payer's own companion guide (some ask for CAT02 MB for every file, and some take an u…" }, "limits": { "attachments": 10, "decoded_bytes": 1400000 }, "loinc_notice": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http:/…", "transmitted": false } ``` Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json). | Field | Type | What it is | | --- | --- | --- | | `version` | the value "005010X210" | | | `usage` | one of "T", "P" | | | `solicited` | boolean | | | `x12` | string | The whole interchange. | | `interchange_control_number` | string | | | `group_control_number` | string | | | `transaction_set_control_number` | string | | | `bgn02` | string | | | `segments` | integer | | | `attachments` | list of object | | | `warnings` | list of FieldProblem | | | `shape` | object | | | `limits` | object | | | `loinc_notice` | string | LOINC’s notice, carried with any answer that names a LOINC code. | | `transmitted` | the value false | Payerworks wrote the file and sent it nowhere. | ### POST /v1/attachments/requests/explain **Read a request for more information.** A payer’s 277 request for additional information (005010X213) said claim by claim: what it asks for (each LOINC code it names, in LOINC’s own words, or said as a code Payerworks has no words for), about which claim and which service line, by when against your own today, and the solicited 275 that answers it: the payer’s trace, the claim’s REF*EJ, the submitter id, the payer’s response contact, and a body POST /v1/attachments/275 takes. Read as public sources show the request, not from the licensed implementation guide, and the answer says so. Nothing is stored or sent. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/attachments/requests/explain" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postAttachmentsRequestsExplain(body); ``` With the Python client ```python answer = pw.post_attachments_requests_explain(body) ``` request.json ```json { "x12": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000004*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1500*4*X*005010X213~ST*277*0001*005010X213~BHT*0010*08*PWSANDBOX4*20261019*1500~HL*1**20*1~NM1*PR*2*PAYERWORKS SANDBOX PAYER*****PI*PWSANDBOX~HL*2*1*21*1~NM1*41*2*Sample Sleep Dentistry*****46*SAMPLEBILLER~HL*3*2*19*1~NM1*1P*2*Sample Sleep Dentistry*****XX*1234567893~HL*4*3*PT~NM1*QC*1*Patient*Sample****MI*W12345RFAI~TRN*1*PWR3503656727~STC*R4:11506-3::LOI*20261019~REF*1K*PWS1325701407~REF*EJ*PW-SBX-RFAI~DTP*472*D8*20261001~DTP*106*D8*20261118~SE*17*0001~GE*1*4~IEA*1*000000004~", "today": "2026-10-19" } ``` The answer (200) ```json { "kind": "277RFAI", "version": "005010X213", "usage": "T", "created": "2026-10-19", "reference": "PWSANDBOX4", "today": "2026-10-19", "claims": [ { "index": 0, "trace": "PWR3503656727", "trace_type": "1", "payer": { "name": "PAYERWORKS SANDBOX PAYER", "id": "PWSANDBOX" }, "receiver": { "name": "Sample Sleep Dentistry", "id": "SAMPLEBILLER", "id_qualifier": "46" }, "provider": { "entity": "1P", "name": "Sample Sleep Dentistry", "first_name": null, "id_qualifier": "XX", "id": "1234567893" }, "patient": { "entity": "QC", "last_name": "Patient", "first_name": "Sample", "id_qualifier": "MI", "id": "W12345RFAI" }, "payer_claim_number": "PWS1325701407", "patient_control_number": "PW-SBX-RFAI", "service_date": "2026-10-01", "service_date_end": null, "references": [ { "qualifier": "1K", "value": "PWS1325701407", "words": "the payer's claim control number" }, { "qualifier": "EJ", "value": "PW-SBX-RFAI", "words": "the patient control number (the claim's CLM01)" } ], "dates": [ { "qualifier": "472", "format": "D8", "value": "20261001", "words": "the date of service" }, { "qualifier": "106", "format": "D8", "value": "20261118", "words": "the day the payer needs the information by" } ], "due": { "date": "2026-11-18", "source": "DTP*106", "days_left": 30, "overdue": false, "words": "Due by 11/18/2026, in 30 days." }, "requests": [ { "level": "claim", "line_index": null, "element": "STC01", "written": "R4:11506-3::LOI", "category": { "code": "R4", "words": "held for supporting documentation", "known": true }, "loinc": { "code": "11506-3", "valid": true, "known": true, "long_common_name": "Progress Note", "short_name": "Prog Note", "label_source": "loinc", "notice": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http:/…" }, "code": "11506-3", "code_is_loinc": true, "entity": null, "code_list_qualifier": "LOI", "effective_date": "2026-10-19", "words": "The payer asks for the Progress Note (LOINC 11506-3) about the claim: the claim is held for supporting documentation." } ], "lines": [], "response_contact": null, "payer_contact": null, "response_275": { "bgn01": "11", "trn01": "2", "trn02": "PWR3503656727", "ref_ej": "PW-SBX-RFAI", "submitter_id": "SAMPLEBILLER", "payer": { "name": "PAYERWORKS SANDBOX PAYER", "id": "PWSANDBOX" }, "payer_contact": null, "provider": { "entity": "1P", "name": "Sample Sleep Dentistry", "first_name": null, "id_qualifier": "XX", "id": "1234567893" }, "patient": { "last_name": "Patient", "first_name": "Sample", "member_id": "W12345RFAI" }, "request": { "trace": "PWR3503656727", "stc01": "R4:11506-3::LOI", "patient_control_number": "PW-SBX-RFAI", "submitter_id": "SAMPLEBILLER" }, "attachments": [ { "control_number": "ATT1", "stc01": "R4:11506-3::LOI", "loinc": "11506-3", "document": "Progress Note", "content_type": null, "content_base64": null } ], "sender_id": "SAMPLEBILLER", "receiver_id": "PWSANDBOX", "cannot_answer": [], "words": "Send a solicited 275 (BGN01 11) under the payer's trace PWR3503656727 (TRN01 2, the same TRN02 on every attachment), as submitter SAMPLEBILLER, with REF*EJ PW-SBX-RFAI, and one attachment for each code asked, each echoing the request's STC …" }, "words": "One request about the claim PW-SBX-RFAI. Due by 11/18/2026, in 30 days." } ], "requests": 1, "shape": { "verified": false, "words": "Read as public sources show a 277 request for additional information (005010X213): X12's interpretation 2045 (the LOINC code in STC01, STC10 and STC11), HL7's Da Vinci attachment mapping (the payer's trace in the claim's TRN, the deadline a…" }, "loinc_notice": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http:/…", "today_source": "today", "reads": "Only the file sent in this call: nothing is stored, and no payer is asked." } ``` Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json). | Field | Type | What it is | | --- | --- | --- | | `kind` | the value "277RFAI" | | | `version` | string | | | `usage` | string or null | | | `created` | string or null | YYYY-MM-DD, or empty when not stated. | | `reference` | string or null | | | `today` | string | YYYY-MM-DD, or empty when not stated. | | `claims` | list of object | | | `requests` | integer | | | `shape` | object | | | `loinc_notice` | string | | | `today_source` | string | | | `reads` | string | | ### POST /v1/attachments/requests/check **Check a 275 against its request.** A solicited 275 (or up to ten) held to the 277 request it answers before you send it: BGN01 11, the payer’s trace on every attachment, the request’s REF*EJ and submitter id, every code asked for answered by an attachment echoing its STC, each file’s BIN length, and the due day. Errors and warnings per 275 set, and per claim whether every code is answered: a set with an error of its own answers no code, what is missing is read across every 275 sent, and a line’s request is answered only by an attachment carrying that line’s REF*FJ. Nothing is stored or sent. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/attachments/requests/check" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postAttachmentsRequestsCheck(body); ``` With the Python client ```python answer = pw.post_attachments_requests_check(body) ``` request.json ```json { "x12": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000004*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1500*4*X*005010X213~ST*277*0001*005010X213~BHT*0010*08*PWSANDBOX4*20261019*1500~HL*1**20*1~NM1*PR*2*PAYERWORKS SANDBOX PAYER*****PI*PWSANDBOX~HL*2*1*21*1~NM1*41*2*Sample Sleep Dentistry*****46*SAMPLEBILLER~HL*3*2*19*1~NM1*1P*2*Sample Sleep Dentistry*****XX*1234567893~HL*4*3*PT~NM1*QC*1*Patient*Sample****MI*W12345RFAI~TRN*1*PWR3503656727~STC*R4:11506-3::LOI*20261019~REF*1K*PWS1325701407~REF*EJ*PW-SBX-RFAI~DTP*472*D8*20261001~DTP*106*D8*20261118~SE*17*0001~GE*1*4~IEA*1*000000004~", "x12_275": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*PWSANDBOX *261019*1500*^*00501*000000008*0*T*:~GS*PI*SAMPLEBILLER*PWSANDBOX*20261019*1500*8*X*005010X210~ST*275*0001*005010X210~BGN*11*PW-SBX-RFAI*20261019~NM1*PR*2*PAYERWORKS SANDBOX PAYER*****PI*PWSANDBOX~NM1*41*2*Sample Sleep Dentistry*****46*SAMPLEBILLER~NM1*1P*2*Sample Sleep Dentistry*****XX*1234567893~PRV*BI*PXC*1223S0112X~NX1*1P~N3*100 Main Street~N4*Springfield*IL*627011234~NM1*QC*1*Patient*Sample****MI*W12345RFAI~REF*EJ*PW-SBX-RFAI~DTP*472*D8*20261001~LX*1~TRN*2*PWR3503656727~STC*R4:11506-3::LOI~DTP*368*D8*20261019~CAT*AE*IA~EFI*05~BIN*246*Mime-Version: 1.0\r\nContent-Type: application/pdf\r\nContent-Transfer-Encoding: base64\r\nContent-Disposition: attachment; filename=progress_note.pdf\r\n\r\nJVBERi0xLjQKJSBhbiBpbnZlbnRlZCBhdHRhY2htZW50CjEgMCBvYmo8PD4+ZW5kb2JqCnRyYWls\r\nZXI8PD4+CiUlRU9GCg==~SE*20*0001~GE*1*8~IEA*1*000000008~", "today": "2026-10-19" } ``` The answer (200) ```json { "kind": "277RFAI", "today": "2026-10-19", "today_source": "today", "answers_every_request": true, "claims": [ { "index": 0, "trace": "PWR3503656727", "patient_control_number": "PW-SBX-RFAI", "asked": [ "11506-3" ], "answered": [ "11506-3" ], "missing": [], "missing_requests": [], "answered_by": [ { "file": 0, "set": 0, "answers": true } ], "complete": true, "words": "Every code asked for is answered." } ], "files": [ { "file": "x12_275", "sets": [ { "index": 0, "st_control": "0001", "trace": "PWR3503656727", "claim_index": 0, "answers": true, "errors": [], "warnings": [] } ] } ], "shape": { "verified": false, "words": "Read as public sources show a 277 request for additional information (005010X213): X12's interpretation 2045 (the LOINC code in STC01, STC10 and STC11), HL7's Da Vinci attachment mapping (the payer's trace in the claim's TRN, the deadline a…" }, "loinc_notice": "This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http:/…", "reads": "Only the files sent in this call: nothing is stored, nothing is sent, and no payer is asked." } ``` Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json). | Field | Type | What it is | | --- | --- | --- | | `kind` | the value "277RFAI" | | | `today` | string | YYYY-MM-DD, or empty when not stated. | | `today_source` | string | | | `answers_every_request` | boolean | | | `claims` | list of object | | | `files` | list of object | | | `shape` | object | | | `reads` | string | | | `loinc_notice` | string | LOINC’s notice, whenever the answer names a LOINC code. | ### POST /v1/remittances/from-image **Read a paper EOB into a draft 835.** A photo, scan or PDF of a payer’s paper explanation of benefits (two pages at most, 1.4 MB), read by a model into a DRAFT: every figure, date and code with the reader’s confidence and where on the page it was read, the payments checked by arithmetic against the check total the page states, and an 835 written as a test file. It is never an ERA and nothing is posted: check every field against the paper. Off until Payerworks turns it on; test keys and invented documents only for now, at most 100 reads a UTC day for an account’s keys together; a call refused for the route being off, a live key or no file is not counted. A read has 25 seconds; past them the answer is 504 model_read_timed_out: send one page, or a crop of the part you need. Nothing is kept. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/remittances/from-image" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postRemittancesFromImage(body); ``` With the Python client ```python answer = pw.post_remittances_from_image(body) ``` request.json ```json { "file_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAAAoCAAAAABrpaM1AAAAJElEQVR4nGOYSSFgGDVg1IBRA0YNGDVg1IBRA0YNGDVgOBoAAFl9+kzmtZbEAAAAAElFTkSuQmCC" } ``` The answer (200) ```json { "object": "remittance_draft", "draft": true, "needs_review": true, "is_era": false, "posted": false, "words": "A draft read from a picture of a paper explanation of benefits by a model. It is not an ERA, it was not sent by the payer, and nothing has been posted: check every field against the paper before you use it.", "confidence_words": "confidence is the reader's own estimate from 0 to 1, not a measured accuracy.", "region_words": "region is where on the page the reader placed the value: page (1 is the first) and a box as fractions of the page's width and height from its top left. It is approximate, and null where the reader read a PDF's text rather than its picture.", "document": { "media_type": "image/png", "pages": 1, "read_as": "picture" }, "payer": { "name": { "value": "SAMPLE HEALTH PLAN", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } }, "payee": { "name": { "value": "Sample Family Medicine", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "npi": { "value": "1234567893", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "tax_id": { "value": "12-3456789", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } }, "check": { "number": { "value": "CHK10001", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "date": { "value": "2026-10-01", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "total": { "value": 150, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "method": { "value": "Check", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } }, "claims": [ { "patient_name": { "value": "PATIENT, SAMPLE", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "member_id": { "value": "W123456789", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "patient_control_number": { "value": "PW-2001", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "payer_claim_number": { "value": "PCN000123", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "status": { "value": "processed_as_primary", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "billed": { "value": 215, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "allowed": { "value": 150, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "paid": { "value": 120, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "patient_responsibility": { "value": 30, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "service_from": { "value": null, "confidence": null, "region": null, "not_printed": true }, "service_to": { "value": null, "confidence": null, "region": null, "not_printed": true }, "adjustments": [], "lines": [ { "date": { "value": "2026-10-01", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "procedure_code": { "value": "99213", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "modifiers": { "value": null, "confidence": null, "region": null, "not_printed": true }, "units": { "value": 1, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "billed": { "value": 150, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "allowed": { "value": 150, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "paid": { "value": 120, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "adjustments": [ { "group": { "value": "PR", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "reason": { "value": "2", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "amount": { "value": 30, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } } ], "remarks": { "value": null, "confidence": null, "region": null, "not_printed": true } }, { "date": { "value": "2026-10-01", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "procedure_code": { "value": "87880", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "modifiers": { "value": null, "confidence": null, "region": null, "not_printed": true }, "units": { "value": 1, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "billed": { "value": 65, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "allowed": { "value": 0, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "paid": { "value": 0, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "adjustments": [ { "group": { "value": "CO", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "reason": { "value": "97", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "amount": { "value": 65, "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } } ], "remarks": { "value": "N130", "confidence": 0.62, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } } ] } ], "provider_adjustments": [], "totals": { "check_total_stated": 150, "claims_paid": 120, "provider_adjustments": 0, "check_total_computed": 120, "matches": false, "words": "The claims as read do NOT add up to the check total the page states." }, "warnings": [ { "code": "check_total_mismatch", "path": "check.total", "message": "The page states a check total of $150.00, and the claims as read come to $120.00: a difference of $30.00. Something was misread or not read: check every payment against the paper.", "stated": 150, "computed": 120 } ], "review": [ "claims[0].lines[1].remarks", "check.total" ], "x12": { "version": "005010X221A1", "usage": "T", "text": "ISA*00* *00* *ZZ*PWDRAFT *ZZ*PWDRAFT *261019*1500*^*00501*000000001*0*T*:~GS*HP*PWDRAFT*PWDRAFT*20261019*1500*1*X*005010X221A1~ST*835*0001~BPR*I*150*C*CHK************20261001~TRN*1*CHK10001~DTM*405*20261001~N…", "reads_back": true, "not_read": [ { "path": "payer", "element": "TRN03" }, { "path": "claims[0]", "element": "CLP06" } ], "words": "A test interchange (ISA15 T) whatever your key: a draft to check against the paper, never a payer's file. Elements the page did not give are left empty and listed in not_read." }, "mode": "test", "stored": false, "transmitted": false } ``` Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json). | Field | Type | What it is | | --- | --- | --- | | `object` | the value "remittance_draft" | | | `draft` | the value true | | | `needs_review` | the value true | | | `is_era` | the value false | Never an ERA: the payer did not send it. | | `posted` | the value false | Nothing was posted. | | `words` | string | | | `confidence_words` | string | | | `region_words` | string | | | `document` | object | | | `payer` | object | | | `payee` | object | | | `check` | object | | | `claims` | list of object | At most 25 claims and 100 service lines. | | `provider_adjustments` | list of object | | | `totals` | object | The arithmetic, never the model’s: the claims’ payments less the provider adjustments against the check total the page states. | | `warnings` | list of object | | | `review` | list of string | Every path to check first: a value read below 0.8 confidence, a value not read as its kind, and every path a warning names. | | `x12` | object | | | `mode` | one of "test", "live" | | | `stored` | the value false | | | `transmitted` | the value false | | ### POST /v1/payers/from-card **Look up a payer from a card photo.** A photo of an insurance card’s front (and back, if you have it), read twice by a model for the payer’s name, the member ID and its shape, the group number and the plan type the card itself states, and the payer looked up in the Payerworks payer directory. A match means the directory holds published facts about that payer, never that a claim can be sent to it; an electronic payer ID printed on the card is shown only where the payer publishes it. Off until Payerworks turns it on; test keys and invented cards only for now, at most 100 reads a UTC day for an account’s keys together; a call refused for the route being off, a live key or no file is not counted. A read has 25 seconds; past them the answer is 504 model_read_timed_out: send one page, or a crop of the part you need. Nothing is kept. Request ```bash curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/payers/from-card" \ -H "Authorization: Bearer $PAYERWORKS_API_KEY" \ -H "Content-Type: application/json" \ -d @request.json ``` With the JavaScript client ```js const answer = await pw.postPayersFromCard(body); ``` With the Python client ```python answer = pw.post_payers_from_card(body) ``` request.json ```json { "front_base64": "iVBORw0KGgoAAAANSUhEUgAAAEAAAAAoCAAAAABrpaM1AAAAJElEQVR4nGOYSSFgGDVg1IBRA0YNGDVg1IBRA0YNGDVgOBoAAFl9+kzmtZbEAAAAAElFTkSuQmCC" } ``` The answer (200) ```json { "object": "card_lookup", "needs_review": true, "words": "Read from a photo of an insurance card by a model, and matched by name against the Payerworks payer directory. A match says the directory holds published facts about that payer, never that a claim can be sent to it.", "confidence_words": "confidence is the reader's own estimate from 0 to 1, not a measured accuracy.", "region_words": "region is where the reader placed the value: page 1 is the front photo, 2 the back; a box as fractions of that photo from its top left. It is approximate.", "files": [ { "field": "front_base64", "media_type": "image/png", "pages": 1 } ], "payer_name": { "value": "Aetna", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "plan_name": { "value": null, "confidence": null, "region": null, "not_printed": true }, "member_id": { "value": "W123456789", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] }, "reads": "agreed", "other_readings": [], "shape": { "length": 10, "pattern": "A999999999", "letters": 1, "digits": 9, "leading_letters": "W", "mbi_format": false, "words": "It does not have the form of a Medicare Beneficiary Identifier." } }, "group_number": { "value": "0123456", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } }, "plan_type": { "stated": "ppo", "words": { "value": "PPO", "confidence": 0.97, "region": { "page": 1, "box": [ 0.1, 0.2 ] } } }, "printed_payer_id": { "printed": true, "published": true, "value": "60054", "words": "The card prints this electronic payer ID, and a directory row lists it as an ID the payer publishes (the row says where and when it was read)." }, "directory": { "available": true, "matched": true, "matches": [ { "id": "pwd_c28e50f685f059ec", "name": "Aetna", "kind": "organization", "states": [], "nationwide": false, "payer_id": null, "payer_id_words": "This payer publishes more than one claims payer ID; each is listed with what it is for.", "published_payer_ids": [ { "payer_id": "60054", "for": "Commercial and Medicare plan claims and encounters", "transactions": [ "claims" ], "source": { "url": "https://www.aetna.com/document-library/healthcare-professionals/assets/documents/eligibility-benefits-claims-information.pdf", "label": "Aetna: where to go for eligibility, benefits and claims", "read_on": "2026-10-19" } }, { "payer_id": "60055", "for": "Bulk encounter files (Aetna asks to be contacted first)", "transactions": [ "encounters" ], "source": { "url": "https://www.aetna.com/document-library/healthcare-professionals/assets/documents/eligibility-benefits-claims-information.pdf", "label": "Aetna: where to go for eligibility, benefits and claims", "read_on": "2026-10-19" } } ], "match": { "by": "payer_id", "exact": true, "payer_id": "60054" }, "connection": "none", "transmits": false }, { "id": "pwd_65862b816a773b41", "name": "Aetna", "kind": "organization", "states": [ "OH" ], "nationwide": false, "payer_id": null, "payer_id_words": "No payer ID published by the payer that Payerworks has read.", "published_payer_ids": [], "match": { "by": "name", "exact": true }, "connection": "none", "transmits": false } ], "words": "Matched in the Payerworks directory: the directory holds published facts about a payer by this name. It is not a list of payers Payerworks can send to, and it does not say a claim can be sent.", "scope": "Payers and plan programs from public federal files; not a list of payers Payerworks can send to; payer IDs only where the payer publishes one.", "payer_ids_are": "A payer ID is shown only where the payer or its Medicare contractor publishes it, with the page and the day it was read. Clearinghouses can route the same payer under other IDs, and Payerworks is connected to no payer yet." }, "warnings": [], "mode": "test", "stored": false, "transmitted": false } ``` Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in [/openapi.json](https://payerworks.com/openapi.json). | Field | Type | What it is | | --- | --- | --- | | `object` | the value "card_lookup" | | | `needs_review` | the value true | | | `words` | string | | | `confidence_words` | string | | | `region_words` | string | | | `files` | list of object | | | `payer_name` | ReadField | | | `plan_name` | ReadField | | | `member_id` | ReadField | | | `group_number` | ReadField | | | `plan_type` | object | | | `printed_payer_id` | object | | | `directory` | object | | | `warnings` | list of object | | | `mode` | one of "test", "live" | | | `stored` | the value false | | | `transmitted` | the value false | | ## Reading the answer - A PDF answer is `pdf_base64`, `sha256` and `bytes`, with `stored: false` and `transmitted: false`. Decode the base64 to get the file. - A 275 answer is the `x12` with `shape.verified: false`: it is written as public payer companion guides show the 275, not from the licensed implementation guide. Check your payer’s own guide. - A request for more information: each claim’s `requests` name what is asked (`known: false` where Payerworks has no words for a code), `due` says by when against your `today`, and `response_275` holds every value the solicited 275 must carry: the payer’s trace on every attachment (`trn02`), the request’s REF*EJ and the submitter id. The request is read as public sources show it (`shape.verified: false`). - A check answers `answers_every_request`, and per claim the codes `asked`, `answered` and `missing` and each request not yet answered (`missing_requests`, a line’s request naming its line), with each 275 set’s errors and warnings by field. A set with an error of its own answers no code, and what is missing is read across every 275 sent, so an answer split across two files counts. - A model read is a draft a person checks: every value with the reader’s confidence and where it was read, totals checked by arithmetic, and `is_era: false`. It has 25 seconds. ## Troubleshooting - `model_read_not_offered` (501): The picture reads are off on this host until Payerworks turns them on. A 501 is never retried by the clients: it will not pass by waiting. - `invalid_attachments` (422): Each attachment is refused with its field, for example a control number the claim does not announce with transmission EL. - `not_medicare_fee_for_service` (422): The appeal forms are Original Medicare’s; the 835 must say the claim is Medicare fee-for-service. - `documents_unavailable` (503): The part that draws PDFs was not loaded: retry in a moment. - `not_an_information_request` (422): The file is not a 277 request for additional information (005010X213): the error names what it is, and the route that reads it. A claim status 277 goes to POST /v1/claim-status/explain. - `no_attachment_response` (400): The check needs the solicited 275 too, as x12_275: the file’s text, or a list of them. - A 275 written under the claim’s own number, not the payer’s trace, goes unmatched and the claim is decided without it: copy `trn02`, the REF*EJ and the submitter id from `response_275`. - `model_read_timed_out` (504): A picture read did not finish in its 25 seconds: send one page, or a crop of the part you need. Every refusal these routes may answer, with its status. Any route may also answer the codes every route shares, on [Every error](https://payerworks.com/docs/errors). | Code | Status | What it means | | --- | --- | --- | | `invalid_document_option` | 400 | An option of this document is not one the route takes: the error names it and what it takes. | | `invalid_image_base64` | 400 | The file is not base64: send the file's bytes base64 encoded (A-Z, a-z, 0-9, + and /, with = padding), with no data: prefix. | | `invalid_information_request_call` | 400 | A field of the request is not in the shape this route takes; each problem is listed with its field. | | `no_attachment_response` | 400 | Send the solicited 275 to check as x12_275: the file's text, or a list of them. | | `no_image` | 400 | Send the file as base64: file_base64 for a paper EOB, front_base64 (and back_base64 if you have it) for an insurance card. | | `no_information_request` | 400 | Send the payer's 277 request for additional information as x12 (the file's text). | | `no_remittance_file` | 400 | Send the 835 as x12 (the file's text). | | `too_many_forms` | 400 | These claims need more CMS-1500 forms than one call draws (200, at six service lines a form): send fewer claims in each call. | | `unknown_appeal_form` | 400 | form is redetermination (CMS-20027) or reconsideration (CMS-20033). | | `model_read_test_keys_only` | 403 | This route answers test keys only, with invented documents, until an agreement covering the model is in place for live data. Use a test key. | | `test_key_production_file` | 403 | A test key writes test interchanges only (ISA15 = T). Use a live key for a production file. | | `image_too_large` | 413 | The file is larger than one call reads: at most 1,400,000 bytes in all, before base64. Send a smaller copy (a lower resolution photo, or fewer pages). | | `too_many_pages` | 413 | The PDF holds more pages than one call reads: the error names the most (limit). Send fewer pages in each call. | | `claim_not_on_remittance` | 422 | The 835 holds no claim payment with this reference (CLP01); send the reference the denying claim payment carries. | | `invalid_appeal_form_input` | 422 | One or more fields cannot be typed into the form; nothing was filled. Each problem is listed with its field. | | `invalid_attachments` | 422 | The 275 cannot be written as asked; nothing was written. Each problem is listed with its field. | | `invalid_claims` | 422 | One or more claims would be refused; nothing was written or run. Each claim's errors are listed. | | `mixed_functional_groups` | 422 | This interchange holds functional groups of different kinds: send each kind in its own interchange, so no part of it goes unread. | | `no_requested_claims` | 422 | This request holds no claim (no TRN in a patient loop), so there is nothing to say or check. | | `not_an_835` | 422 | This is not an 835 remittance. | | `not_an_attachment_response` | 422 | A file sent as x12_275 is not a 275 this route can read: the error names the file and why. | | `not_an_eob` | 422 | The reader did not see a payer's explanation of benefits or remittance advice in this file, so no draft was written. | | `not_an_information_request` | 422 | This file is not a 277 request for additional information (005010X213): the error names what it is, and the route that reads it. | | `not_an_insurance_card` | 422 | The reader did not see a health insurance card in this file, so nothing was looked up. | | `not_medicare_fee_for_service` | 422 | These are Original Medicare's forms, and the 835 says this claim is not Medicare fee-for-service (CLP06 is not MA or MB): use the plan's own appeal, or POST /v1/appeals/letter. | | `unreadable_image` | 422 | The file could not be read as a picture or a PDF; the error says why (reason) and what to send instead. | | `model_read_daily_limit` | 429 | This account's keys have made the most model-read calls an account may make on this route today (100 a UTC day, its keys together). Try again tomorrow. | | `model_read_not_offered` | 501 | Reading a document with a model is not offered on this host: Payerworks turns it on route by route. This is not a passing fault, so sending the request again answers the same. | | `model_read_failed` | 502 | The reader gave no usable answer for this file, so nothing is answered from it. Send a clearer copy, or try again. | | `documents_unavailable` | 503 | The PDF could not be drawn just now: the part of the API that draws it is not loaded. Retry in a moment. The engine run on its own, in a browser or a test, draws no PDF; the hosted Payerworks API, at the base URL shown with your key, does. | | `form_asset_changed` | 503 | The form file on our side is not the one CMS published that we pinned, so nothing was filled. This is ours to fix. | | `model_read_unavailable` | 503 | The document reader could not be loaded just now, so nothing was read. Retry in a moment. The engine run on its own, in a browser or a test, has no reader; the hosted Payerworks API does. | | `model_read_timed_out` | 504 | The read did not finish inside one call's time. Send less: one page, or a crop of the part you need. | ## Code lists ### LOINC This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc. ## Example [documents.mjs](https://payerworks.com/docs/examples/documents.mjs) runs every step below against the API with a test key. It needs [payerworks.mjs](https://payerworks.com/sdk/payerworks.mjs) and [sample-data.mjs](https://payerworks.com/docs/examples/sample-data.mjs) beside it. documents.mjs ```js // Payerworks example: documents, a CMS-1500 drawn and a 275 written. Docs: https://payerworks.com/docs/documents // // Run it with Node 18 or later, with the JavaScript client (https://payerworks.com/sdk/payerworks.mjs) // and sample-data.mjs beside this file: // PAYERWORKS_API_KEY=pw_test_... PAYERWORKS_BASE_URL= node documents.mjs // A test key and invented data only. Payerworks sends nothing to a payer: every file it writes is yours. import { pathToFileURL } from 'node:url'; import { Payerworks, PayerworksError } from './payerworks.mjs'; import { CLAIM, ELIGIBILITY_QUESTION, copy, refusalOf } from './sample-data.mjs'; /** @param {Payerworks} pw */ export async function run(pw) { // 1. The claim drawn on the CMS-1500, after the same checks the 837P route makes. The PDF comes back as base64. const form = await pw.postClaimsCms1500({ claim: copy(CLAIM), form: 'full', signed_on: '2026-10-20' }); const pdf = Buffer.from(form.pdf_base64, 'base64'); // 2. An eligibility answer printed: the sandbox's 271, as POST /v1/eligibility/explain reads it. const sandbox = await pw.postSandboxEligibility({ request: copy(ELIGIBILITY_QUESTION) }); const summary = await pw.postEligibilityPdf({ x12: sandbox.files.eligibility_271 }); // 3. The failure path: reading a paper EOB with a model is built and switched off until Payerworks // turns it on. A 501 will not pass by waiting, so the clients never retry it. const off = await refusalOf(() => pw.postRemittancesFromImage({ file_base64: 'iVBORw0KGgo=' }), { PayerworksError }); return { cms1500: { starts: pdf.subarray(0, 5).toString('latin1'), sha256: form.sha256.length, stored: form.stored, transmitted: form.transmitted }, eligibility_pdf: summary.pdf_base64.startsWith('JVBERi0'), off, }; } // Run as a script: node , with PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL set. if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { console.log(JSON.stringify(await run(new Payerworks()), null, 2)); } ``` What it answered, run against the API in Payerworks’ own tests (your request ids will differ) ```json { "cms1500": { "starts": "%PDF-", "sha256": 64, "stored": false, "transmitted": false }, "eligibility_pdf": true, "off": { "status": 501, "code": "model_read_not_offered", "request_id": "req_4" } } ```