Headless. Every capability is an API call.

Five sandboxes answer the way a payer and its front end would. Claims sent to POST /v1/sandbox/claims come back in the answer to one call as a 999, a 277CA and an 835, every file explained and, once you set a webhook, posted as events too; institutional and dental claims sent to POST /v1/sandbox/claims/837i and /837d come back the same way, with no events. Eligibility questions sent to POST /v1/sandbox/eligibility come back as a 271, claim status questions sent to POST /v1/sandbox/claim-status as a 277, and prior authorization requests sent to POST /v1/sandbox/authorizations as a 278 response, each explained, with no events. Enrollment has the fifth, the sandbox payer PWSANDBOX, below. Every file is a test file. Use invented patients only.

How the subscriber’s member ID ends decides each answer, and each sandbox reads only its own list.

Claims POST /v1/sandbox/claims

Eligibility POST /v1/sandbox/eligibility

Each 271 the eligibility sandbox writes can be read back in the JSON grouped by plan as well: send it to POST /v1/eligibility/explain with ?include=answer&shape=plans, and the same answer is explained the same from either.

Claim status POST /v1/sandbox/claim-status

A claim status question follows the claims list, so it agrees with that claim’s 277CA and 835: the same payer claim number and the same paid amount. These endings are the status sandbox’s own, the answers a status question alone can get:

One exception: when a claim’s payment depends on its service lines (member IDs ending in D97), the status answer says the claim is finalized and leaves what was paid to the remittance, because a status question carries no lines. The claim status sandbox answers test files only: a 276 marked for production use is refused.

Prior authorization POST /v1/sandbox/authorizations

It answers from the same payer as the eligibility sandbox, and the endings the two share answer alike: a member the eligibility sandbox cannot find is not found here either, and a claim the claims sandbox denies is not certified here. These are its endings:

Every answer is a test interchange from the payer id PWSANDBOX. Run them in your browser.

curl "$PAYERWORKS_BASE_URL/v1/sandbox/claims" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sender_id": "SAMPLEBILLER", "claims": [ … ] }'

Write the 270 from the JSON your system already holds, send it on your own connection, and give Payerworks the 271 that comes back, as X12 or as JSON. The answer is said per patient, in words.

• A deductible or out-of-pocket figure is read only inside its own network tier, coverage level, insurance type and period. When a payer states several, such as Medicare Part A and Part B, or last year and this year, each is said under its own type and dates, and none is dropped.
• In network and out of network are the plan’s benefit tiers as the payer stated them. A 271 does not say whether a provider participates with the plan, and the answer never says it does.
• A refusal is said as the next step by the payer’s own follow-up code: correct these fields, ask again later, or do not send it again.
• Whether the plan covered the day you asked about is read inside both the plan’s dates and the member’s own eligibility dates, from the later begin to the earlier end, so a member whose coverage ended before the plan year did is not covered after it. Where a payer states coverage separately for each insurance type, such as Medicare Part A active and Part B not, each is said with its own state.
• A figure the payer did not state is null, never zero.
• The answer may come as an X12 271, as the flat JSON list of benefits most clearinghouse APIs return, or as that JSON grouped by plan with each kind of benefit in its own list. The three forms of one answer explain the same; what the grouped shape holds that is not read is listed as not read, and an entry the sender set aside is read as the payer stated it, and said.
• A question can ask about procedures as well as service types. One that asks only about procedures asks no service type beside them, and a question that uses no procedure field is written exactly as before.

# Write the 270 from your JSON, send it on your own connection, then explain the 271 that comes back.
curl "$PAYERWORKS_BASE_URL/v1/eligibility/270" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d @question.json
curl "$PAYERWORKS_BASE_URL/v1/eligibility/explain" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile x12 answer.271 '{ x12: $x12, asked: { service_type_codes: ["30", "98"] } }')"

Write the 276 from the JSON your system holds, send it on your own connection, and give Payerworks the 277 that comes back, as X12 or as JSON. Each question is answered with where the claim stands, the money, the next step and when to ask again.

• A claim the payer cannot find in its first few business days is not loaded yet, never rejected; after that, the answer says to confirm the payer received it.
• A payer whose system did not answer is asked again the next business day. A question the payer refused because of its own data is corrected first, never asked again unchanged.
• Finalized is not the same as paid: a finalized answer that states no amount leaves the money to the remittance.
• Business days are Monday to Friday, and holidays are not counted.
• The payer’s own claim number (REF*1K) and the clearinghouse’s trace number (REF*D9) are said apart, so one is never taken for the other.
• A file holding more than one call can read is refused before it is read, naming what was counted and the limit: split it.

# Write the 276, send it on your own connection, then explain the 277 that comes back.
curl "$PAYERWORKS_BASE_URL/v1/claim-status/276" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d @inquiry.json
curl "$PAYERWORKS_BASE_URL/v1/claim-status/explain" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile x12 answer.277 '{ x12: $x12, asked: { submitted_on: "2026-10-05" } }')"

Send the claim (JSON or the 837P), and the 999s, 277CAs and 835s you hold for it. Payerworks answers where each claim stands, who said so, what was paid, and a dated timeline of every file. It reads only what you send: nothing is stored and no payer is asked.

submitted

Sent, and no acknowledgment of this submission is among the files you sent.

received

Received, and not yet accepted for adjudication: a receipt is not an acceptance.

accepted

Accepted into the payer's adjudication system, and being processed.

information_requested

The payer asked for more information before it decides the claim (a 277 request for additional information), and no 275 among the files you sent answers it.

rejected

Rejected before adjudication: the payer never decided it, and no remittance follows a rejection.

processed

Adjudicated: the payer accepted responsibility for the claim. That is not the same as paid in full, or paid at all.

denied

Adjudicated and denied: the payer decided it is not responsible for the claim.

