Building with a coding agent

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 coding agent builds against Payerworks well when it reads what the API answers rather than guessing. Every page here is also markdown, the whole set is one file, and the contract is machine-readable, so you can hand an agent everything it needs in a few lines.

What to hand it

• /llms-full.txt: every docs page as markdown, in one file. /docs/llms.txt is its index.
• /openapi.json: every route with its request and answer schemas and real examples.
• /sdk/payerworks.mjs and /sdk/payerworks.py: the clients, one method per route.
• The MCP server, to let the agent call the API itself while it works: run /sdk/payerworks-mcp.mjs over stdio, or use the hosted one at POST /v1/mcp with your key.
• The examples, one per page, each run against the API in Payerworks’ own tests.

{
  "mcpServers": {
    "payerworks": {
      "command": "node",
      "args": ["/absolute/path/to/payerworks-mcp.mjs"],
      "env": { "PAYERWORKS_API_KEY": "pw_test_...", "PAYERWORKS_BASE_URL": "<the address shown with your key>" }
    }
  }
}

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.

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 rules to give it

• Use a test key from an environment variable, and invented patients only. Never paste a real patient into an agent’s session.
• Keep the key on a server: it is a bearer key, never browser code.
• Payerworks sends nothing. A file the API writes is for your system to send on your own connection.
• A refusal is a PayerworksError with a status, a code and a request id: handle it by its code, and retry only what the clients retry (429, 503 and 409 idempotency_in_flight).

Prompts

Start the integration

Read https://payerworks.com/llms-full.txt and https://payerworks.com/openapi.json. Using the JavaScript client from https://payerworks.com/sdk/payerworks.mjs, write a module that checks a claim with POST /v1/claims/validate and, only when it is valid, writes it with POST /v1/claims/837p. Read the key from PAYERWORKS_API_KEY and the base URL from PAYERWORKS_BASE_URL. Handle a PayerworksError by its code. Use invented test data only.

Test it against the sandbox

Write tests for that module against the Payerworks claims sandbox, POST /v1/sandbox/claims, with one claim per member ID ending the claims docs page lists (a paid claim, REJ, DENY and PEND). Assert on the explained 999, 277CA and 835 the sandbox answers, never on figures you typed.

Receive events

Add a webhook receiver for Payerworks events. Check the Standard Webhooks signature over the raw request body with verifyStandardWebhook from the client before parsing it, skip a webhook-id already handled, and answer 2xx quickly. The events and their fields are on https://payerworks.com/docs/events.md.

Explain eligibility

Using https://payerworks.com/docs/eligibility.md, write a function that turns a 271 into the patient’s deductible and out-of-pocket remaining, in network, for service type 30, by calling POST /v1/eligibility/explain. A figure the payer did not state stays null: never print it as zero.

Checking what it built

• Run what it wrote against the sandbox payers with a test key, and compare it with the matching example file.
• A signature checked after the body was parsed and written again fails: the check reads the raw bytes.
• A claim status of not_found is not a rejection, and a remittance’s verdict is not CLP02 alone. An agent that maps codes itself instead of reading the answer gets both wrong.
• Nothing it builds should keep a patient’s data in an enrollment request or a provider: those are for a practice’s business facts.