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.
A claim is JSON in the 837P’s own structure: submitter, receiver, billing, subscriber, the providers, and claimInformation with its service lines. POST /v1/claims/validate checks it the way a payer’s front end would, against one published edit table (GET /v1/edits), and lists every reason it would be refused, each with a code, the field’s path and a sentence. POST /v1/claims/837p writes up to one hundred claims as one file, after the same checks; nothing is written when any claim would be refused.
The 837I and 837D routes take the same JSON with the institutional or dental fields. POST /v1/claims/correction-plan says how to replace or void a claim already sent, and POST /v1/x12/parse reads any of these files back to the same JSON.
Before a claim goes anywhere, run it through the sandbox payer: POST /v1/sandbox/claims answers it as a 999, a 277CA and an 835 in one call, each explained, and posts the answers to your webhook as events.
POST /v1/claims/submit is how a live key will send claims once Payerworks has a trading partner for the payer. Payerworks is connected to no payer today, so it answers 501 submit_not_offered with each of its five gates and whether it is open, and nothing is written or sent. GET /v1/partners lists the partners it sends to, and is empty today.
New here? Start with A sandbox claim, to its 835.
Routes
- POST
/v1/claims/validateValidate claims - POST
/v1/claims/837pWrite an 837P - POST
/v1/claims/837iWrite an 837I - POST
/v1/claims/837i/validateValidate institutional claims - POST
/v1/claims/837dWrite an 837D - POST
/v1/claims/837d/validateValidate dental claims - POST
/v1/claims/correction-planPlan a corrected or void claim - GET
/v1/editsEvery claim edit - GET
/v1/edits/{code}One claim edit - POST
/v1/edits/rules/checkCheck your own claim rules - POST
/v1/x12/parseRead an X12 file - POST
/v1/sandbox/claimsRun the sandbox payer - POST
/v1/sandbox/claims/837iRun the sandbox payer on an 837I - POST
/v1/sandbox/claims/837dRun the sandbox payer on an 837D - POST
/v1/sandbox/claims/timelineRun the sandbox over days - POST
/v1/claims/submitSend claims to a payer - GET
/v1/partnersTrading partners
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/validate
Validate claims
Every reason a claim would be refused at the front door or by a payer’s first edit, each with a code, the field’s path and a sentence, from the one edit table GET /v1/edits lists: the NPIs’ check digits, the dates, the pointers, a total that must equal its lines, the filing indicator, a character X12 reserves, and each diagnosis, HCPCS Level II code and modifier against the release in force on its date of service (the ICD-10 diagnosis releases for fiscal 2025 to 2027, CMS’s HCPCS file from January 2025) and the place of service against CMS’s list. A CPT code is checked for its shape only, and a dental D code or a CPT modifier, which CMS’s file does not carry, is listed as not checked. Every claim carries what the guides require: the submitter’s contact, the billing provider’s tax id, the patient’s address and date of birth, a facility’s address when one is sent, and the filing indicator. Formatting is repaired first, on a copy, and each claim lists its repairs (phone punctuation, a ZIP+4 hyphen, letter case, a diagnosis code’s dot, spaces) and not_checked, every check that could not run and why. For a claim to a later payer: the payers’ order, each earlier payer’s paid amount, claim and line balance, the adjudication date and the patient’s remaining share each at one level, the adjustment groups, the Medicare secondary payer type, and remark codes in force on the day; when Medicare is the later payer, the claim’s total equals each earlier payer’s paid amount plus all its adjustments, and a claim to Medicare is an original claim (frequency 1). Send the claims as JSON, or an 837P file as x12, read back claim by claim. Send your own rules beside them as rules, written as POST /v1/edits/rules/check reads them, and each is applied to every claim after its repairs: a rule that fires is listed as caller_rule with source caller, and one of severity error makes the claim invalid like any other error. Passing means the claim is well formed, not that a payer will pay it.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/validate" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaimsValidate(body);With the Python client
answer = pw.post_claims_validate(body){
"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"
]
}
}
}
]
}
}
}{
"valid": true,
"claims": [
{
"index": 0,
"reference": "PW-2001",
"errors": [],
"warnings": [],
"repairs": [],
"not_checked": []
}
]
}| Field | Type | What it is |
|---|---|---|
valid | boolean | True when no claim has an error. |
claims | list of ClaimChecks |
POST/v1/claims/837p
Write an 837P
Up to one hundred claims written as one 005010X222A1 interchange under your sender and receiver ids and your control number, a claim to a secondary or tertiary payer included: send each earlier payer’s adjudication (otherSubscriberInformation, and lineAdjudicationInformation on each line it paid) and the file carries the coordination of benefits loops. Every claim is checked as POST /v1/claims/validate checks it, your own rules included when you send them as rules, and written from its repaired copy; each claim’s answer lists its repairs, what was not checked, and a not_written warning for any field the 837P has no element for. Nothing is written if any claim would be refused. A test key writes test files only.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/837p" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaims837p(body);With the Python client
answer = pw.post_claims_837p(body){
"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"
]
}
}
}
]
}
},
"sender_id": "SAMPLEBILLER",
"receiver_id": "99999",
"control_number": 7
}{
"version": "005010X222A1",
"usage": "T",
"x12": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*99999 *261019*1500*^*00501*000000007*0*T*:~GS*HC*SAMPLEBILLER*99999*20261019*1500*7*X*005010X222A1~ST*837*0001*005010X222A1~BHT*0019*00*PW-2001*20261019*1500*CH~NM1*41*2*Sample …",
"interchange_control_number": "000000007",
"group_control_number": "7",
"transaction_set_control_numbers": [
"0001"
],
"segments": 31,
"claims": [
{
"reference": "PW-2001",
"transaction_set_control_number": "0001",
"warnings": [],
"repairs": [],
"not_checked": []
}
],
"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 |
|---|---|---|
version | string | The implementation guide written. |
usage | one of "T", "P" | T or P. |
x12 | string | The whole interchange. |
interchange_control_number | string | |
group_control_number | string | |
transaction_set_control_numbers | list of string | |
segments | integer | |
transmitted | the value false | Payerworks wrote the file and sent it nowhere. |
claims | list of object |
POST/v1/claims/837i
Write an 837I
Up to one hundred institutional claims, the UB-04’s electronic form, written as one 005010X223A2 interchange from the same JSON as the 837P route, with the institutional fields: the facility type and frequency, the statement dates, admission type, source and patient status, revenue code lines, principal and admitting diagnoses with present on admission, procedures, occurrence, span, value and condition codes, and the attending and operating providers. Every claim is checked first, and nothing is written if any would be refused. A revenue code or a type of bill is checked for its shape: the code set’s words belong to the NUBC. A test key writes test files only.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/837i" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaims837i(body);With the Python client
answer = pw.post_claims_837i(body){
"claim": {
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Community Hospital",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"organizationName": "Sample Community Hospital",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "282N00000X",
"address": {
"address1": "200 Hospital Drive",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19700101",
"gender": "F",
"groupNumber": "GRP1",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"attending": {
"lastName": "Doctor",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "207R00000X"
},
"claimInformation": {
"patientControlNumber": "PW-3001",
"claimChargeAmount": "1500.50",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"statementBeginDate": "20261001",
"statementEndDate": "20261003",
"admissionDateAndHour": "202610010800",
"dischargeHour": "1400"
},
"claimCodeInformation": {
"admissionTypeCode": "1",
"admissionSourceCode": "7",
"patientStatusCode": "01"
},
"principalDiagnosis": {
"qualifierCode": "ABK",
"principalDiagnosisCode": "J18.9",
"presentOnAdmissionIndicator": "Y"
},
"admittingDiagnosis": {
"qualifierCode": "ABJ",
"admittingDiagnosisCode": "R05"
},
"otherDiagnosisInformationList": [
[
{
"qualifierCode": "ABF",
"otherDiagnosisCode": "E119",
"presentOnAdmissionIndicator": "Y"
}
]
],
"serviceLines": [
{
"institutionalService": {
"serviceLineRevenueCode": "0120",
"lineItemChargeAmount": "1000",
"measurementUnit": "DA",
"serviceUnitCount": "2"
},
"serviceDate": "20261001",
"serviceDateEnd": "20261002",
"lineItemControlNumber": "L1"
},
{
"institutionalService": {
"serviceLineRevenueCode": "0300",
"procedureIdentifier": "HC",
"procedureCode": "80053",
"lineItemChargeAmount": "500.50",
"serviceUnitCount": "1"
},
"serviceDate": "20261001",
"lineItemControlNumber": "L2"
}
]
}
},
"sender_id": "SAMPLEBILLER",
"receiver_id": "99999",
"control_number": 8
}{
"kind": "837I",
"version": "005010X223A2",
"usage": "T",
"x12": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*99999 *261019*1500*^*00501*000000008*0*T*:~GS*HC*SAMPLEBILLER*99999*20261019*1500*8*X*005010X223A2~ST*837*0001*005010X223A2~BHT*0019*00*PW-3001*20261019*1500*CH~NM1*41*2*Sample …",
"interchange_control_number": "000000008",
"group_control_number": "8",
"transaction_set_control_numbers": [
"0001"
],
"segments": 41,
"claims": [
{
"reference": "PW-3001",
"transaction_set_control_number": "0001",
"warnings": []
}
],
"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 |
|---|---|---|
version | string | The implementation guide written. |
usage | one of "T", "P" | T or P. |
x12 | string | The whole interchange. |
interchange_control_number | string | |
group_control_number | string | |
transaction_set_control_numbers | list of string | |
segments | integer | |
transmitted | the value false | Payerworks wrote the file and sent it nowhere. |
kind | one of "837I", "837D" | |
claims | list of object |
POST/v1/claims/837i/validate
Validate institutional claims
The same institutional claims checked against the 837I’s rules without writing a file: each problem names its code, its field and a sentence.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/837i/validate" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaims837iValidate(body);With the Python client
answer = pw.post_claims_837i_validate(body){
"claim": {
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Community Hospital",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"organizationName": "Sample Community Hospital",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "282N00000X",
"address": {
"address1": "200 Hospital Drive",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19700101",
"gender": "F",
"groupNumber": "GRP1",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"attending": {
"lastName": "Doctor",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "207R00000X"
},
"claimInformation": {
"patientControlNumber": "PW-3001",
"claimChargeAmount": "1500.50",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"statementBeginDate": "20261001",
"statementEndDate": "20261003",
"admissionDateAndHour": "202610010800",
"dischargeHour": "1400"
},
"claimCodeInformation": {
"admissionTypeCode": "1",
"admissionSourceCode": "7",
"patientStatusCode": "01"
},
"principalDiagnosis": {
"qualifierCode": "ABK",
"principalDiagnosisCode": "J18.9",
"presentOnAdmissionIndicator": "Y"
},
"admittingDiagnosis": {
"qualifierCode": "ABJ",
"admittingDiagnosisCode": "R05"
},
"otherDiagnosisInformationList": [
[
{
"qualifierCode": "ABF",
"otherDiagnosisCode": "E119",
"presentOnAdmissionIndicator": "Y"
}
]
],
"serviceLines": [
{
"institutionalService": {
"serviceLineRevenueCode": "0120",
"lineItemChargeAmount": "1000",
"measurementUnit": "DA",
"serviceUnitCount": "2"
},
"serviceDate": "20261001",
"serviceDateEnd": "20261002",
"lineItemControlNumber": "L1"
},
{
"institutionalService": {
"serviceLineRevenueCode": "0300",
"procedureIdentifier": "HC",
"procedureCode": "80053",
"lineItemChargeAmount": "500.50",
"serviceUnitCount": "1"
},
"serviceDate": "20261001",
"lineItemControlNumber": "L2"
}
]
}
}
}{
"kind": "837I",
"version": "005010X223A2",
"valid": true,
"claims": [
{
"index": 0,
"reference": "PW-3001",
"errors": [],
"warnings": []
}
]
}| Field | Type | What it is |
|---|---|---|
kind | one of "837I", "837D" | |
version | string | |
valid | boolean | True when no claim has an error. |
claims | list of Claim837Checks |
POST/v1/claims/837d
Write an 837D
Up to one hundred dental claims and predeterminations written as one 005010X224A2 interchange from the same JSON as the 837P route, with the teeth and surfaces, the area of the mouth, tooth status, prosthesis replacement, orthodontic months and up to four diagnoses. A predetermination carries no date of service. A dental procedure code is checked for its shape: the code set’s words belong to the ADA. Nothing is written if any claim would be refused, and a test key writes test files only.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/837d" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaims837d(body);With the Python client
answer = pw.post_claims_837d(body){
"claim": {
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Dental",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Dental Plan"
},
"billing": {
"organizationName": "Sample Dental",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "1223G0001X",
"address": {
"address1": "3 Oak Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19800202",
"gender": "F",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"rendering": {
"lastName": "Dentist",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "1223G0001X"
},
"claimInformation": {
"patientControlNumber": "PW-4001",
"claimChargeAmount": "385",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"serviceDate": "20261005"
},
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "K02.52"
}
],
"serviceLines": [
{
"dentalService": {
"procedureCode": "D2392",
"lineItemChargeAmount": "210",
"procedureCount": 1,
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "30",
"toothSurfaceCodes": [
"M",
"O"
]
}
],
"providerControlNumber": "DL1"
},
{
"dentalService": {
"procedureCode": "D2740",
"lineItemChargeAmount": "175",
"prosthesisCrownOrInlayCode": "I",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "19"
}
],
"providerControlNumber": "DL2"
}
]
}
},
"sender_id": "SAMPLEBILLER",
"receiver_id": "99999",
"control_number": 8
}{
"kind": "837D",
"version": "005010X224A2",
"usage": "T",
"x12": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*99999 *261019*1500*^*00501*000000008*0*T*:~GS*HC*SAMPLEBILLER*99999*20261019*1500*8*X*005010X224A2~ST*837*0001*005010X224A2~BHT*0019*00*PW-4001*20261019*1500*CH~NM1*41*2*Sample …",
"interchange_control_number": "000000008",
"group_control_number": "8",
"transaction_set_control_numbers": [
"0001"
],
"segments": 36,
"claims": [
{
"reference": "PW-4001",
"transaction_set_control_number": "0001",
"warnings": []
}
],
"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 |
|---|---|---|
version | string | The implementation guide written. |
usage | one of "T", "P" | T or P. |
x12 | string | The whole interchange. |
interchange_control_number | string | |
group_control_number | string | |
transaction_set_control_numbers | list of string | |
segments | integer | |
transmitted | the value false | Payerworks wrote the file and sent it nowhere. |
kind | one of "837I", "837D" | |
claims | list of object |
POST/v1/claims/837d/validate
Validate dental claims
The same dental claims checked against the 837D’s rules without writing a file: each problem names its code, its field and a sentence.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/837d/validate" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaims837dValidate(body);With the Python client
answer = pw.post_claims_837d_validate(body){
"claim": {
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Dental",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Dental Plan"
},
"billing": {
"organizationName": "Sample Dental",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "1223G0001X",
"address": {
"address1": "3 Oak Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19800202",
"gender": "F",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"rendering": {
"lastName": "Dentist",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "1223G0001X"
},
"claimInformation": {
"patientControlNumber": "PW-4001",
"claimChargeAmount": "385",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"serviceDate": "20261005"
},
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "K02.52"
}
],
"serviceLines": [
{
"dentalService": {
"procedureCode": "D2392",
"lineItemChargeAmount": "210",
"procedureCount": 1,
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "30",
"toothSurfaceCodes": [
"M",
"O"
]
}
],
"providerControlNumber": "DL1"
},
{
"dentalService": {
"procedureCode": "D2740",
"lineItemChargeAmount": "175",
"prosthesisCrownOrInlayCode": "I",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "19"
}
],
"providerControlNumber": "DL2"
}
]
}
}
}{
"kind": "837D",
"version": "005010X224A2",
"valid": true,
"claims": [
{
"index": 0,
"reference": "PW-4001",
"errors": [],
"warnings": []
}
]
}| Field | Type | What it is |
|---|---|---|
kind | one of "837I", "837D" | |
version | string | |
valid | boolean | True when no claim has an error. |
claims | list of Claim837Checks |
POST/v1/claims/correction-plan
Plan a corrected or void claim
Say whether you want to replace or void a claim, and give the payer’s claim number, or say the payer never processed it (adjudicated: false); with neither, the plan asks which rather than guess. The plan says the frequency code, whether REF*F8 goes, whether to use a new patient control number, and when a Medicare contractor fixes a processed claim by reopening instead. Send the replacement too, as JSON or an 837P (an 837D for a dental claim), and it is checked against the plan and every claim rule. Companion guides vary, and the answer says so. It writes and sends nothing.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/correction-plan" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaimsCorrectionPlan(body);With the Python client
answer = pw.post_claims_correction_plan(body){
"change": "replace",
"payer_claim_number": "2026101900123",
"original": {
"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"
]
}
}
}
]
}
},
"replacement": {
"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-2001A",
"claimChargeAmount": "215.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "7",
"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": {
"claimControlNumber": "2026101900123"
}
}
}
}{
"change": "replace",
"claim_type": "professional",
"stage": "adjudicated",
"stage_reason": "The payer gave the claim its own number, so it took the claim into processing.",
"medicare_mac": false,
"medicare_mac_source": "default",
"route": "send_corrected_claim",
"frequency_code": "7",
"ref_f8": {
"send": true,
"value": "2026101900123"
},
"patient_control_number": {
"new_one": true,
"original": "PW-2001",
"why": "A new reference keeps the corrected claim's acknowledgments and remittance apart from the original's, so neither is matched to the other; some payers ask for the original's, so read the companion guide."
},
"steps": [
"Send the whole claim again with every service, corrected: frequency code 7 (CLM05-3).",
"Put the payer's claim number in 2300 REF*F8 (2026101900123); without it the payer rejects the claim."
],
"caveat": "Companion guides vary: this is the rule most payers publish, and a payer's own companion guide decides. Read it before the first corrected claim you send to that payer.",
"sources": [
"https://www.bcbsil.com/docs/provider/il/claims/submission/claim-frequency-codes-prof.pdf",
"https://x12.org/resources/requests-for-interpretation/rfi-1278-5010-837-claim-ccndcn"
],
"replacement": {
"valid": true,
"checks": "plan_claim_and_coordination",
"errors": [],
"warnings": []
}
}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 |
|---|---|---|
change | string | |
claim_type | string | |
stage | one of "not_adjudicated", "adjudicated" | |
stage_reason | string | |
medicare_mac | boolean | |
medicare_mac_source | one of "default", "caller", "claim_filing_code" | |
route | one of "send_as_new_claim", "nothing_to_void", "send_corrected_claim", "medicare_reopening" | |
frequency_code | string or null | CLM05-3. |
ref_f8 | object | |
patient_control_number | object | |
steps | list of string | |
caveat | string | Companion guides vary, and the answer says so. |
sources | list of string | |
if_returned_unprocessable | object | A Medicare claim the contractor returned as unprocessable: sent again as a new claim. |
replacement | object or null |
GET/v1/edits
Every claim edit
Every check Payerworks runs on a professional claim before it is written: its code, SNIP type, severity, what is wrong, how to fix it and where the rule comes from. Also the formatting repairs made first, the coordination of benefits checks a claim to a later payer gets, the checks a correction plan’s replacement gets, and the checks Payerworks does not run, with why. Filter with snip_type, severity, kind or runs_in, applied to every list. Passing every check means the claim is well formed and its codes are valid on their dates, not that a payer will pay it.
Request
curl -sS -X GET "$PAYERWORKS_BASE_URL/v1/edits?kind=code_set" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY"With the JavaScript client
const answer = await pw.getEdits({ query: {"kind":"code_set"} });With the Python client
answer = pw.get_edits(query={"kind": "code_set"}){
"version": "10/19/2026",
"scope": "The edits Payerworks runs on a professional (837P) claim before it is written, from the one table the validator runs. Passing them means the claim is well formed and its codes are valid on their dates; it does not mean a payer will pay it, …",
"claim_types": [
"837P"
],
"filters": {
"kind": "code_set"
},
"count": 4,
"edits": [
{
"code": "place_of_service_unassigned",
"snip_type": 5,
"claim_types": [
"837P"
],
"severity": "error",
"kind": "code_set",
"message": "The place of service is two digits but not a code CMS has assigned, or not one in force on the date of service.",
"fix": "Send an assigned place of service code (11 office, 12 home, 22 outpatient hospital and the rest of CMS's list).",
"source": {
"title": "CMS Place of Service Code Set",
"url": "https://www.cms.gov/medicare/coding-billing/place-of-service-codes/code-sets",
"read_on": "10/19/2026"
},
"runs_in": "edits"
},
{
"code": "diagnosis_not_valid_on_date",
"snip_type": 5,
"claim_types": [
"837P"
],
"severity": "error",
"kind": "code_set",
"message": "A diagnosis code is not a valid ICD-10-CM code in the release in force on its date of service.",
"fix": "Send a code valid on that day: a code is valid from the October 1 its release takes effect to the next September 30.",
"source": {
"title": "ICD-10-CM code files, FY2025 to FY2027 (CMS)",
"url": "https://www.cms.gov/medicare/coding-billing/icd-10-codes",
"read_on": "10/19/2026"
},
"runs_in": "edits",
"needs_code_set": "icd10cm"
}
],
"repairs": [
{
"code": "spaces_trimmed",
"does": "Removes spaces before and after a value."
},
{
"code": "phone_punctuation_removed",
"does": "Writes a phone or fax number as its ten digits: parentheses, hyphens, dots, spaces and a leading +1 are removed."
}
],
"coordination_of_benefits": [],
"replacement_checks": [],
"not_run": [
{
"code": "taxonomy_not_in_code_set",
"snip_type": 5,
"why": "The national provider taxonomy is licensed by the AMA through NUCC: its permission must be accepted on behalf of the organization before the set is used in a product. Only the code's shape is checked (invalid_taxonomy).",
"source": {
"url": "https://www.nucc.org/index.php/code-sets-mainmenu-41/provider-taxonomy-mainmenu-40/csv-mainmenu-57",
"read_on": "10/19/2026"
}
},
{
"code": "clia_not_on_file",
"snip_type": 5,
"why": "CMS publishes the certified laboratories in its quarterly Provider of Services file (15 MB to 36 MB), a lookup for the door, not a table for this claim check. Only the number's shape is checked (invalid_clia).",
"source": {
"url": "https://catalog.data.gov/dataset/provider-of-services-file-clinical-laboratories-2024-03-02",
"read_on": "10/19/2026"
}
}
],
"transmits": 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 |
|---|---|---|
version | string | |
scope | string | |
claim_types | list of string | |
filters | object | The filters this answer applied. |
count | integer | |
edits | list of Edit | |
repairs | list of EditRepair | The formatting repaired on a copy before any check runs. |
coordination_of_benefits | list of EditCheckRow | The checks a claim to a later payer gets. |
replacement_checks | list of EditCheckRow | The checks a correction plan’s replacement gets. |
not_run | list of EditNotRun | |
transmits | the value false |
GET/v1/edits/{code}
One claim edit
One check by its code, in any case. A check Payerworks does not run answers runs: false and says why; any other code is 404 edit_not_found.
Request
curl -sS -X GET "$PAYERWORKS_BASE_URL/v1/edits/future_date" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY"With the JavaScript client
const answer = await pw.getEditsByCode("future_date");With the Python client
answer = pw.get_edits_by_code("future_date"){
"version": "10/19/2026",
"runs": true,
"edit": {
"code": "future_date",
"snip_type": 3,
"claim_types": [
"837P"
],
"severity": "error",
"kind": "deterministic",
"message": "A date on the claim has not happened yet: a claim bills a service already given.",
"fix": "Send the claim after the service, with the day it was given.",
"source": {
"title": "Decided by the claim itself",
"where": "a value that contradicts another on the same claim"
},
"runs_in": "edits"
}
}| Field | Type | What it is |
|---|---|---|
version | string | |
runs | boolean | False for a check Payerworks does not run. |
edit | Edit or EditCheckRow or EditNotRun |
POST/v1/edits/rules/check
Check your own claim rules
Rules you write for your own payers: a field’s path, an operator from a fixed list of twenty, a value, the payers it applies to, your message and whether it is an error or a warning. Each rule is checked for the format, and applied to any claims you send with it (up to 100). The same rules may ride on POST /v1/claims/validate and POST /v1/claims/837p as rules, where a rule of severity error refuses the claim. Patterns are a small fixed format, never code, and each call has a step budget, and a field a rule reads may reach at most 1,000 values: a rule it does not reach, or whose field reaches more, is listed as not checked with its reason, never as passed. Nothing is stored.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/edits/rules/check" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postEditsRulesCheck(body);With the Python client
answer = pw.post_edits_rules_check(body){
"rules": [
{
"id": "visit-needs-pos-11",
"payer_id": "99999",
"field": "claimInformation.placeOfServiceCode",
"operator": "not_equals",
"value": "11",
"severity": "error",
"message": "This plan pays office visits in the office only."
},
{
"id": "member-id-shape",
"field": "subscriber.memberId",
"operator": "not_matches",
"value": "W\\d{9}",
"severity": "warning",
"message": "Our member ids for this plan are W and nine digits."
},
{
"id": "strep-test-needs-qw",
"scope": "claimInformation.serviceLines[]",
"when": [
{
"field": "professionalService.procedureCode",
"operator": "equals",
"value": "87880"
}
],
"field": "professionalService.procedureModifiers",
"operator": "not_contains",
"value": "QW",
"severity": "error",
"message": "A waived rapid strep test (87880) is billed with modifier QW."
}
],
"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"
]
}
}
}
]
}
}
}{
"valid": true,
"rules": [
{
"index": 0,
"id": "visit-needs-pos-11",
"valid": true,
"problems": []
},
{
"index": 1,
"id": "member-id-shape",
"valid": true,
"problems": []
}
],
"operators": [
"exists",
"absent"
],
"stored": false,
"claims": [
{
"index": 0,
"reference": "PW-2001",
"errors": [
{
"code": "caller_rule",
"rule_id": "strep-test-needs-qw",
"field": "claimInformation.serviceLines[1].professionalService.procedureModifiers",
"message": "A waived rapid strep test (87880) is billed with modifier QW.",
"severity": "error",
"source": "caller"
}
],
"warnings": [],
"not_checked": []
}
]
}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 |
|---|---|---|
valid | boolean | |
rules | list of object | |
operators | list of one of "exists", "absent", "equals", "not_equals", "in", "not_in", "contains", "not_contains", "starts_with", "ends_with", "longer_than", "shorter_than", "gt", "gte", "lt", "lte", "before", "after", "matches", "not_matches" | |
stored | the value false | |
claims | list of object | Each claim sent, with the rules that fired on it (only when every rule is valid). |
POST/v1/x12/parse
Read an X12 file
Any X12 file Payerworks reads, to JSON with its envelope, in the file’s own delimiters: an 835, a 999, a 277CA, a 270 or 271, a 276 or 277, a 278, or an 837P, 837I or 837D. A claim file is read back to the same JSON its write route takes, each claim also as its own one-claim interchange, so a bulk file splits per claim, and every segment the reader does not read is named by its id, loop and position, never its value. A 277CA is told from a claim status 277 by its implementation guide, any other kind is named, and an interchange that mixes kinds is refused.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/x12/parse" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postX12Parse(body);With the Python client
answer = pw.post_x12_parse(body){
"x12": "ISA*00* *00* *ZZ*SAMPLEPAYER *ZZ*SAMPLEBILLER *261018*0900*^*00501*000000071*0*T*:~\nGS*FA*SAMPLEPAYER*SAMPLEBILLER*20261018*0900*71*X*005010X231A1~\nST*999*0001*005010X231A1~\nAK1*HC*42*005010X222A1~\nAK2*837*0001*005010X222A1~\nIK3*NM1*8*2010BA*8~\nCTX*CLM01:PW-1003~\nIK4*9*67*6*W1234#~\nIK5*R*5~\nAK9*R*1*1*0~\nSE*9*0001~\nGE*1*71~\nIEA*1*000000071~"
}{
"kind": "999",
"envelope": {
"sender_qualifier": "ZZ",
"sender": "SAMPLEPAYER",
"receiver_qualifier": "ZZ",
"receiver": "SAMPLEBILLER",
"date": "261018",
"time": "0900",
"control_number": "000000071",
"usage": "T",
"functional_group": "FA",
"version": "005010X231A1",
"transaction_sets": {
"999": 1
},
"segments": 12
},
"acknowledgment": {
"ok": true,
"groups": [
{
"functional": "HC",
"control": "42",
"version": "005010X222A1",
"verdict": "R",
"included": 1,
"received": 1,
"accepted": 0,
"codes": [],
"sets": [
{
"set": "837",
"control": "0001",
"implementation": "005010X222A1",
"verdict": "R",
"codes": [
"5"
],
"errors": [
{
"segment": "NM1",
"position": "8",
"loop": "2010BA",
"code": "8",
"claim_reference": "PW-1003",
"context": null,
"elements": [
{
"position": "9",
"component": "",
"reference": "67",
"code": "6",
"value": "W1234#"
}
]
}
]
}
]
}
]
}
}| Field | Type | What it is |
|---|---|---|
kind | one of "270", "271", "276", "277", "277CA", "277RFAI", "278", "835", "837P", "837I", "837D", "999", "997", "TA1", "mixed", "unknown" | The kind of file read. |
envelope | Envelope | The interchange envelope, as the file states it. |
remittance | object | An 835, read. |
acknowledgment | object | A 999, read. |
claim_acknowledgment | object | A 277CA, read. |
interchange_acknowledgment | object | A TA1, read: each TA1’s verdict (TA104) and note code (TA105), in words. |
eligibility_request | object | A 270, read: each request in the JSON shape POST /v1/eligibility/270 takes, and not_read, every segment the reader does not read. |
eligibility_answer | object | A 271, read: each transaction, with answered_on and unread. |
claim_status_inquiry | object | A 276, read: each question in the JSON shape POST /v1/claim-status/276 takes. |
claim_status | object | A 277 claim status answer (005010X212), read. |
professional_claims | ClaimFileRead | An 837P, 837I or 837D read back. |
institutional_claims | ClaimFileRead | An 837P, 837I or 837D read back. |
dental_claims | ClaimFileRead | An 837P, 837I or 837D read back. |
authorization | object | A 278 request or response (005010X217), read: each review with its decision, dates and services. |
POST/v1/sandbox/claims
Run the sandbox payer
Your claims written as an 837P and answered by the sandbox payer in the same call: a 999 for the file, a 277CA for each claim and an 835 for each claim it adjudicated, every file explained, and claims[] with each claim’s warnings, its repairs and the checks that could not run. Any key may call it, every file is a test file, and nothing reaches a payer. How the member ID ends decides the answer. A member ID ending in RFAI is held for a document: a 277 request for additional information follows. Send the same claims again with the solicited 275 (attachments_275, at most five) and the claim is paid.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/sandbox/claims" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postSandboxClaims(body);With the Python client
answer = pw.post_sandbox_claims(body){
"sender_id": "SAMPLEBILLER",
"claims": [
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Sleep Dentistry",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"npi": "1234567893",
"employerId": "123456789",
"organizationName": "Sample Sleep Dentistry",
"taxonomyCode": "1223S0112X",
"address": {
"address1": "100 Main Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"paymentResponsibilityLevelCode": "P",
"firstName": "Sample",
"lastName": "Patient",
"gender": "F",
"dateOfBirth": "19600214",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "PW-SBX-PAID",
"claimChargeAmount": "2900.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "G4733"
}
],
"serviceLines": [
{
"serviceDate": "20261001",
"professionalService": {
"procedureIdentifier": "HC",
"procedureCode": "E0486",
"procedureModifiers": [
"KX"
],
"lineItemChargeAmount": "2900.00",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
}
}
]
}
},
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Sleep Dentistry",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"npi": "1234567893",
"employerId": "123456789",
"organizationName": "Sample Sleep Dentistry",
"taxonomyCode": "1223S0112X",
"address": {
"address1": "100 Main Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W12345REJ",
"paymentResponsibilityLevelCode": "P",
"firstName": "Sample",
"lastName": "Patient",
"gender": "F",
"dateOfBirth": "19600214",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "PW-SBX-REJ",
"claimChargeAmount": "2900.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "G4733"
}
],
"serviceLines": [
{
"serviceDate": "20261001",
"professionalService": {
"procedureIdentifier": "HC",
"procedureCode": "E0486",
"procedureModifiers": [
"KX"
],
"lineItemChargeAmount": "2900.00",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
}
}
]
}
}
]
}{
"usage": "T",
"transmitted": false,
"control": {
"interchange": "000000001",
"group": "1",
"sets": [
"0001",
"0002"
]
},
"files": {
"claims_837p": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*PWSANDBOX *261019*1500*^*00501*000000001*0*T*:~GS*HC*SAMPLEBILLER*PWSANDBOX*20261019*1500*1*X*005010X222A1~ST*837*0001*005010X222A1~BHT*0019*00*PW-SBX-PAID*20261019*1500*CH~NM1*41*2…",
"acknowledgment_999": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000001*0*T*:~GS*FA*PWSANDBOX*SAMPLEBILLER*20261019*1500*1*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HC*1*005010X222A1~AK2*837*0001*005010X222A1~I…",
"claim_acknowledgment_277ca": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000002*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1500*2*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*PWSANDBOX2*20261019*1500*TH~HL*1**20*1~NM…",
"remittance_835": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000003*0*T*:~GS*HP*PWSANDBOX*SAMPLEBILLER*20261019*1500*3*X*005010X221A1~ST*835*0001~BPR*I*1392*C*CHK************20261019~TRN*1*PWSANDBOX-000000003…"
},
"outcomes": [
{
"reference": "PW-SBX-PAID",
"outcome": "paid",
"charge": 2900,
"allowed": 1740,
"paid": 1392,
"patient_responsibility": 348,
"payer_claim_number": "PWS2292711347"
},
{
"reference": "PW-SBX-REJ",
"outcome": "rejected",
"charge": 2900,
"allowed": null,
"paid": null,
"patient_responsibility": null,
"payer_claim_number": ""
}
],
"claims": [
{
"reference": "PW-SBX-PAID",
"warnings": [],
"repairs": [],
"not_checked": []
},
{
"reference": "PW-SBX-REJ",
"warnings": [],
"repairs": [],
"not_checked": []
}
],
"explained": {
"acknowledgment_999": {
"kind": "999",
"groups": [
{
"control_number": "1",
"verdict": "A",
"verdict_words": "Accepted",
"received": 2,
"accepted": 2,
"transaction_sets": [
{
"control_number": "0001",
"verdict": "A",
"verdict_words": "Accepted",
"fixes": []
},
{
"control_number": "0002",
"verdict": "A",
"verdict_words": "Accepted",
"fixes": []
}
]
}
]
},
"claim_acknowledgment_277ca": {
"kind": "277CA",
"batch": {
"trace": "000000001",
"statuses": [
{
"category": "A1",
"code": "19",
"entity": "PR",
"date": "20261019",
"action": "WQ",
"amount": "5800"
}
],
"accepted": 1,
"rejected": 1
},
"claims": [
{
"reference": "PW-SBX-PAID",
"payer_claim_number": "PWS2292711347",
"verdict": "A",
"fixes": [
{
"category": "A2",
"code": "20",
"entity": "",
"verdict": "A",
"where": "",
"sentence": "The claim was accepted into the payer's adjudication system: accepted for processing (STC A2:20). Nothing to fix."
}
]
},
{
"reference": "PW-SBX-REJ",
"payer_claim_number": "",
"verdict": "R",
"fixes": [
{
"category": "A7",
"code": "164",
"entity": "IL",
"verdict": "R",
"where": "the subscriber in your claim data",
"sentence": "The claim was rejected for invalid information: the subscriber's contract or member number is missing or invalid (STC A7:164:IL). Fix it on the subscriber in your claim data, then send the claim again."
}
]
}
]
},
"remittance": {
"check": {
"number": "PWSANDBOX-000000003-1",
"date": "20261019",
"amount": "1392",
"method_flag": "C",
"payer": "PAYERWORKS SANDBOX PAYER",
"payee_ids": {
"npis": [
"1234567893"
],
"tins": [
"123456789"
]
}
},
"checks": [
{
"number": "PWSANDBOX-000000003-1",
"date": "20261019",
"amount": "1392",
"method_flag": "C",
"payer": "PAYERWORKS SANDBOX PAYER",
"payee_ids": {
"npis": [
"1234567893"
],
"tins": [
"123456789"
]
},
"references": [
"PW-SBX-PAID"
],
"balance": {
"stated": 1392,
"claims_net": 1392,
"provider_adjustments_net": 0,
"variance": 0,
"ties": true,
"words": "The claims, less the provider-level adjustments, add up to the check."
},
"provider_adjustments": []
}
],
"claims": [
{
"reference": "PW-SBX-PAID",
"payer_claim_number": "PWS2292711347",
"status_code": "1",
"status": "processed as primary",
"service_date": "20261001",
"billed": 2900,
"paid": 1392,
"allowed": 1740,
"patient_responsibility": 348,
"amounts": {
"billed": 2900,
"paid": 1392,
"allowed": 1740,
"allowed_basis": "stated",
"patient_responsibility": 348,
"patient_basis": "stated",
"adjustment": 1160,
"adjustment_basis": "stated",
"write_off": 1160,
"below_allowed": 0,
"not_paid": 0,
"shortfall": 0
},
"adjustments": [
{
"group": "CO",
"code": "45",
"amount": 1160,
"label": "Charge exceeds the fee schedule / contracted amount",
"category": "Underpayment",
"known": true,
"label_source": "paraphrase",
"patient_billable": false
}
],
"patient_adjustments": [
{
"group": "PR",
"code": "2",
"amount": 348,
"label": "Coinsurance amount",
"category": "Other",
"known": true,
"label_source": "paraphrase",
"patient_billable": true
}
],
"remark_codes": [],
"primary_reason": null,
"crossover_carrier": "",
"service_lines": [
{
"procedure_code": "E0486",
"modifiers": [
"KX"
],
"billed": 2900,
"paid": 1392,
"allowed": 1740
}
],
"check_number": "PWSANDBOX-000000003-1",
"index": 0,
"claim_filing_indicator": "CI",
"verdict": "paid",
"verdict_words": "Paid: the payer paid $1,392.00, the patient owes $348.00 (patient responsibility), and $1,160.00 is a contractual adjustment.",
"remarks": [],
"claim_adjustments": [],
"lines": [
{
"index": 0,
"procedure_code": "E0486",
"procedure_qualifier": "HC",
"modifiers": [
"KX"
],
"billed": 2900,
"paid": 1392,
"allowed": 1740,
"units_paid": 1,
"service_date": "2026-10-01",
"service_date_end": null,
"line_control_number": "",
"adjustments": [
{
"group": "CO",
"code": "45",
"amount": 1160,
"line": 0
},
{
"group": "PR",
"code": "2",
"amount": 348,
"line": 0
}
],
"remarks": []
}
]
}
],
"provider_adjustments": [],
"groups": {
"CO": {
"name": "Contractual obligation",
"patient_billable": false,
"words": "An adjustment your agreement with the payer, or a regulation, requires. It is generally a write-off for you and is not billed to the patient."
},
"OA": {
"name": "Other adjustment",
"patient_billable": "depends",
"words": "Used when no other group applies, such as the effect of an earlier payer's payment. Whether the patient may be billed depends on the reason code beside it and on your agreement with the plan."
},
"PI": {
"name": "Payer-initiated reduction",
"patient_billable": false,
"words": "A reduction the payer made itself. It is not a patient responsibility amount, so it is not billed to the patient."
},
"PR": {
"name": "Patient responsibility",
"patient_billable": true,
"words": "An amount that may be billed to the patient, such as the deductible, coinsurance or copay."
}
}
}
},
"events": [
{
"id": "evt_cc264f7536a9315a0c6fe09f",
"type": "sandbox.file.acknowledged"
},
{
"id": "evt_e38518c4523f2dcd24e34de2",
"type": "sandbox.claim.acknowledged"
}
],
"webhook": {
"configured": false,
"queued": 0
}
}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 |
|---|---|---|
usage | the value "T" | |
transmitted | the value false | |
control | object | |
files | object | |
outcomes | list of SandboxOutcome | |
claims | list of object | Each claim as it was checked, as POST /v1/claims/837p answers it beside its file. |
explained | object | Each answer as /v1/acknowledgments/explain, /v1/remittances/explain and /v1/attachments/requests/explain say it. |
events | list of EventRef | |
webhook | object | Events are queued for your webhook, never delivered inside the call; GET /v1/events says what each delivery did. |
POST/v1/sandbox/claims/837i
Run the sandbox payer on an 837I
Your institutional claims checked as POST /v1/claims/837i checks them, written as an 837I and answered by the same sandbox payer as the professional claims, by the same rules: how the member ID ends decides the answer, and the paid amounts and payer claim numbers are made the same way. The answer is a 999 for the file, a 277CA for each claim and an 835 for each claim it adjudicated, and explain_with names the routes that explain them. A member ID ending in RFAI is held for a document, as on POST /v1/sandbox/claims: send the same claims again with the solicited 275 in attachments_275 and the claim is paid. Any key may call it, every file is a test file, nothing is posted to your webhook, and nothing reaches a payer.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/sandbox/claims/837i" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postSandboxClaims837i(body);With the Python client
answer = pw.post_sandbox_claims_837i(body){
"sender_id": "SAMPLEBILLER",
"claim": {
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Community Hospital",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"organizationName": "Sample Community Hospital",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "282N00000X",
"address": {
"address1": "200 Hospital Drive",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19700101",
"gender": "F",
"groupNumber": "GRP1",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"attending": {
"lastName": "Doctor",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "207R00000X"
},
"claimInformation": {
"patientControlNumber": "PW-3001",
"claimChargeAmount": "1500.50",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"statementBeginDate": "20261001",
"statementEndDate": "20261003",
"admissionDateAndHour": "202610010800",
"dischargeHour": "1400"
},
"claimCodeInformation": {
"admissionTypeCode": "1",
"admissionSourceCode": "7",
"patientStatusCode": "01"
},
"principalDiagnosis": {
"qualifierCode": "ABK",
"principalDiagnosisCode": "J18.9",
"presentOnAdmissionIndicator": "Y"
},
"admittingDiagnosis": {
"qualifierCode": "ABJ",
"admittingDiagnosisCode": "R05"
},
"otherDiagnosisInformationList": [
[
{
"qualifierCode": "ABF",
"otherDiagnosisCode": "E119",
"presentOnAdmissionIndicator": "Y"
}
]
],
"serviceLines": [
{
"institutionalService": {
"serviceLineRevenueCode": "0120",
"lineItemChargeAmount": "1000",
"measurementUnit": "DA",
"serviceUnitCount": "2"
},
"serviceDate": "20261001",
"serviceDateEnd": "20261002",
"lineItemControlNumber": "L1"
},
{
"institutionalService": {
"serviceLineRevenueCode": "0300",
"procedureIdentifier": "HC",
"procedureCode": "80053",
"lineItemChargeAmount": "500.50",
"serviceUnitCount": "1"
},
"serviceDate": "20261001",
"lineItemControlNumber": "L2"
}
]
}
}
}{
"kind": "837I",
"version": "005010X223A2",
"usage": "T",
"transmitted": false,
"control": {
"interchange": "000000001",
"group": "1",
"sets": [
"0001"
]
},
"files": {
"claims_837i": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*PWSANDBOX *261019*1500*^*00501*000000001*0*T*:~GS*HC*SAMPLEBILLER*PWSANDBOX*20261019*1500*1*X*005010X223A2~ST*837*0001*005010X223A2~BHT*0019*00*PW-3001*20261019*1500*CH~NM1*41*2*Sam…",
"acknowledgment_999": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000001*0*T*:~GS*FA*PWSANDBOX*SAMPLEBILLER*20261019*1500*1*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HC*1*005010X223A2~AK2*837*0001*005010X223A2~I…",
"claim_acknowledgment_277ca": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000002*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1500*2*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*PWSANDBOX2*20261019*1500*TH~HL*1**20*1~NM…",
"remittance_835": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000003*0*T*:~GS*HP*PWSANDBOX*SAMPLEBILLER*20261019*1500*3*X*005010X221A1~ST*835*0001~BPR*I*720.24*C*CHK************20261019~TRN*1*PWSANDBOX-0000000…"
},
"outcomes": [
{
"reference": "PW-3001",
"outcome": "paid",
"charge": 1500.5,
"allowed": 900.3,
"paid": 720.24,
"patient_responsibility": 180.06,
"payer_claim_number": "PWS1424823247"
}
],
"claims": [
{
"reference": "PW-3001",
"warnings": []
}
],
"explain_with": {
"acknowledgments": "POST /v1/acknowledgments/explain",
"remittance": "POST /v1/remittances/explain"
}
}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 |
|---|---|---|
kind | one of "837I", "837D" | |
version | string | |
usage | the value "T" | |
transmitted | the value false | |
control | object | |
files | object | |
outcomes | list of SandboxOutcome | |
claims | list of object | |
explain_with | object | The routes that explain the files: these runs are not explained inside the answer, and nothing is posted to your webhook. |
loinc_notice | string | Only when a claim is held for information. |
POST/v1/sandbox/claims/837d
Run the sandbox payer on an 837D
Your dental claims and predeterminations, checked as POST /v1/claims/837d checks them and answered by the same sandbox payer, by the same member ID endings, with a 999, a 277CA and an 835. A predetermination is answered as one: CLP02 25, nothing paid, each line’s would-be payment as an OA 101 adjustment, and the estimate in the outcome. A member ID ending in RFAI is held for a document: send the same claims again with the solicited 275 in attachments_275 and the claim is paid. Any key may call it, every file is a test file, nothing is posted to your webhook, and nothing reaches a payer.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/sandbox/claims/837d" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postSandboxClaims837d(body);With the Python client
answer = pw.post_sandbox_claims_837d(body){
"sender_id": "SAMPLEBILLER",
"claims": [
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Dental",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Dental Plan"
},
"billing": {
"organizationName": "Sample Dental",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "1223G0001X",
"address": {
"address1": "3 Oak Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19800202",
"gender": "F",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"rendering": {
"lastName": "Dentist",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "1223G0001X"
},
"claimInformation": {
"patientControlNumber": "PW-4001",
"claimChargeAmount": "385",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"claimDateInformation": {
"serviceDate": "20261005"
},
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "K02.52"
}
],
"serviceLines": [
{
"dentalService": {
"procedureCode": "D2392",
"lineItemChargeAmount": "210",
"procedureCount": 1,
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "30",
"toothSurfaceCodes": [
"M",
"O"
]
}
],
"providerControlNumber": "DL1"
},
{
"dentalService": {
"procedureCode": "D2740",
"lineItemChargeAmount": "175",
"prosthesisCrownOrInlayCode": "I",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "19"
}
],
"providerControlNumber": "DL2"
}
]
}
},
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Dental",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Dental Plan"
},
"billing": {
"organizationName": "Sample Dental",
"npi": "1234567893",
"employerId": "123456789",
"taxonomyCode": "1223G0001X",
"address": {
"address1": "3 Oak Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"firstName": "Sample",
"lastName": "Patient",
"dateOfBirth": "19800202",
"gender": "F",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"rendering": {
"lastName": "Dentist",
"firstName": "Sample",
"npi": "1245319599",
"taxonomyCode": "1223G0001X"
},
"claimInformation": {
"patientControlNumber": "PW-4002",
"claimChargeAmount": "385",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"claimFilingCode": "CI",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "K02.52"
}
],
"serviceLines": [
{
"dentalService": {
"procedureCode": "D2392",
"lineItemChargeAmount": "210",
"procedureCount": 1,
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "30",
"toothSurfaceCodes": [
"M",
"O"
]
}
],
"providerControlNumber": "DL1"
},
{
"dentalService": {
"procedureCode": "D2740",
"lineItemChargeAmount": "175",
"prosthesisCrownOrInlayCode": "I",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
},
"teethInformation": [
{
"toothCode": "19"
}
],
"providerControlNumber": "DL2"
}
],
"predeterminationOfBenefits": true
}
}
]
}{
"kind": "837D",
"version": "005010X224A2",
"usage": "T",
"transmitted": false,
"control": {
"interchange": "000000001",
"group": "1",
"sets": [
"0001",
"0002"
]
},
"files": {
"claims_837d": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*PWSANDBOX *261019*1500*^*00501*000000001*0*T*:~GS*HC*SAMPLEBILLER*PWSANDBOX*20261019*1500*1*X*005010X224A2~ST*837*0001*005010X224A2~BHT*0019*00*PW-4001*20261019*1500*CH~NM1*41*2*Sam…",
"acknowledgment_999": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000001*0*T*:~GS*FA*PWSANDBOX*SAMPLEBILLER*20261019*1500*1*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HC*1*005010X224A2~AK2*837*0001*005010X224A2~I…",
"claim_acknowledgment_277ca": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000002*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1500*2*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*PWSANDBOX2*20261019*1500*TH~HL*1**20*1~NM…",
"remittance_835": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1500*^*00501*000000003*0*T*:~GS*HP*PWSANDBOX*SAMPLEBILLER*20261019*1500*3*X*005010X221A1~ST*835*0001~BPR*I*184.8*C*CHK************20261019~TRN*1*PWSANDBOX-00000000…"
},
"outcomes": [
{
"reference": "PW-4001",
"outcome": "paid",
"charge": 385,
"allowed": 231,
"paid": 184.8,
"patient_responsibility": 46.2,
"payer_claim_number": "PWS3214346392"
},
{
"reference": "PW-4002",
"outcome": "paid",
"charge": 385,
"allowed": 231,
"paid": 0,
"patient_responsibility": 46.2,
"payer_claim_number": "PWS3264679249",
"predetermination": true,
"estimated_payment": 184.8
}
],
"claims": [
{
"reference": "PW-4001",
"warnings": []
},
{
"reference": "PW-4002",
"warnings": []
}
],
"explain_with": {
"acknowledgments": "POST /v1/acknowledgments/explain",
"remittance": "POST /v1/remittances/explain"
}
}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 |
|---|---|---|
kind | one of "837I", "837D" | |
version | string | |
usage | the value "T" | |
transmitted | the value false | |
control | object | |
files | object | |
outcomes | list of SandboxOutcome | |
claims | list of object | |
explain_with | object | The routes that explain the files: these runs are not explained inside the answer, and nothing is posted to your webhook. |
loinc_notice | string | Only when a claim is held for information. |
POST/v1/sandbox/claims/timeline
Run the sandbox over days
The claims sandbox spread over simulated time: the 999 after five minutes, a 277CA saying each claim was received after an hour, the payer’s own 277CA after two days and the 835 after fourteen. Send the claims, a seed, the start and the moment to read as of; send a later moment and the cursor you were given to read what came next. Each event is the exact body a webhook sends, so you can post it to your own handler; Payerworks posts none of them. Add format: report for the 277CAs and 835 in the JSON field names most clearinghouse APIs use. Nothing is stored or sent: the same request gives the same answer.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/sandbox/claims/timeline" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postSandboxClaimsTimeline(body);With the Python client
answer = pw.post_sandbox_claims_timeline(body){
"sender_id": "SAMPLEBILLER",
"claims": [
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Sleep Dentistry",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"npi": "1234567893",
"employerId": "123456789",
"organizationName": "Sample Sleep Dentistry",
"taxonomyCode": "1223S0112X",
"address": {
"address1": "100 Main Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W123456789",
"paymentResponsibilityLevelCode": "P",
"firstName": "Sample",
"lastName": "Patient",
"gender": "F",
"dateOfBirth": "19600214",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "PW-SBX-PAID",
"claimChargeAmount": "2900.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "G4733"
}
],
"serviceLines": [
{
"serviceDate": "20261001",
"professionalService": {
"procedureIdentifier": "HC",
"procedureCode": "E0486",
"procedureModifiers": [
"KX"
],
"lineItemChargeAmount": "2900.00",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
}
}
]
}
},
{
"tradingPartnerServiceId": "99999",
"submitter": {
"organizationName": "Sample Sleep Dentistry",
"contactInformation": {
"name": "Billing Office",
"phoneNumber": "5555550100"
}
},
"receiver": {
"organizationName": "Sample Health Plan"
},
"billing": {
"npi": "1234567893",
"employerId": "123456789",
"organizationName": "Sample Sleep Dentistry",
"taxonomyCode": "1223S0112X",
"address": {
"address1": "100 Main Street",
"city": "Springfield",
"state": "IL",
"postalCode": "627011234"
}
},
"subscriber": {
"memberId": "W12345REJ",
"paymentResponsibilityLevelCode": "P",
"firstName": "Sample",
"lastName": "Patient",
"gender": "F",
"dateOfBirth": "19600214",
"address": {
"address1": "9 Elm Street",
"city": "Springfield",
"state": "IL",
"postalCode": "62701"
}
},
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "PW-SBX-REJ",
"claimChargeAmount": "2900.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "G4733"
}
],
"serviceLines": [
{
"serviceDate": "20261001",
"professionalService": {
"procedureIdentifier": "HC",
"procedureCode": "E0486",
"procedureModifiers": [
"KX"
],
"lineItemChargeAmount": "2900.00",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1"
]
}
}
}
]
}
}
],
"seed": "demo-1",
"start": "2026-10-19T09:00:00Z",
"as_of": "2026-10-21T09:00:00Z"
}{
"usage": "T",
"transmitted": false,
"stored": false,
"run_id": "tl_e5d82a7c305b0437",
"start": "2026-10-19T09:00:00.000Z",
"as_of": "2026-10-21T09:00:00.000Z",
"format": "x12",
"schedule": [
{
"stage": "file_acknowledged",
"kind": "999",
"at": "2026-10-19T09:05:00.000Z",
"file": true,
"events": 1,
"order": 1
},
{
"stage": "claims_received",
"kind": "277CA",
"at": "2026-10-19T10:00:00.000Z",
"file": true,
"events": 2,
"order": 2
}
],
"items": [
{
"sequence": 1,
"at": "2026-10-19T09:05:00.000Z",
"stage": "file_acknowledged",
"file_id": "tl_e5d82a7c305b0437.f1",
"event": {
"id": "evt_60ed631692398d5d8974da74",
"type": "sandbox.file.acknowledged",
"created": 1792400700,
"mode": "test",
"data": {
"acknowledgment": "999",
"interchange_control_number": "000000001",
"group_control_number": "1",
"verdict": "A",
"verdict_words": "Accepted",
"received": 2,
"accepted": 2,
"transaction_sets": [
{
"control_number": "0001",
"verdict": "A"
},
{
"control_number": "0002",
"verdict": "A"
}
]
}
}
},
{
"sequence": 2,
"at": "2026-10-19T10:00:00.000Z",
"stage": "claims_received",
"file_id": "tl_e5d82a7c305b0437.f2",
"event": {
"id": "evt_5fed61838f3988a48c74df2d",
"type": "sandbox.claim.acknowledged",
"created": 1792404000,
"mode": "test",
"data": {
"reference": "PW-SBX-PAID",
"payer_claim_number": "",
"verdict": "A",
"fixes": [
"The claim was received, not yet accepted for adjudication: the payer acknowledges receipt (STC A1:19:PR). Nothing to fix."
]
}
}
}
],
"files": [
{
"id": "tl_e5d82a7c305b0437.f1",
"stage": "file_acknowledged",
"kind": "999",
"at": "2026-10-19T09:05:00.000Z",
"x12": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*0905*^*00501*000000001*0*T*:~GS*FA*PWSANDBOX*SAMPLEBILLER*20261019*0905*1*X*005010X231A1~ST*999*0001*005010X231A1~AK1*HC*1*005010X222A1~AK2*837*0001*005010X222A1~I…"
},
{
"id": "tl_e5d82a7c305b0437.f2",
"stage": "claims_received",
"kind": "277CA",
"at": "2026-10-19T10:00:00.000Z",
"x12": "ISA*00* *00* *ZZ*PWSANDBOX *ZZ*SAMPLEBILLER *261019*1000*^*00501*000000002*0*T*:~GS*HN*PWSANDBOX*SAMPLEBILLER*20261019*1000*2*X*005010X214~ST*277*0001*005010X214~BHT*0085*08*PWSANDBOX2*20261019*1000*TH~HL*1**20*1~NM…"
}
],
"claims_837p": "ISA*00* *00* *ZZ*SAMPLEBILLER *ZZ*PWSANDBOX *261019*0900*^*00501*000000001*0*T*:~GS*HC*SAMPLEBILLER*PWSANDBOX*20261019*0900*1*X*005010X222A1~ST*837*0001*005010X222A1~BHT*0019*00*PW-SBX-PAID*20261019*0900*CH~NM1*41*2…",
"control": {
"interchange": "000000001",
"group": "1",
"sets": [
"0001",
"0002"
]
},
"claims": [
{
"reference": "PW-SBX-PAID",
"state": "accepted",
"payer_claim_number": "PWS2292711347"
},
{
"reference": "PW-SBX-REJ",
"state": "rejected",
"payer_claim_number": ""
}
],
"checked": [
{
"reference": "PW-SBX-PAID",
"warnings": [],
"repairs": [],
"not_checked": []
},
{
"reference": "PW-SBX-REJ",
"warnings": [],
"repairs": [],
"not_checked": []
}
],
"next_cursor": "tl_e5d82a7c305b0437.5",
"has_more": false,
"next_event_at": "2026-11-02T09:00:00.000Z",
"complete": false,
"events_total": 6
}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 |
|---|---|---|
usage | the value "T" | |
transmitted | the value false | |
stored | the value false | |
run_id | string | |
start | string | |
as_of | string | |
format | one of "x12", "report", "both" | |
schedule | list of object | |
items | list of object | |
files | list of object | |
claims_837p | string | The 837P the run sent (first read only). |
control | object | First read only. |
claims | list of object | |
checked | list of object | |
next_cursor | string | Pass as cursor with a later as_of. |
has_more | boolean | More events are already due: read again before moving as_of. |
next_event_at | string or null | |
complete | boolean | |
events_total | integer |
POST/v1/claims/submit
Send claims to a payer
Not offered yet: Payerworks is connected to no payer, so this answers 501 submit_not_offered with each gate and whether it is open (sending switched on, a live key, a signed business associate agreement recorded for your account, a trading partner for the payer, and that partner switched on). Nothing is written or sent. Once every gate is open it writes your claims as an 837P exactly as POST /v1/claims/837p does, under the partner’s interchange ids and a control number Payerworks assigns, and hands the file to the partner; transmitted is true only when the partner’s connection accepted the file. Every patientControlNumber begins with your account’s reference prefix, and one already in flight is refused unless it was rejected or the claim is a replacement or a void. The partner’s 999, 277CA and 835 arrive as submission events to the key that sent the file, never to anyone else. Send an Idempotency-Key: a retry under it answers the first answer and sends nothing again.
Request
curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/claims/submit" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d @request.jsonWith the JavaScript client
const answer = await pw.postClaimsSubmit(body);With the Python client
answer = pw.post_claims_submit(body){
"claim": {
"tradingPartnerServiceId": "60054",
"receiver": {
"organizationName": "SAMPLE HEALTH PLAN"
},
"submitter": {
"organizationName": "Sample Dental",
"contactInformation": {
"name": "BILLING OFFICE",
"email": "billing@sample.test"
}
},
"billing": {
"organizationName": "Sample Dental",
"npi": "1234567893",
"employerId": "12-3456789",
"taxonomyCode": "1223S0112X",
"address": {
"address1": "100 Sample St",
"city": "Provo",
"state": "UT",
"postalCode": "84601-1234"
},
"contactInformation": {
"name": "BILLING OFFICE",
"phoneNumber": "(801) 555-0100"
}
},
"subscriber": {
"memberId": "TESTMEMBER01",
"paymentResponsibilityLevelCode": "P",
"firstName": "JANE",
"lastName": "DOE",
"gender": "F",
"dateOfBirth": "1960-02-03",
"groupNumber": "GRP100",
"address": {
"address1": "9 Test Ave",
"city": "Provo",
"state": "UT",
"postalCode": "84601"
}
},
"rendering": {
"npi": "1922222223",
"firstName": "JOHN",
"lastName": "DOE"
},
"claimInformation": {
"claimFilingCode": "CI",
"patientControlNumber": "SDX-1001",
"claimChargeAmount": "250.00",
"placeOfServiceCode": "11",
"claimFrequencyCode": "1",
"signatureIndicator": "Y",
"planParticipationCode": "A",
"benefitsAssignmentCertificationIndicator": "Y",
"releaseInformationCode": "Y",
"healthCareCodeInformation": [
{
"diagnosisTypeCode": "ABK",
"diagnosisCode": "G47.33"
},
{
"diagnosisTypeCode": "ABF",
"diagnosisCode": "R06.83"
}
],
"serviceLines": [
{
"serviceDate": "2026-10-01",
"providerControlNumber": "PW-SELF-1-L1",
"professionalService": {
"procedureIdentifier": "HC",
"procedureCode": "99213",
"procedureModifiers": [
"25"
],
"lineItemChargeAmount": "250.00",
"measurementUnit": "UN",
"serviceUnitCount": "1",
"compositeDiagnosisCodePointers": {
"diagnosisCodePointers": [
"1",
"2"
]
}
}
}
]
}
}
}{
"error": {
"code": "submit_not_offered",
"message": "Payerworks does not send this claim yet: `gates` names each gate and whether it is open. Nothing was written or sent; write the 837P with POST /v1/claims/837p and send it on the connection you have.",
"gates": [
{
"gate": "service",
"open": false,
"sentence": "Sending claims is not switched on for Payerworks yet."
},
{
"gate": "live_key",
"open": null,
"sentence": "Not checked: a gate before it is closed."
}
],
"connection": "Payerworks is connected to no payer.",
"transmitted": false
}
}Every call is answered this way today. The answer once every gate is open is described, field by field, below and in /openapi.json.
| Field | Type | What it is |
|---|---|---|
submission_id | string | |
partner_id | string | |
partner_name | string | |
usage | the value "P" | |
interchange_control_number | string | ISA13, assigned by Payerworks. |
group_control_number | string | GS06. |
claims | list of object | |
transfer_id | string | The partner connection’s id for the transfer that accepted the file. |
sent_at | string | |
acknowledgments | string | Where the partner’s answers arrive. |
transmitted | the value true | Only once the partner’s connection accepted the file: every other answer is a refusal, with transmitted: false. |
warnings | list of FieldProblem |
GET/v1/partners
Trading partners
The trading partners claims go to through POST /v1/claims/submit today, with the payer ids each takes and the transactions it carries, and one sentence about Payerworks’ connections. Today the list is empty: Payerworks is connected to no payer.
Request
curl -sS -X GET "$PAYERWORKS_BASE_URL/v1/partners" \
-H "Authorization: Bearer $PAYERWORKS_API_KEY"With the JavaScript client
const answer = await pw.getPartners();With the Python client
answer = pw.get_partners(){
"connection": "Payerworks is connected to no payer.",
"partners": []
}| Field | Type | What it is |
|---|---|---|
connection | string | The one sentence about Payerworks’ connections; today: Payerworks is connected to no payer. |
partners | list of object | Empty today. |
Reading the answer
- A validate answer is
validand, per claim,errors,warnings,repairs(the formatting Payerworks fixed on a copy: phone punctuation, a ZIP+4 hyphen, letter case, a diagnosis code’s dot) andnot_checked(each check that could not run, with why). Passing means well formed and valid on the date of service, never that a payer will pay. - Each claim answer carries back your patientControlNumber as
reference, so the answer matches your claim. - A written file comes back as
x12, with its interchange, group and transaction set control numbers andtransmitted: false.
Troubleshooting
invalid_claims(422): At least one claim would be refused, so nothing was written. Each claim’s errors name the field; fix them and send the whole set again.duplicate_reference(422): Two claims carry the same patientControlNumber. Each must be unique in one call, because the answers match back on it.- A value holding a character X12 reserves (* : ^ ~) is refused and named by field, never silently rewritten.
- A CPT code is checked for its shape only, and a dental D code or a CPT modifier is listed as not checked: CMS’s HCPCS file carries neither.
sandbox_test_only(400): The sandbox answers test interchanges only: leave usage out, or send T.invalid_sandbox_attachments(422): A 275 sent back to the sandbox as attachments_275 could not be read (at most five, each a test 275’s X12 text): nothing was run.adjudication_unknown(422): A correction plan needs to know whether the payer processed the claim: send its payer claim number, oradjudicated: false.submit_not_offered(501): A gate on a real send is closed:gatesnames each, with whether it is open. A 501 is never retried by the clients: it will not pass by waiting. Write the 837P with POST /v1/claims/837p and send it on the connection you have.reference_prefix_required(422): Every patientControlNumber you send begins with your account’s reference prefix, which Payerworks records with your business associate agreement.
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 |
|---|---|---|
cursor_other_run | 400 | This cursor belongs to another timeline run: the claims, the seed or the start differ from the run that made it. |
invalid_adjudicated | 400 | adjudicated is true or false: true says the payer processed the claim even when its number is not at hand. |
invalid_change | 400 | change is "replace" (correct a claim) or "void" (cancel it). |
invalid_correction_claim | 400 | original and replacement are each one claim in the 837P JSON shape POST /v1/claims/837p takes. |
invalid_edit_code | 400 | An edit code is snake_case letters, digits and underscores, at most 64 characters, such as future_date. |
invalid_edit_filter | 400 | A filter on GET /v1/edits is snip_type (1 to 7), severity (error or warning), kind (deterministic or code_set) or runs_in (edits, validateClaim, validateSecondaryClaim or correction-plan); the message names the one that is not. |
invalid_format | 400 | format is "x12", "report" or "both". |
invalid_instant | 400 | start and as_of are moments written in ISO 8601 with a time and a zone (such as 2026-10-19T09:00:00Z), from the year 2000 to 2099, and as_of is not before start. |
invalid_medicare_mac | 400 | medicare_mac is true or false. |
invalid_partner_id | 400 | partner_id is a partner's id as GET /v1/partners lists it, or left out to send to the one partner taking the claims' payer. |
invalid_payer_claim_number | 400 | payer_claim_number is the payer's own number for the claim, at most 50 characters and none of the X12 delimiters (~ * : ^). |
invalid_row_offset | 400 | row_offset is a whole number from 0 to 1000000000: the rows of the whole file before the first data row of this piece. |
invalid_seed | 400 | seed is your own string for the run, 1 to 64 of A-Z, a-z, 0-9, _ and -: the same seed, claims and start give the same run. |
invalid_timeline_cursor | 400 | cursor is the next_cursor an earlier timeline answer gave, unchanged. |
invalid_timeline_limit | 400 | limit is a whole number from 1 to 500. |
no_claim | 400 | The body has no claim: send claim (or claims) in the 837P shape the docs describe. |
no_mrf | 400 | Send the file's text as csv (the tall or wide CSV template) or the file as json (an object, or its text). |
no_rules | 400 | Send the rules as rules, a list of one or more rule objects. |
no_x12 | 400 | Send the file's text as x12. |
sandbox_test_only | 400 | A sandbox payer answers test interchanges only: usage is "T" or left out. |
submit_envelope_assigned | 400 | On a submission Payerworks sets the interchange: leave out sender_id, receiver_id, the two qualifiers, control_number and usage. |
too_many_claims | 400 | At most 100 claims a call. |
too_many_rules | 400 | At most 100 rules a call. |
test_key_production_file | 403 | A test key writes test interchanges only (ISA15 = T). Use a live key for a production file. |
edit_not_found | 404 | No edit has this code: GET /v1/edits lists every edit Payerworks runs and the ones it does not. |
reference_in_flight | 409 | A claim with this patientControlNumber was already sent to this partner and has not been rejected; a corrected claim (frequency 7 or 8) may reuse it. |
mrf_too_large | 413 | The file is longer than 1990000 characters, or holds more than 50000 rows or 50000 items: check it in pieces, the first three rows sent again with each piece and row_offset set. |
adjudication_unknown | 422 | Say whether the payer processed the claim: send payer_claim_number (CLP07 on the 835, REF*1K on the 277CA) when it did, or adjudicated: false when it was rejected before processing (a 999 or 277CA rejection). Sending a processed claim again as a new one is a duplicate. |
claim_type_not_planned | 422 | claim_type is "professional" or "dental": an institutional claim carries its frequency in the type of bill, which this plan does not cover yet. |
dental_not_checked_here | 422 | A dental claim sent as an 837D is read where the API runs (POST /v1/claims/correction-plan), not on this page: send it as JSON here, or call the API. |
duplicate_reference | 422 | Two claims carry the same reference (patientControlNumber, CLM01); each must be unique so its answers match back. |
invalid_claims | 422 | One or more claims would be refused; nothing was written or run. Each claim's errors are listed. |
invalid_rules | 422 | One or more rules are not written in the rule format; nothing was applied. Each rule's problems are listed. |
invalid_sandbox_attachments | 422 | A 275 sent back to the sandbox cannot be read; nothing was run. Each problem is listed with its field. |
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. |
mrf_not_json | 422 | json is not a JSON document that can be read. |
not_an_837d | 422 | With claim_type dental, original_x12 and replacement_x12 are each a one-claim 837D interchange (GS08 005010X224A2). |
not_an_837p | 422 | An x12 read as claims (original_x12 and replacement_x12 on POST /v1/claims/correction-plan, x12 on POST /v1/claims/validate) is an 837P interchange (GS08 005010X222A1). |
not_read_here | 422 | This file is a kind Payerworks recognizes but does not read here yet; the error names its kind. |
payer_claim_number_needed | 422 | The payer processed the claim, so the plan needs its claim number: it is CLP07 on the 835, REF*1K on the 277CA, or the number a claim status answer gives. |
payer_not_at_partner | 422 | A claim names a payer this partner does not take claims for; send it in a call of its own to the partner that does. |
reference_prefix_required | 422 | Every claim's patientControlNumber must begin with your account's reference prefix, so each answer can be matched to you alone; the error names the prefix and the claims. |
several_claims_in_file | 422 | original_x12 and replacement_x12 each hold exactly one claim: split a bulk file with POST /v1/x12/parse first. |
unrecognized_x12 | 422 | This is not an X12 file Payerworks reads; the message lists the kinds it reads. |
submit_not_offered | 501 | Payerworks does not send this claim yet: gates names each gate and whether it is open. Nothing was written or sent; write the 837P with POST /v1/claims/837p and send it on the connection you have. |
timeline_not_offered | 501 | The sandbox timeline is not offered where this was asked: it is not connected to the claim checks here, so nothing was run. This is not a passing fault, so sending the request again answers the same. |
submit_not_sent | 503 | The file was written but the partner's connection did not take it just now, so nothing was sent (transmitted: false). Send the call again. |
Code lists
The claims sandbox’s member ID endings
| Ending | Outcome | What it answers |
|---|---|---|
REJ | rejected | A member ID ending in REJ is rejected by the payer’s front end. The 277CA refuses the claim with STC A7:164:IL (the subscriber’s member number is invalid), and no remittance follows. |
DENY | denied | A member ID ending in DENY is accepted on the 277CA and then denied on the 835 the way payers send a refusal: claim status 1 (processed), nothing paid, the whole charge adjusted under CO 50, and each line carrying remark N115, so only the adjustments show the refusal. |
PEND | pending | A member ID ending in PEND is accepted on the 277CA and stays with the payer, so no remittance line comes back yet. |
DED | deductible | A member ID ending in DED is accepted and paid, but most of what the payer allows is applied to the patient’s deductible (PR 1), so the payer pays only the rest, the patient owes the deductible, and the remainder of the charge is a contractual write-off (CO 45). |
COPAY | copay | A member ID ending in COPAY is accepted and paid less a fixed copay the patient owes (PR 3), and the remainder of the charge is a contractual write-off (CO 45). |
D16 | lacks_information | A member ID ending in D16 is accepted and then refused on the 835 for missing information: nothing is paid, every line is adjusted under CO 16 with remark M51 (a procedure code is missing or invalid), and the claim status code says processed, so only the adjustments show the refusal. |
D97 | bundled | A member ID ending in D97 is paid except for its last line, which the payer bundles into another service (CO 97, remark M15) and pays nothing for. A claim of one line has that line bundled, so nothing is paid. |
REV | reversed_and_repaid | A member ID ending in REV comes back as a correction: the 835 first reverses an earlier payment on the claim (claim status 22, every amount negated), then pays the claim again on a higher allowed amount, so the check carries only the difference. |
PLB | provider_adjustment | A member ID ending in PLB is paid, and its check also carries a provider-level adjustment: the payer recovers an overpayment on an earlier claim (PLB reason WO), so the check is less than the claims it pays. |
XOVER | forwarded | A member ID ending in XOVER is paid as primary and forwarded to the patient’s secondary payer (claim status 19, the secondary named as the crossover payer, remark MA18), so it is not filed to the secondary by hand. |
RFAI | information_requested | A member ID ending in RFAI is accepted on the 277CA and then held for a document: the payer sends a 277 request for additional information asking for a progress note by a day thirty days later, and pays nothing until a solicited 275 answers it. Send the same claims again, to the same sandbox route (professional, institutional or dental), with that 275 in attachments_275, and the claim is paid as any other. |
| `` | paid | Any other member ID is accepted and paid: the payer allows part of the charge, the patient owes coinsurance on what was allowed (PR 2), the rest is a contractual write-off (CO 45), and every service line carries its share to the cent. |
The file kinds POST /v1/x12/parse names
270, 271, 276, 277, 277CA, 277RFAI, 278, 835, 837P, 837I, 837D, 999, 997, TA1, mixed, unknown
The sandbox timeline’s stages
| Stage | After | File | Event |
|---|---|---|---|
file_acknowledged | 5 minutes | 999 | sandbox.file.acknowledged |
claims_received | 1 hours | 277CA | sandbox.claim.acknowledged |
payer_acknowledged | 2 days | 277CA | sandbox.claim.acknowledged |
remittance | 14 days | 835 | sandbox.remittance.received |
The five gates on a real send
Payerworks is connected to no payer.
| Gate | What it says while closed |
|---|---|
service | Sending claims is not switched on for Payerworks yet. |
live_key | A test key never sends a claim. Run the whole loop with test data on POST /v1/sandbox/claims, or use a live key. |
baa | No signed business associate agreement is recorded for this account. Payerworks records one with you before any claim is sent. |
partner | No trading partner Payerworks sends to takes claims for this payer yet. |
partner_switch | The trading partner for this payer is set up, but sending to it is not switched on yet. |
Example
claims.mjs runs every step below against the API with a test key. It needs payerworks.mjs and sample-data.mjs beside it.
// Payerworks example: claims, checked and written as an 837P. Docs: https://payerworks.com/docs/claims
//
// 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 claims.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, SENDER_ID, PAYER_ID, copy, refusalOf } from './sample-data.mjs';
/** @param {Payerworks} pw */
export async function run(pw) {
// 1. Check the claim the way a payer's front end would.
const checked = await pw.postClaimsValidate({ claim: copy(CLAIM) });
// 2. Write it as an 837P. Nothing is written when any claim would be refused.
const written = await pw.postClaims837p({ sender_id: SENDER_ID, receiver_id: PAYER_ID, control_number: 7, claims: [copy(CLAIM)] });
// 3. Read the file back to the same JSON.
const read = await pw.postX12Parse({ x12: written.x12 });
// 4. The failure path: an NPI that fails its check digit and a charge that is not its lines' total.
const broken = copy(CLAIM);
broken.billing.npi = '1234567890';
broken.claimInformation.claimChargeAmount = '300.00';
const refused = await refusalOf(() => pw.postClaims837p({ sender_id: SENDER_ID, receiver_id: PAYER_ID, control_number: 8, claims: [broken] }), { PayerworksError });
// The same claim on validate is answered, with every reason listed.
const reasons = (await pw.postClaimsValidate({ claim: broken })).claims[0].errors.map((e) => e.code);
// 5. Sending through a trading partner is shut while Payerworks is connected to no payer: the answer
// names each of the five gates and whether it is open, and nothing is written or sent.
const partners = await pw.getPartners();
const shut = await refusalOf(() => pw.postClaimsSubmit({ claim: copy(CLAIM) }), { PayerworksError });
return {
valid: checked.valid,
written: { transmitted: written.transmitted, control: written.interchange_control_number },
read_kind: read.kind,
refused,
reasons,
connection: partners.connection,
submit: shut,
};
}
// 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));
}
{
"valid": true,
"written": {
"transmitted": false,
"control": "000000007"
},
"read_kind": "837P",
"refused": {
"status": 422,
"code": "invalid_claims",
"request_id": "req_4"
},
"reasons": [
"invalid_npi",
"charge_does_not_balance"
],
"connection": "Payerworks is connected to no payer.",
"submit": {
"status": 501,
"code": "submit_not_offered",
"request_id": "req_7"
}
}