unknown

No single state can be read from the files: the answers are mixed or incomplete, or use codes a claim acknowledgment does not carry.

• A remittance decides first; then the acknowledgments, a rejection before anything else and the payer’s word before a clearinghouse’s; then the newest date. A late receipt never hides a rejection.
• An accepting 999 moves nothing: it says the file was read, not that the claim was taken.
• Only the latest submission of a claim counts, and a corrected claim joins the claim whose payer claim number it names.
• An 835 sent twice is counted once and named, never added to the paid total twice.
• A reversal whose original decision is not among the files you sent is named on the timeline but left out of the paid total.

curl "$PAYERWORKS_BASE_URL/v1/claims/track" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile c claims.837 --rawfile a ack.277 --rawfile r remit.835 '{ x12_837: $c, acknowledgments: [$a], remittances: [$r] }')"

Send an 835, or the claims as JSON, and each claim comes back with what the payer did and what to do about it.

• The verdict is read from the money and the adjustment codes, never the claim status code alone: a refusal usually arrives as “processed as primary” with a CO-50 or a CO-16 beside it.
• Whether the patient may be billed is said in dollars, by group: patient responsibility may be billed, a contractual adjustment may not.
• A correction is said as the fields to send on the replacement claim, and a request for records names what to send.
• A deadline is computed only from a regulation it cites (Medicare fee-for-service, by its filing indicator) or from the limits you send. Otherwise its date is null, and its words say the payer’s contract or provider manual states it.
• An appeal letter is written by template from your facts only, and a letter you edit can be checked against them before it goes.
• An underpayment letter states one of two bases, from your figures: a contracted amount above what the payer allowed, or a payment below the allowed amount less the patient’s share. With neither, no letter is written.
• A Medicare late filing (CO-29) is said as not appealable, and a Medicare duplicate (CO-18) as a reopening, each with the regulation it rests on. A Medicare filing limit counts from the earliest service line’s date, and a Medicare redetermination or reopening window from the remittance advice’s own date (DTM*405), else the payment date (BPR16).

# Every claim in an 835, said as the next step.
curl "$PAYERWORKS_BASE_URL/v1/denials/next-step" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile x12 remittance.835 '{ x12: $x12, facts: { filing_limit_days: 90 } }')"

# An appeal letter from your facts, by its kind.
curl "$PAYERWORKS_BASE_URL/v1/appeals/letter" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" -H "Content-Type: application/json" \
  -d @letter.json

Follow up on open claims, check the remittances that come back, and count what your own files show. Each answer reads only what you send in the call.

• A payer’s days to pay, its denial rate or an overturn rate is learned from your files alone, with how many it rests on, and is read as a pattern only past a floor (five paid claims, five decided appeals, two refusals of one reason). Below the floor the answer says there is not enough history. Payerworks holds no data of its own about any payer, so nothing here is a benchmark.
• A month is the calendar month; the current month counts to today.
• A claim the payer’s search did not find gets the next questions to ask in order, each built from your own question and the facts you hold, never a value nobody gave.
• Two checks are one payment only when their trace number and its originator agree, and a deposit is matched by amount and date only when exactly one check fits.
• A line with no rate in your fee schedule is said as no rate given, never read as zero, and Medicare’s published rate is labeled as Medicare’s, never as your contract.

Write the 278 from JSON, send it the way the payer takes it, and give Payerworks the response that comes back. Payerworks sends nothing.

• Whether a payer takes a 278 at all is the payer’s choice: many take prior authorizations only on a portal, by fax or by phone. Every answer that writes a file says so.
• A response is read by its decision code: a request the payer never reviewed is said as not reviewed, never as denied, and a pend that asks for something is said as waiting on more information.
• The certification number goes on the claim by the request’s kind: an authorization’s as the prior authorization number, a referral’s as the referral number, and only when something was approved.
• The Medicare lists are dated copies of CMS’s own, said with their dates, and a code on neither is not on the lists held, never not required. A CPT code is held by its number only.
• The FHIR output is the Da Vinci PAS bundle’s shape, built from the guide’s published pages and examples; it has not been run through the HL7 validator.

Estimates, a Good Faith Estimate, an equipment replacement window and a poverty guideline percent, each figured from what you send.

• An estimate never supplies an allowed amount, and a benefit the 271 did not state is said as not stated, never read as zero.
• Whether a copay replaces the deductible and coinsurance, or comes first, is plan design a 271 does not carry: you say which.
• A Good Faith Estimate is your document. Payerworks lays it out with every element the regulation lists, and issues, delivers and keeps nothing.
• The replacement window checks no Medicare record, and the poverty guideline is the 2026 table, named and dated; another year is refused.

The paper side of the same claims and answers, drawn from what you send: the CMS-1500, a remittance laid out for reading, an eligibility answer as a summary, CMS’s own Medicare appeal forms filled in, and a claim’s attachments as an X12 275. Each PDF comes back in the answer as base64 with its SHA-256; Payerworks keeps no copy and sends nothing.

• A CMS-1500 is the claim POST /v1/claims/837p would write: the same checks refuse it the same way, and the form draws the repaired claim. Six service lines go on a form and a claim takes as many forms as it needs, each Box 28 the total of its own lines. Boxes 12 and 31 are dated only when you send signed_on.
• form: full draws CMS’s own form under the data; data_only draws the data alone, to print onto pre-printed red forms. A value too wide for its box is set smaller, never cut, and the answer names it.
• The remittance and the eligibility summary are drawings of the explain answers, POST /v1/remittances/explain and POST /v1/eligibility/explain, never a second reading: every figure is the one those routes give, and a figure the file did not state is left blank.
• The Medicare appeal forms are CMS’s published files, unaltered but for the fields typed in: the redetermination request (CMS-20027) and the reconsideration request (CMS-20033), for Original Medicare only. Nothing is signed, dated or ticked for you; the deadline comes with the regulation it is counted under, and a request past it with no reason given is warned.
• A 275 carries each attachment under the control number the claim’s PWK segment announced with transmission EL, and a control number the claim did not announce is refused. A claim that announces an attachment this way is told so when it is validated, so it does not wait for a file that never comes.
• The 275 is written as public payer companion guides show it, not from the licensed implementation guide, and the answer says so: check your payer’s own guide before you send one.
• A LOINC code you give for an attachment’s kind is checked by its check digit, and named in LOINC’s own words where Payerworks holds it.

