Documents: CMS-1500, remittance PDFs and 275s

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.

Routes

POST/v1/claims/cms1500Draw claims on the CMS-1500
POST/v1/remittances/pdfPrint a remittance
POST/v1/eligibility/pdfPrint an eligibility answer
POST/v1/appeals/formFill a Medicare appeal form
POST/v1/attachments/275Write a 275 attachment
POST/v1/attachments/requests/explainRead a request for more information
POST/v1/attachments/requests/checkCheck a 275 against its request
POST/v1/remittances/from-imageRead a paper EOB into a draft 835
POST/v1/payers/from-cardLook 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

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

const answer = await pw.postClaimsCms1500(body);

With the Python client

answer = pw.post_claims_cms1500(body)

request.jsonJSON

{
  "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
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

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

const answer = await pw.postRemittancesPdf(body);

With the Python client

answer = pw.post_remittances_pdf(body)

request.jsonJSON

{
  "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
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

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

const answer = await pw.postEligibilityPdf(body);

With the Python client

answer = pw.post_eligibility_pdf(body)

request.jsonJSON

{
  "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
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

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

const answer = await pw.postAppealsForm(body);

With the Python client

answer = pw.post_appeals_form(body)

request.jsonJSON

{
  "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
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

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

const answer = await pw.postAttachments275(body);

With the Python client

answer = pw.post_attachments_275(body)

request.jsonJSON

{
  "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.

Field, Type, What it is
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

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

const answer = await pw.postAttachmentsRequestsExplain(body);

With the Python client

answer = pw.post_attachments_requests_explain(body)

request.jsonJSON

{
  "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.

Field, Type, What it is
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

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

const answer = await pw.postAttachmentsRequestsCheck(body);

With the Python client

answer = pw.post_attachments_requests_check(body)

request.jsonJSON

{
  "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.

Field, Type, What it is
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

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

const answer = await pw.postRemittancesFromImage(body);

With the Python client

answer = pw.post_remittances_from_image(body)

request.jsonJSON

{
  "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.

Field, Type, What it is
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

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

const answer = await pw.postPayersFromCard(body);

With the Python client

answer = pw.post_payers_from_card(body)

request.jsonJSON

{
  "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.

Field, Type, What it is
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.

Code, Status, What it means
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 runs every step below against the API with a test key. It needs payerworks.mjs and sample-data.mjs beside it.

documents.mjsJavaScript

// 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=<the base URL shown with your key> 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 <this file>, 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"
  }
}

Documents and attachments

Routes

POST`/v1/claims/cms1500`

POST`/v1/remittances/pdf`

POST`/v1/eligibility/pdf`

POST`/v1/appeals/form`

POST`/v1/attachments/275`

POST`/v1/attachments/requests/explain`

POST`/v1/attachments/requests/check`

POST`/v1/remittances/from-image`

POST`/v1/payers/from-card`

Reading the answer

Troubleshooting

Code lists

LOINC

Example

What happens next

Talk to Payerworks

Documents and attachments

Routes

POST/v1/claims/cms1500

POST/v1/remittances/pdf

POST/v1/eligibility/pdf

POST/v1/appeals/form

POST/v1/attachments/275

POST/v1/attachments/requests/explain

POST/v1/attachments/requests/check

POST/v1/remittances/from-image

POST/v1/payers/from-card

Reading the answer

Troubleshooting

Code lists

LOINC

Example

What happens next

Talk to Payerworks

POST`/v1/claims/cms1500`

POST`/v1/remittances/pdf`

POST`/v1/eligibility/pdf`

POST`/v1/appeals/form`

POST`/v1/attachments/275`

POST`/v1/attachments/requests/explain`

POST`/v1/attachments/requests/check`

POST`/v1/remittances/from-image`

POST`/v1/payers/from-card`