LOINC

This material contains content from LOINC (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.

Two routes read a picture with a model: a paper explanation of benefits into a draft 835, and an insurance card into the payer, the member ID and the payer directory’s rows. Both are built and switched off until Payerworks turns them on, route by route (until then each answers 501 model_read_not_offered, which is not retried), and then answer test keys only until an agreement covers the model for live data.

• A paper EOB comes back as a draft, never an ERA, and nothing is posted: every value with the reader’s confidence and where on the page it was read. The payments are checked against the check total the page states by arithmetic, never by the model, and a difference is said with both figures. The draft 835 is a test interchange whatever your key, and an element the page did not print is left empty and named.
• A card is read twice, and a member ID the two reads spell differently is said. A plan type is given only beside words the card prints, and an electronic payer ID printed on the card is shown only where a payer publishes it, because one misread character is another payer’s ID. A match in the directory says the directory holds published facts about that payer, never that a claim can be sent to it.
• Send one page, or two at most, up to 1.4 MB. A read that cannot finish inside one call is refused with what to send instead; it is never kept to finish later.
• An account’s keys together may make 100 reads a UTC day on each route. A call refused for the route being off, a live key or a body with no file is not counted. Neither route takes an Idempotency-Key, so a second call is a second read.
• With a test key, send invented documents only. Nothing stops a real EOB or a real card from being sent with one, and no business associate agreement covers the model for it, so never send one. The picture is read and forgotten: never stored, never logged.

Three routes for what your own system must hold to: your own claim rules, a hospital’s standard charges file, and the claims sandbox over the days a real claim takes.

• POST /v1/edits/rules/check takes rules you write for your own payers: a field’s path, an operator from a fixed list of twenty, a value, your message and whether it is an error or a warning. Each rule is checked for the format and applied to the claims you send with it, and the same rules may be sent as rules on POST /v1/claims/validate and POST /v1/claims/837p, where one of severity error refuses the claim and 837p writes nothing. A rule fires on the fault it names, says your own words and is marked source: caller, so it never reads as a Payerworks edit.
• A rule’s pattern is a small fixed format, never code, and each call has a step budget: a rule it does not reach is listed as not checked, never as passed. Nothing is stored.
• POST /v1/price-transparency/validate holds a hospital’s standard charges file, the tall or wide CSV or the JSON, to CMS’s version 3.0.0 template and schema, read from CMS’s own repository at one commit. Each problem names its row or path, the column and the rule; Payerworks’ own advice comes as warnings, never as a fault. Nothing is hosted, published or kept.
• POST /v1/sandbox/claims/timeline spreads the claims sandbox over simulated days: 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 a later as_of and the cursor you were given to read what came next; a poller steps the clock, and a webhook handler is tested by posting each item’s event to it. Nothing is stored: the same seed, claims and start give the same run, and Payerworks posts none of its events.

Three things stand between a provider and a payer’s files. Credentialing is the payer checking the provider. Payer enrollment is the provider joining the payer’s plans. Both are the provider’s own work with each payer, and Payerworks does neither. Transaction enrollment registers a provider to exchange one kind of file with one payer through one clearinghouse. That is what these routes ask Payerworks for. Payerworks is not yet registered with any payer, so today a request waits with Payerworks and nothing is sent; the sandbox payer runs the whole path so you can build against it now.

• Make a provider once: its name, billing NPI, tax id and contacts. Then one request per provider, payer and transaction.
• Every request says whose turn it is: yours, the provider’s, Payerworks’ or the payer’s. When it is the provider’s, its tasks say what to do, in rank order, each with its instructions, links and fields of text or a PDF. Payerworks’ own tasks are listed too, so a task held up by one of them names it.
• Every request keeps the history of each status change, and every change raises one event, numbered by sequence, so a receiver can order and dedupe them without trusting the order they arrive in.
• A request can be changed until it is sent to a payer, and canceled in any open status. Every POST takes an Idempotency-Key, so a retried create answers the same request.

The four transactions

eligibility

Eligibility and benefits: Payerworks writes the 270 and reads the 271.270/271

claim_status

Claim status: Payerworks writes the 276 and reads the 277.276/277

professional_claims

Professional claims: Payerworks writes and checks the 837P.837P

remittances

Remittances: Payerworks reads and explains the 835.835

A request for anything else is refused (transaction_not_built), because Payerworks does not yet enroll for it: institutional_claims, dental_claims, attachments, eft, coordination_of_benefits, insurance_discovery, medicare_number_lookup. 999 and 277CA acknowledgments are never enrolled on their own: they come back on the route the claim went.

Each status, and whose turn it is

You never write a status: no write route takes one.

Why a request is Payerworks’ turn

A request at payerworks_action_required carries reason_code, said in these words ({x12} and {payer} are the request’s):

route_not_open

Waiting on Payerworks. Payerworks is not yet registered to exchange {x12} files with {payer}, so nothing has been sent to the payer. Your request waits here, and you can change or cancel it until it is sent.

preparing

Waiting on Payerworks. Payerworks is preparing what the payer asks for.

reviewing

Waiting on Payerworks. Payerworks is checking the answers the provider gave.

Today Payerworks has no payer route open yet, so no live request is with a payer or live. A live request you submit goes to payerworks_action_required with reason_code route_not_open, and the answer to the create or the submit says so in a warning. From there Payerworks staff may ask the provider for a task, or reject or cancel it, but nobody can mark it with the payer or live until the route opens.

What each payer asks

• GET /v1/enrollment-requirements/{payer_id} answers for every payer id: per transaction, whether Payerworks’ route is open, who files, the fields needed and each step the payer publishes, with its source and the day Payerworks read it.
• Payerworks holds published steps for the four Medicare DME MACs and CMS’s HETS. Every other payer answers published: false, which means Payerworks holds no facts for it, never that nothing is required.
• Payerworks states no timeframe of its own. Where a payer publishes one, it is quoted with its source.

The sandbox payer, end to end

With a test key, enroll a provider with the sandbox payer, PWSANDBOX. The last word of the provider’s name picks what happens (make one provider per scenario), and POST /v1/sandbox/enrollments/{id}/advance makes the sandbox payer’s next move. A scenario takes the same path every time, and a call retried with the same Idempotency-Key answers the same ids. The sandbox payer’s task instructions and the words of its rejection start with “Sandbox:”, and so do a request’s status_words once it is with the sandbox payer, live, rejected or ended. A cancel asked while a request is with the sandbox payer or live is what the next advance does: canceled, or ended.

import { Payerworks } from "./payerworks.mjs";

const pw = new Payerworks({ apiKey: process.env.PAYERWORKS_API_KEY, baseUrl: process.env.PAYERWORKS_BASE_URL });
// A test key enrolls with the sandbox payer; the last word of the name picks the scenario.
const provider = await pw.postProviders({ name: "Sample Family Clinic TASKS", npi: "1234567893", tax_id: "12-3456789", tax_id_type: "ein" });
let enr = await pw.postEnrollments({
  provider_id: provider.id, payer: { id: "PWSANDBOX" }, transaction: "remittances", submit: true,
  notify_email: "dev@sampleclinic.example",
  primary_contact: { organization_name: "Sample Family Clinic LLC", email: "enrollment@sampleclinic.example", phone: "8015550100",
    address: { line1: "100 Main St", city: "Salt Lake City", state: "UT", zip: "84101" } },
});
console.log(enr.status, enr.waiting_on, enr.status_words);
for (const t of enr.tasks.filter((t) => t.responsible === "provider" && !t.complete)) {
  const values = t.fields.map((f) => ({ key: f.key, text: "PKT-0001" }));
  ({ enrollment: enr } = await pw.postTasksById(t.id, { values, complete: true }));
}
// A PDF for a document task: the upload and the confirm in one helper.
// await pw.uploadDocument(enr.id, task.id, "signed_form", "signed-form.pdf", pdfBytes);
const { moved } = await pw.postSandboxEnrollmentsByIdAdvance(enr.id);
console.log(moved);

Enrollment events

Each change raises one event, posted to your webhook and listed by GET /v1/events. An event carries ids, statuses and words only, never a tax id, a contact, a note or a document: GET /v1/enrollments/{id} for the rest. Payerworks also emails your key’s notice address (PUT /v1/account/contact) when a request moves without your doing it, to provider_action_required, with_payer, live, rejected, canceled or ended: every such move inside the same 15 minutes goes in one email, which names each request’s id, the provider’s name and NPI, the payer, the transaction and the status, and never a tax id, a contact, a note or a document. With no notice address set, nothing is emailed.

enrollment.updated

An enrollment request changed: a status change no type below names, or its fields, tasks, documents or notes. It carries the status, the previous status, whose turn it is, the reason, the fields that changed and the sequence.

enrollment.live

The payer confirmed the request: files of this kind may flow. It adds when, and the payer’s reference.

enrollment.rejected

The request was refused. It adds the rejection: the payer’s words whole, and the remedy.

enrollment.canceled

The request was canceled, or you asked to cancel one that is with the payer or live (cancel_requested says which).

enrollment.ended

A live route ended: the payer ended it, or a cancel you asked for while it was live went through (in the sandbox, at the next advance).

enrollment.task.assigned

A task was added: its id, rank, who holds it, its title and its fields.

enrollment.task.completed

A task was finished, by the provider, or by Payerworks for its own.

enrollment.task.deleted

A task was replaced by another (superseded_by names it).

What is refused, and why

• A Social Security number, as a tax id or anywhere: a provider enrolls with its EIN, which the IRS issues (ssn_not_accepted). A tax id whose first two digits are not a prefix the IRS assigns to an EIN is refused too (not_an_ein); that catches typos and some Social Security numbers, never all of them, so never send one.
• A bank account, routing or account number: no task asks for one, and free text holding a run of eight or more digits is refused (holds_long_number).
• A phone that is all one digit or not a US number, and on a live key an email at a reserved or example domain: the payer’s mail and calls would go nowhere.
• A real payer with a test key (test_key_sandbox_payer_only), and the sandbox payer with a live key (sandbox_payer_test_only).
• Eligibility at a DME MAC: traditional Medicare eligibility is asked of CMS’s HETS (ask_another_payer, naming the payer that answers it).
• A second open request for the same provider, payer and transaction (409 enrollment_exists, naming the one that stands).
• An upload that is not a PDF, or is over 10 MB.

Many requests from one file

POST /v1/enrollments/import/check reads a CSV of up to 100 rows, one request a row, and checks each exactly as POST /v1/providers and POST /v1/enrollments check their bodies, saving nothing; POST /v1/enrollments/import then makes each valid row. The header is the template below, and a column the import does not take is refused by name, never dropped.

provider_name,npi,tax_id,tax_id_type,payer_id,payer_name,transaction,contact_organization_name,contact_first_name,contact_last_name,contact_email,contact_phone,contact_phone_extension,contact_address_line1,contact_address_line2,contact_city,contact_state,contact_zip,notify_email,requested_effective_date,era_aggregation,ptan,note,submit

• A provider your key already has with that NPI and tax id is used as it is, never changed, and the row says so. A request that already stands, or an earlier row of the file asking the same, is a duplicate that names it.
• The import stops starting rows when its time in one call runs out, and names the first row not run: send that row and the rows after it again. An Idempotency-Key retry of the same file answers the same requests, never duplicates of them.
• With a live key, each NPI is looked up in the NPI registry, which answers one of three ways: it holds an active record (with Type 1 or 2 and whether the row’s provider name matches, each row on its own), it holds none, or it could not be asked just now. Each is a warning, never a refusal, and nothing it says is kept.
• GET /v1/enrollments/export answers every request matching the list’s filters as CSV, up to 5,000 rows, with no contact, note or full tax id; a cell a spreadsheet would run as a formula starts with an apostrophe.
• GET /v1/enrollments/durations says how long your own requests spent waiting on Payerworks, on the provider and with the payer, by payer and transaction. A figure is given once five stays have finished, the median and the middle half, each with how many it rests on; fewer says not enough history. Payerworks has no figures from anyone else.

How each row ends

ready

Checked: it would be made as it is (the check route only).

created

Made: its request (and its provider, when the key had none with that NPI and tax id).

invalid

Not made: one or more cells would be refused. Each problem names its column.

duplicate

Not made: an open request for this provider, payer and transaction already stands on the key, or an earlier row of this file asks for the same one.

refused

Not made: the store refused it (a limit reached, a lost race, a store failure). The error says which; send the row again.

not_run

Not started: the import ran out of time first. Send this row and the rows after it again.

What Payerworks will never do

• Sign for a provider. The provider signs its own agreements with each payer; no field here asks Payerworks to.
• Ask for a Social Security number, a bank account or a routing number.
• Say a request is with a payer, or live, before it is.

Providers and requests belong to the key that made them, like its webhook and its events. A new key starts with none, so keep the key that holds them; a rotated key keeps them, because rotation keeps the key id. Enrollment is the one part of the API that keeps what you send: the providers and enrollment requests you create (names, NPIs, tax ids, contacts and notes) and the PDFs you upload for a task, because a request lives for weeks and Payerworks people work it. They are for a practice’s business facts; never put a patient’s information in them. A test key’s providers and requests expire 30 days after their last change, and its PDFs 30 days after each was uploaded, or about a day after you delete one; a PDF uploaded but never confirmed goes after a day, whatever the key. A live key’s are kept until you delete them, and the copy of a deleted live PDF for 30 days more. Apart from that, our backups hold every PDF that was there each night, a test key’s included, for 35 days, and each Sunday’s for a year.

Drop 837P, 837I or 837D interchanges in your own folder over SFTP and read the answers from another: a TA1 when the envelope is not yours, a 999 by your setting, and a report that names every claim’s errors as POST /v1/claims/validate names them. It is built and not yet open: until Payerworks opens it, every /v1/sftp route answers 403 sftp_not_open.

• Make your user with PUT /v1/sftp and add an SSH public key with POST /v1/sftp/ssh-keys. There are no passwords, a private key is refused and never kept, and a key’s comment is dropped.
• A test key’s user sends usage indicator T to receiver PAYERWORKSTEST and a live key’s sends P to PAYERWORKS, both under qualifier ZZ. The answers are always in your key’s mode, whatever the file said.
• The 999 says what Payerworks checked of the envelope and the controls. A claim the checks refuse is said in the report, never in the 999, and no 277CA is written for a dropped file.
• Nothing you drop goes on to a payer.

What is kept, and for how long

• A file you drop in inbound is read once and deleted as soon as its answers are written. A file the lane could not reach is deleted by the bucket 1 day after it arrived; S3 removes an expired file in the day or so after its expiry.
• Each answer (a TA1, a 999 and the report) waits in outbound for 7 days after it was written, then the bucket deletes it; you may delete it sooner. S3 removes an expired file in the day or so after its expiry.
• The bucket keeps no earlier version of a file and is in no backup. Nothing you drop is stored anywhere else, logged or sent on: the lane's own log line names the key, the kind of file and the outcome, never its contents or its name.
• The endpoint's transfer log in CloudWatch records the name of each file you move, so never put a patient's name or any identifier in a file name.
• Nothing is sent to a payer: Payerworks validates and acknowledges the file, and you send the claims on yourself.
• When your key is revoked, its SFTP user is removed at once; when it expires, or when the endpoint could not be reached at the revoke, by the next daily pass, within a day. A file dropped under a revoked or expired key before then is deleted unread, with no answer.

Every route is under /v1. The base URL is shown with your key. The whole contract, machine-readable, is openapi.json.

Docs by job, with quickstarts, examples that run and every page as markdown for an agent: payerworks.com/docs. Every rate, size and item limit, read from the code that refuses by it: payerworks.com/limits. What was measured this month, with any incident and its feed: payerworks.com/status.

Claims are JSON in the 837P’s own structure: submitter, receiver, billing, subscriber (and dependent when the patient is not the subscriber), rendering and referring providers, and claimInformation with its patientControlNumber, claimChargeAmount, placeOfServiceCode, claimFilingCode, healthCareCodeInformation and serviceLines. patientControlNumber is your own reference, at most twenty characters; every answer about the claim carries it back. An institutional (837I) or dental (837D) claim takes the same shape, with institutionalService or dentalService on its lines and the fields its own route names.

curl "$PAYERWORKS_BASE_URL/v1/claims/validate" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @claim.json

• A file’s kind is read from its functional group and its implementation guide, so a 277CA claim acknowledgment is never read as a claim status 277. A kind Payerworks recognizes and does not read yet is named, never called unreadable.
• One kind of file a call: an interchange whose functional groups are of different kinds is refused, naming them, so no part of it goes unread.
• Every answer fits in one response; one that would not is refused 413 answer_too_large, so split the file.
• A path value with a broken percent escape is refused 400 invalid_path. A query parameter may be at most 200 characters, and no query is ever logged.

Send an Idempotency-Key header with any POST, and with the webhook PUT, and a retry gets the first answer instead of a second run.

• Use a new key for each new request: a UUID is a good one. A key is remembered for 24 hours.
• A retry with the same key and the same request gets the first answer again, with the header idempotent-replayed: true. What the first request did is not done a second time, and the sandbox’s webhook events keep their ids, so your server can ignore one it already handled.
• If the first answer said its webhook events could not be recorded or queued, and to retry, the retry with the same key does that step instead of repeating the refusal.
• The same key with a different request is refused with 422. While the first request is still running, a retry is refused with 409 and retry-after.
• An answer that failed on our side (a 5xx) is not remembered, so a retry runs the request again.
• Payerworks keeps a fingerprint of the request and the moment it ran, so it can answer the same way again. It never keeps the request or the answer.

key=$(uuidgen)   # one new key per request; reuse it only to retry that request
curl "$PAYERWORKS_BASE_URL/v1/sandbox/claims" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $key" \
  -d @claims.json

Every answer carries an x-request-id header naming that request, and every refusal carries request_id inside the error: the same id, except on an Idempotency-Key replay, where request_id names the request that first answered and x-request-id names the retry. Quote either when you write to us.

Set an https address in the console and every answer the 837P claims sandbox (POST /v1/sandbox/claims) makes, and every change to an enrollment request, is posted to it as an event, the moment it is made, signed with a secret only you and Payerworks hold. An event your server does not take is tried again, and every event is kept for 30 days, to list and to send again.

Every event is a POST of JSON in one shape. In it, created is the time in Unix seconds, mode is the key’s (a sandbox event is always test), and id is the same each time the same event is sent, a retry and a resend included, so you can ignore one you already handled.

POST /your/webhook
Content-Type: application/json
User-Agent: Payerworks-Webhooks/1
webhook-id: evt_8a1c…
webhook-timestamp: 1792324800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Payerworks-Signature: t=1792324800,v1=5f0c…

{ "id": "evt_8a1c…", "type": "sandbox.claim.acknowledged", "created": 1792324800, "mode": "test",
  "data": { "reference": "PW-SBX-REJ", "verdict": "R", "fixes": [ "The claim was rejected…" ] } }

Each POST is signed under the Standard Webhooks specification, so any of its libraries checks it: webhook-id is the event’s id, webhook-timestamp the time it was signed in Unix seconds, and webhook-signature is v1, a comma and the signature in base64.

That signature is HMAC-SHA256 over the id, a period, the timestamp, a period and the raw body exactly as it arrived, keyed with your signing secret’s bytes: the part after whsec_, decoded from base64.

Each POST also carries the Payerworks-Signature header the first receivers were built on: t, the time it was signed in Unix seconds, and v1, HMAC-SHA256 keyed with your whole signing secret over the time, a period and the raw body, written in hex.

Check one of them before you trust the body: compute the same HMAC, compare the two in constant time, and refuse a time more than five minutes from your clock, so a captured event cannot be sent to you again.

Checking the Standard Webhooks signature, in three languages:

import crypto from "node:crypto";

// headers: the headers of the request (Node gives their names in lowercase);
// rawBody: the request body exactly as it arrived, before any JSON parsing.
export function verifyWebhook(secret, headers, rawBody, toleranceSeconds = 300) {
  const id = headers["webhook-id"];
  const timestamp = String(headers["webhook-timestamp"] || "");
  if (!id || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest();
  return String(headers["webhook-signature"] || "").split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    const given = Buffer.from(signature || "", "base64");
    return version === "v1" && given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

Checking the Payerworks-Signature header instead, for a receiver built on it:

import crypto from "node:crypto";

// rawBody: the request body exactly as it arrived, before any JSON parsing.
export function verifyPayerworks(secret, header, rawBody, toleranceSeconds = 300) {
  const fields = { v1: [] };
  for (const part of String(header || "").split(",")) {
    const at = part.indexOf("=");
    if (at < 1) continue;
    const name = part.slice(0, at).trim();
    const value = part.slice(at + 1).trim();
    if (name === "v1") fields.v1.push(value); else fields[name] = value;
  }
  const t = fields.t || "";
  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  return fields.v1.some((v) => {
    const given = Buffer.from(v, "hex");
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

• Events are queued when the call is answered and posted a moment later, so your call never waits on your server. The call’s answer says how many were queued. A key may queue six deliveries a minute.
• Answer with any 2xx within four seconds and the event is delivered. A redirect, a timeout or any other answer is not, and Payerworks tries again: twice more, one and then two minutes later, sending only the events not yet delivered. All of one try’s events share ten seconds, and an endpoint that could not be reached is not asked again in that try.
• An event can arrive more than once, so ignore one whose webhook-id you already handled.
• Your address must be https, at a hostname rather than an IP address, on the standard port, with no user name or password in it.
• The signing secret begins whsec_ and is shown once, when it is made (and again to a retry of that same request with the same Idempotency-Key, within 24 hours). Setting the address again keeps it. Ask for a new one with rotate: true; the previous secret then signs every event beside the new one for 24 hours, or the overlap_hours you send (0 to 720), so a header carries two signatures and your server can switch over without missing one.
• A secret made before 10/19/2026 is written in an older alphabet (base64url, without padding). It keeps working, and the samples below read both; rotate it for one every Standard Webhooks library reads as it is.

Setting the address, rotating its secret and sending a test event from your own system:

# Set the address. The first answer carries the signing secret once: store it.
curl -X PUT "$PAYERWORKS_BASE_URL/v1/account/webhook" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "url": "https://example.com/payerworks/events" }'

# Rotate the secret: a new one, shown once; the old one signs beside it for 24 hours.
curl -X PUT "$PAYERWORKS_BASE_URL/v1/account/webhook" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/payerworks/events", "rotate": true }'

# Queue one ping event for it (202, with the event id).
curl -X POST "$PAYERWORKS_BASE_URL/v1/account/webhook/test" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY"

# A moment later: what the delivery did, as webhook.last_delivery.
curl "$PAYERWORKS_BASE_URL/v1/account" -H "Authorization: Bearer $PAYERWORKS_API_KEY"

Webhook destinations

• Besides the one account webhook, a key may hold up to ten webhook destinations, each with its own name, https address and signing secret (shown once), the event types it takes and how many deliveries it takes at once (1 to 10, 2 by default). Only events Payerworks makes are sent, and a ping always reaches the destination it is sent to.
• A delivery a destination did not take is tried again 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours and 48 hours after the attempt before it, seven attempts in all. After the seventh fails, the destination is disabled; PUT /v1/webhook-destinations/{id} with enabled: true turns it on again.
• Each post to a destination carries Payerworks-Attempt-Number, Payerworks-Attempt-Type (automatic, or manual for a redelivery you asked for) and Payerworks-Destination-Id beside both signatures. GET /v1/events/{id}/attempts lists every attempt, and a destination’s deliveries say which are pending, scheduled, delivered or failed.
• Set a notice address with PUT /v1/account/contact, and Payerworks emails it when a destination has been failing for 2 hours, for 24 hours, and when it is disabled. Each notice goes with the first failed attempt past its mark, so the first comes with the attempt about 2 hours 35 minutes after the first failure. A notice names the destination by its id and its address’s host, never by its name.
• POST /v1/events/{id}/redeliver with destination_id sends an event to that destination as a manual attempt and starts its retries again from the first. A destination’s secret is rotated the way the account webhook’s is, with overlap_hours.

The event log

• GET /v1/events lists your key’s events newest first, each as it was sent with what delivering it did: pending, delivered or failed, how many times it was posted, the last status (null when your server gave no answer) and the last error. An event that could not be queued, whose webhook was removed before it went, or that no delivery reported on within 65 minutes of being queued is failed too, its last error saying why and how to send it again. Pass limit (up to 100), type, and starting_after (the next_cursor of the page before, or an event id) to read further.
• GET /v1/events/{id} reads one event, and POST /v1/events/{id}/redeliver sends it again to the address set now. An event not yet delivered that is queued again, this way or by a retry with the same Idempotency-Key, reads pending until that delivery is done.
• An event is kept for 30 days and holds only what the event says: the sandbox payer’s invented answer, your claim references and your file’s control numbers, never the claim you sent; an enrollment event holds ids, statuses and words, never a tax id, a contact, a note or a document.
• An account’s keys together record up to 2,000 events a UTC day. Past that, a run still answers in full, but its events are not recorded or sent, and the answer says so; events are recorded again from 00:00 UTC (retry the run with the same Idempotency-Key then to record and send them).

# The newest ten events, then the page after them.
curl "$PAYERWORKS_BASE_URL/v1/events?limit=10" -H "Authorization: Bearer $PAYERWORKS_API_KEY"
curl "$PAYERWORKS_BASE_URL/v1/events?limit=10&starting_after=$NEXT_CURSOR" -H "Authorization: Bearer $PAYERWORKS_API_KEY"

# Only one type, and one event by its id.
curl "$PAYERWORKS_BASE_URL/v1/events?type=sandbox.remittance.received" -H "Authorization: Bearer $PAYERWORKS_API_KEY"
curl "$PAYERWORKS_BASE_URL/v1/events/$EVENT_ID" -H "Authorization: Bearer $PAYERWORKS_API_KEY"

# Send it again to the address set now (202).
curl -X POST "$PAYERWORKS_BASE_URL/v1/events/$EVENT_ID/redeliver" -H "Authorization: Bearer $PAYERWORKS_API_KEY"

Your key’s rate, its calls by day and your webhook are in the console. Open the console.

Three files, generated from the same route list as this page and openapi.json, so every route here is a method there. Each is plain source with no dependencies: download it, read it, and keep it in your own repository.

• The JavaScript and Python clients each send an Idempotency-Key on every POST and PUT, and retry a 429, a 503 or a 409 idempotency_in_flight at most twice, after the wait retry-after names, with the same key. A refusal is a PayerworksError carrying the status, the code, the sentence and the request id.
• The two clients also each check a webhook’s signature, in the Standard Webhooks headers or the Payerworks-Signature header, in constant time.
• The MCP server makes its calls the same way: an Idempotency-Key on every POST its tools send, and the same retries with the same key, waiting at most 30 seconds. A refusal reaches the model as a tool error carrying the status, the code, the sentence and the request id.
• Both clients can keep your own request log: requestLog: true (request_log=True in Python) keeps the last 1,000 attempts in your process, a number keeps that many, and requestLogFile (request_log_file) appends one JSON line an attempt to a file of yours. Each entry is the method, the path, the status, the request id, the time it took and the Idempotency-Key, never a body, a query or a header. Payerworks keeps no such record of your calls.
• Each of the three calls only the base URL you give it, never follows a redirect, and sends nothing anywhere else. The one exception is the JavaScript client’s uploadDocument, which posts your PDF, without your key, to the https upload address the API answered for it. Download again when this page lists a new route: each file names the build it was made from.

Add the MCP server to your AI client’s configuration:

// Download /sdk/payerworks.mjs from this site into your project.
import { Payerworks, PayerworksError } from "./payerworks.mjs";

const pw = new Payerworks({ apiKey: process.env.PAYERWORKS_API_KEY, baseUrl: process.env.PAYERWORKS_BASE_URL });
try {
  const { valid, claims } = await pw.postClaimsValidate({ claim });
  const page = await pw.getEvents({ query: { limit: 10 } });
} catch (e) {
  if (e instanceof PayerworksError) console.log(e.status, e.code, e.message, e.requestId);
}

With a test key, send invented data only. With a live key, the AI model and its provider read the patient data each tool sends and receives, so the server refuses a live key unless you set PAYERWORKS_MCP_ALLOW_LIVE_KEY=1. Set it only where that is permitted, for example under a business associate agreement that covers your AI client.

The same tools are also served by the API itself: POST /v1/mcp, over MCP’s Streamable HTTP transport (revision 2026-07-28, and the 2025 handshakes), with your key as the bearer and nothing to download. Each tool call is a call to its route under your key, metered and rate-limited as that route. With a live key no tool is called unless the request carries Payerworks-MCP-Allow-Live-Key: 1.

• Send your key on every call as `Authorization: Bearer <key>`.
• A test key (pw_test_…) is yours from the form on this page, for invented data only. It writes test interchanges and runs the sandbox payer, and nothing sent with it reaches a payer.
• A live key (pw_live_…) writes production files. Payerworks issues it once a business associate agreement is signed; ask from the form at the foot of the page.
• Each key has a rate in calls a minute: a test key from this page has 60, and a key Payerworks issues has 120 unless another rate is agreed. The rate is counted in a window that resets at the start of each UTC minute. Every answer to a route called with a valid key, an error included, carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (the seconds until the window resets), and the same figures in the RateLimit and RateLimit-Policy fields of the IETF draft. Past the limit the answer is 429 with retry-after. An answer given before a key is read carries none of them: a missing or invalid key, an unknown path (404), a method the route does not answer (405), a path that does not decode (400), or GET /v1/health, which takes no key.
• A call the API turns away before any work is done is counted as refused, apart from your calls: over the rate, a body that is not JSON or is too large, a query it cannot read, or an Idempotency-Key it cannot read, already used for another request or still running.
• A revoked key stops working within a minute.
• An account is the keys one key started. POST /v1/keys makes a named key of your key’s own mode and rate, shown once, with an expiry if you want one (1 to 365 days); a key never outlives the key that made it: its expiry is the sooner of expires_in_days and the making key’s own, and the making key’s when none is asked. An account holds 3 test keys or 25 live ones that are not revoked. Every key of an account may list its keys, and make, rotate and revoke them unless the account’s organization chose that only its signed-in members do.
• POST /v1/keys/{id}/rotate gives a key a new secret under the same key id, so its webhooks, events, usage and enrollments carry on. The old secret is still accepted for overlap_hours (24 by default, up to 720) and stops at once if the key is revoked; a second rotation ends the first one’s overlap. Two rotations at once: the first finishes, and the other answers 409 key_rotation_conflict and makes nothing.

Every refusal has one shape:

{ "error": { "code": "invalid_claims", "message": "One or more claims would be refused; nothing was written.", "claims": [ … ] } }

• 400 The request is malformed: no claim, bad JSON, a bad id, a path or a query that does not decode, or an Idempotency-Key that cannot be read.
• 401 No key, or a key that is not valid; on an organization route, a key where a member’s console sign-in is needed, or a sign-in that has ended.
• 403 The key may not do this, such as a test key asking for a production file, a live key on a route open to test keys only, or a route not open on this deployment yet (sftp_not_open); or a member whose role does not allow the call (org_role_forbidden).
• 404 No such route, or no such event for this key.
• 405 The route does not answer that method; the allow header names the ones it does.
• 409 Not now: a test event before a webhook address is set, a request with the same Idempotency-Key still running (retry after the seconds retry-after names), a webhook or a destination that changed while your request ran, or a limit reached (ten destinations, an account’s keys, ten SSH keys).
• 410 Gone: an invitation’s link is used within 7 days, and this one is older. Ask a member of the organization for a new one.
• 413 The body is over the size limit, or the answer would be larger than one response carries (answer_too_large): split the file, or send fewer claims or questions a call.
• 422 The input was read and would be refused (every claim’s or question’s errors are listed, and nothing was written), an interchange mixes kinds of file, or an Idempotency-Key was already used for a different request.
• 429 Over the key’s rate (wait the seconds retry-after names), over its webhook deliveries a minute, or past the events its account records in a UTC day, or past its account’s model reads a day (a test event is refused until 00:00 UTC).
• 500 Something failed on our side. Retry; nothing you sent was kept.
• 501 This route is not offered where you asked, and asking again answers the same: only the hosted API answers it, because it reads your key’s account (answered_by_the_door), a model read is switched off on this deployment (model_read_not_offered), or the sandbox timeline is not connected here (timeline_not_offered); organization sign-in is not open here (org_not_offered); or a claim cannot be sent to a payer yet (submit_not_offered, with each of its gates). Neither client retries a 501.
• 502 A model read gave no usable answer for the file you sent (model_read_failed): send a clearer copy, or try again.
• 503 We could not read or write your key’s records, or queue its events, just now; the message says what was not done. Retry in a moment; both clients retry a 503 twice by themselves. The same when the part of the API that draws a PDF or reads a picture could not be loaded (documents_unavailable, model_read_unavailable).
• 504 A model read did not finish inside one call (model_read_timed_out): send one page, or a crop of the part you need.

Every error code

Every refusal’s error.code is one of these: stable, snake_case, and always said with the same status. The list is read from the engine’s own catalog. A refusal that lists problems field by field names each one’s own code and field inside it.