Prior authorization: write 278s, read responses

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.

Write the review request as a 278 from JSON, send it the way the payer takes it, and give Payerworks the response that comes back to read. The authorization sandbox answers from the same payer as the eligibility sandbox. POST /v1/authorizations/required checks codes against Medicare’s published prior authorization lists.

Routes

POST/v1/authorizations/278Write a 278
POST/v1/authorizations/explainExplain a 278 response
POST/v1/sandbox/authorizationsRun the prior authorization sandbox
POST/v1/authorizations/requiredDoes Medicare require it

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/authorizations/278`

Write a 278

Up to one hundred prior authorization or referral requests, from JSON (the kind of review, the service type, each procedure code with its units and dates, the requester, the servicing provider, the patient and the diagnoses), written as one 005010X217 interchange for you to send on your own connection, or built in the shape of the Da Vinci PAS request bundle with output set to fhir. Each request is checked field by field first, and nothing is written if any would be refused. A test key writes test files only. 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.

Request

curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/authorizations/278" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

With the JavaScript client

const answer = await pw.postAuthorizations278(body);

With the Python client

answer = pw.post_authorizations_278(body)

request.jsonJSON

{
  "sender_id": "SAMPLEBILLER",
  "receiver_id": "99999",
  "control_number": 31,
  "request": {
    "controlNumber": "AUTH-0001",
    "tradingPartnerServiceId": "99999",
    "requester": {
      "organizationName": "Sample Family Medicine",
      "npi": "1234567893"
    },
    "subscriber": {
      "memberId": "W123456789",
      "firstName": "SAMPLE",
      "lastName": "PATIENT",
      "dateOfBirth": "1980-02-14",
      "gender": "F"
    },
    "review": {
      "serviceTypeCode": "12",
      "placeOfServiceCode": "12",
      "diagnoses": [
        "M17.11"
      ]
    },
    "services": [
      {
        "procedureCode": "L1833",
        "units": 4,
        "serviceDate": "2026-11-02"
      }
    ]
  }
}

The answer (200)JSON

{
  "version": "005010X217",
  "usage": "T",
  "x12": "ISA*00*          *00*          *ZZ*SAMPLEBILLER   *ZZ*99999          *261019*1500*^*00501*000000031*0*T*:~GS*HI*SAMPLEBILLER*99999*20261019*1500*31*X*005010X217~ST*278*0001*005010X217~BHT*0007*13*AUTH-0001*20261019*1500~HL*1**20*1~NM1*X3*2*…",
  "interchange_control_number": "000000031",
  "group_control_number": "31",
  "transaction_set_control_numbers": [
    "0001"
  ],
  "segments": 22,
  "requests": [
    {
      "index": 0,
      "trace": "AUTH-0001",
      "transaction_set_control_number": "0001",
      "warnings": []
    }
  ],
  "payer_choice": "Payerworks sends nothing. Whether a payer accepts an X12 278 or a FHIR prior authorization request at all is the payer's choice: many take them only on a portal, by fax or by phone, and its companion guide says what it requires.",
  "transmitted": false
}

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in /openapi.json.

Field, Type, What it is
Field	Type	What it is
`version`	string
`usage`	one of "T", "P"
`x12`	string
`interchange_control_number`	string
`group_control_number`	string
`transaction_set_control_numbers`	list of string
`segments`	integer
`fhir`	object	With output fhir or both: the implementation guide named, a note that the shape is not validated, and each request’s bundle.
`requests`	list of object
`payer_choice`	string	That Payerworks sends nothing, and whether a payer takes a 278 at all is the payer’s choice.
`transmitted`	the value false

POST`/v1/authorizations/explain`

Explain a 278 response

A payer’s 278 response, as X12, as Payerworks’ own JSON read of one, or as a PAS response, said per review: approved, approved in part, approved with changes, not approved, pended, waiting on more information, canceled, no review needed, or not reviewed at all, with the reason in words, the certification and reference numbers, the approved dates and units against what you asked, the claim field the number goes in, and the next step. A request the payer never reviewed is never called a denial.

Request

curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/authorizations/explain" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

With the JavaScript client

const answer = await pw.postAuthorizationsExplain(body);

With the Python client

answer = pw.post_authorizations_explain(body)

request.jsonJSON

{
  "x12": "ISA*00*          *00*          *ZZ*PWSANDBOX      *ZZ*SUBMITTER      *261019*1500*^*00501*000000002*0*T*:~GS*HI*PWSANDBOX*SUBMITTER*20261019*1500*2*X*005010X217~ST*278*0001*005010X217~BHT*0007*11*AUTH-0001*20261019*1500*18~HL*1**20*1~NM1*X3*2*PAYERWORKS SANDBOX PAYER*****PI*PWSANDBOX~HL*2*1*21*1~NM1*1P*2*Sample Family Medicine*****XX*1234567893~HL*3*2*22*1~NM1*IL*1*PATIENT*SAMPLE****MI*W12345PARTIAL~DMG*D8*19800214*F~HL*4*3*EV*1~TRN*2*AUTH-0001*9SUBMITTER~UM*HS*I*12*12:B~HCR*A2*PWA033425780*10~REF*NT*PWR951115437~DTP*AAH*RD8*20261102-20270130~DTP*102*D8*20261019~DTP*007*RD8*20261102-20270130~DTP*036*D8*20270130~HI*ABK:M1711~HL*5*4*SS*0~TRN*2*852346626*9SUBMITTER~HCR*A2*PWA033425780*10~DTP*472*D8*20261102~SV1*HC:L1833**UN*2~SE*25*0001~GE*1*2~IEA*1*000000002~",
  "asked": {
    "controlNumber": "AUTH-0001",
    "tradingPartnerServiceId": "PWSANDBOX",
    "requester": {
      "organizationName": "Sample Family Medicine",
      "npi": "1234567893"
    },
    "subscriber": {
      "memberId": "W12345PARTIAL",
      "firstName": "SAMPLE",
      "lastName": "PATIENT",
      "dateOfBirth": "1980-02-14",
      "gender": "F"
    },
    "review": {
      "serviceTypeCode": "12",
      "placeOfServiceCode": "12",
      "diagnoses": [
        "M17.11"
      ]
    },
    "services": [
      {
        "procedureCode": "L1833",
        "units": 4,
        "serviceDate": "2026-11-02"
      }
    ]
  }
}

The answer (200)JSON

{
  "kind": "278",
  "source": "x12",
  "envelope": {
    "sender_qualifier": "ZZ",
    "sender": "PWSANDBOX",
    "receiver_qualifier": "ZZ",
    "receiver": "SUBMITTER",
    "date": "261019",
    "time": "1500",
    "control_number": "000000002",
    "usage": "T",
    "functional_group": "HI",
    "version": "005010X217",
    "transaction_sets": {
      "278": 1
    },
    "segments": 28
  },
  "reviews": [
    {
      "index": 0,
      "trace": "AUTH-0001",
      "purpose": "response",
      "payer": {
        "name": "PAYERWORKS SANDBOX PAYER",
        "id": "PWSANDBOX",
        "entity": "X3"
      },
      "requester": {
        "name": "Sample Family Medicine",
        "id_qualifier": "XX",
        "id": "1234567893",
        "entity": "1P"
      },
      "subscriber": {
        "name": "SAMPLE PATIENT",
        "member_id": "W12345PARTIAL",
        "birth_date": "1980-02-14",
        "gender": "F"
      },
      "dependent": null,
      "request_category": {
        "code": "HS",
        "words": "health services review: outpatient services",
        "known": true
      },
      "service_type": {
        "code": "12",
        "words": "durable medical equipment, purchased",
        "known": true,
        "verified_in_005010": true,
        "later_words": ""
      },
      "verdict": "partially_approved",
      "words": "Approved in part, certification number PWA033425780: fewer units than asked on one service.",
      "next_step": "Bill only what was approved, with PWA033425780 as priorAuthorizationNumber (2300 REF*G1). For what was not, ask the payer to reconsider (a 278 with certificationType N and the administrative reference number, where the payer takes one) or f…",
      "certification_number": "PWA033425780",
      "administrative_reference_number": "PWR951115437",
      "previous_authorization_number": "",
      "decision": {
        "code": "A2",
        "words": "certified in part",
        "verdict": "partially_approved",
        "known": true,
        "certification_number": "PWA033425780",
        "second_surgical_opinion": ""
      },
      "reason": {
        "code": "10",
        "words": "the delivery pattern asked (units, days, visits, weeks, hours or months)",
        "kind": "denial",
        "known": true
      },
      "rejections": [],
      "dates": {
        "event": {
          "begin": "2026-11-02",
          "end": "2027-01-30"
        },
        "admission": "",
        "certification": {
          "issued": "2026-10-19",
          "effective": {
            "begin": "2026-11-02",
            "end": "2027-01-30"
          },
          "expires": "2027-01-30"
        }
      },
      "services": [
        {
          "index": 0,
          "trace": "852346626",
          "procedure": {
            "qualifier": "HC",
            "code": "L1833",
            "modifiers": []
          },
          "verdict": "partially_approved",
          "decision": {
            "code": "A2",
            "words": "certified in part",
            "verdict": "partially_approved",
            "known": true,
            "certification_number": "PWA033425780"
          },
          "reason": {
            "code": "10",
            "words": "the delivery pattern asked (units, days, visits, weeks, hours or months)",
            "known": true
          },
          "units": 2,
          "units_asked": 4,
          "units_cut": 2,
          "dates": {
            "begin": "2026-11-02",
            "end": "2026-11-02"
          },
          "dates_asked": {
            "begin": "2026-11-02",
            "end": "2026-11-02"
          },
          "dates_changed": false,
          "quantities": [],
          "administrative_reference_number": "",
          "messages": []
        }
      ],
      "quantities": [],
      "messages": [],
      "claim": {
        "prior_authorization_number": "PWA033425780",
        "field": "claimInformation.claimSupplementalInformation.priorAuthorizationNumber",
        "segment": "2300 REF*G1",
        "route": "POST /v1/claims/837p"
      },
      "notes": [
        "From 01/01/2026, CMS-0057-F (89 FR 8758, 02/08/2024) requires Medicare Advantage organizations, Medicaid and CHIP programs and plans, and QHP issuers on the federal exchanges to give a specific reason for a denied prior authorization (drugs…"
      ],
      "label_source": "paraphrase"
    }
  ],
  "label_source": "paraphrase"
}

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in /openapi.json.

Field, Type, What it is
Field	Type	What it is
`kind`	the value "278"
`source`	one of "x12", "json", "fhir"
`envelope`	Envelope or null
`reviews`	list of AuthorizationReview
`answer`	object	Only with ?include=answer: the 278 read to JSON.
`label_source`	the value "paraphrase"

POST`/v1/sandbox/authorizations`

Run the prior authorization sandbox

The round trip on invented data: your requests written as a 278 and the sandbox payer’s 278 response, chosen by how each member ID ends, read back and explained in the same call. Any key may call it, every file is a test file, and nothing reaches a payer.

Request

curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/sandbox/authorizations" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

With the JavaScript client

const answer = await pw.postSandboxAuthorizations(body);

With the Python client

answer = pw.post_sandbox_authorizations(body)

request.jsonJSON

{
  "request": {
    "controlNumber": "AUTH-0001",
    "tradingPartnerServiceId": "PWSANDBOX",
    "requester": {
      "organizationName": "Sample Family Medicine",
      "npi": "1234567893"
    },
    "subscriber": {
      "memberId": "W12345PARTIAL",
      "firstName": "SAMPLE",
      "lastName": "PATIENT",
      "dateOfBirth": "1980-02-14",
      "gender": "F"
    },
    "review": {
      "serviceTypeCode": "12",
      "placeOfServiceCode": "12",
      "diagnoses": [
        "M17.11"
      ]
    },
    "services": [
      {
        "procedureCode": "L1833",
        "units": 4,
        "serviceDate": "2026-11-02"
      }
    ]
  }
}

The answer (200)JSON

{
  "usage": "T",
  "transmitted": false,
  "control": {
    "interchange_request": "000000001",
    "interchange_response": "000000002",
    "sets": [
      "0001"
    ]
  },
  "files": {
    "authorization_request_278": "ISA*00*          *00*          *ZZ*SUBMITTER      *ZZ*PWSANDBOX      *261019*1500*^*00501*000000001*0*T*:~GS*HI*SUBMITTER*PWSANDBOX*20261019*1500*1*X*005010X217~ST*278*0001*005010X217~BHT*0007*13*AUTH-0001*20261019*1500~HL*1**20*1~NM1*X3*2*…",
    "authorization_response_278": "ISA*00*          *00*          *ZZ*PWSANDBOX      *ZZ*SUBMITTER      *261019*1500*^*00501*000000002*0*T*:~GS*HI*PWSANDBOX*SUBMITTER*20261019*1500*2*X*005010X217~ST*278*0001*005010X217~BHT*0007*11*AUTH-0001*20261019*1500*18~HL*1**20*1~NM1*X3…"
  },
  "outcomes": [
    {
      "index": 0,
      "trace": "AUTH-0001",
      "outcome": "partially_approved",
      "trigger": "PARTIAL"
    }
  ],
  "requests": [
    {
      "index": 0,
      "trace": "AUTH-0001",
      "warnings": []
    }
  ],
  "explained": [
    {
      "index": 0,
      "trace": "AUTH-0001",
      "purpose": "response",
      "payer": {
        "name": "PAYERWORKS SANDBOX PAYER",
        "id": "PWSANDBOX",
        "entity": "X3"
      },
      "requester": {
        "name": "Sample Family Medicine",
        "id_qualifier": "XX",
        "id": "1234567893",
        "entity": "1P"
      },
      "subscriber": {
        "name": "SAMPLE PATIENT",
        "member_id": "W12345PARTIAL",
        "birth_date": "1980-02-14",
        "gender": "F"
      },
      "dependent": null,
      "request_category": {
        "code": "HS",
        "words": "health services review: outpatient services",
        "known": true
      },
      "service_type": {
        "code": "12",
        "words": "durable medical equipment, purchased",
        "known": true,
        "verified_in_005010": true,
        "later_words": ""
      },
      "verdict": "partially_approved",
      "words": "Approved in part, certification number PWA033425780: fewer units than asked on one service.",
      "next_step": "Bill only what was approved, with PWA033425780 as priorAuthorizationNumber (2300 REF*G1). For what was not, ask the payer to reconsider (a 278 with certificationType N and the administrative reference number, where the payer takes one) or f…",
      "certification_number": "PWA033425780",
      "administrative_reference_number": "PWR951115437",
      "previous_authorization_number": "",
      "decision": {
        "code": "A2",
        "words": "certified in part",
        "verdict": "partially_approved",
        "known": true,
        "certification_number": "PWA033425780",
        "second_surgical_opinion": ""
      },
      "reason": {
        "code": "10",
        "words": "the delivery pattern asked (units, days, visits, weeks, hours or months)",
        "kind": "denial",
        "known": true
      },
      "rejections": [],
      "dates": {
        "event": {
          "begin": "2026-11-02",
          "end": "2027-01-30"
        },
        "admission": "",
        "certification": {
          "issued": "2026-10-19",
          "effective": {
            "begin": "2026-11-02",
            "end": "2027-01-30"
          },
          "expires": "2027-01-30"
        }
      },
      "services": [
        {
          "index": 0,
          "trace": "852346626",
          "procedure": {
            "qualifier": "HC",
            "code": "L1833",
            "modifiers": []
          },
          "verdict": "partially_approved",
          "decision": {
            "code": "A2",
            "words": "certified in part",
            "verdict": "partially_approved",
            "known": true,
            "certification_number": "PWA033425780"
          },
          "reason": {
            "code": "10",
            "words": "the delivery pattern asked (units, days, visits, weeks, hours or months)",
            "known": true
          },
          "units": 2,
          "units_asked": 4,
          "units_cut": 2,
          "dates": {
            "begin": "2026-11-02",
            "end": "2026-11-02"
          },
          "dates_asked": {
            "begin": "2026-11-02",
            "end": "2026-11-02"
          },
          "dates_changed": false,
          "quantities": [],
          "administrative_reference_number": "",
          "messages": []
        }
      ],
      "quantities": [],
      "messages": [],
      "claim": {
        "prior_authorization_number": "PWA033425780",
        "field": "claimInformation.claimSupplementalInformation.priorAuthorizationNumber",
        "segment": "2300 REF*G1",
        "route": "POST /v1/claims/837p"
      },
      "notes": [
        "From 01/01/2026, CMS-0057-F (89 FR 8758, 02/08/2024) requires Medicare Advantage organizations, Medicaid and CHIP programs and plans, and QHP issuers on the federal exchanges to give a specific reason for a denied prior authorization (drugs…"
      ],
      "label_source": "paraphrase"
    }
  ],
  "payer_choice": "Payerworks sends nothing. Whether a payer accepts an X12 278 or a FHIR prior authorization request at all is the payer's choice: many take them only on a portal, by fax or by phone, and its companion guide says what it requires."
}

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in /openapi.json.

Field, Type, What it is
Field	Type	What it is
`usage`	the value "T"
`transmitted`	the value false
`control`	object
`files`	object
`outcomes`	list of object
`requests`	list of object
`explained`	list of AuthorizationReview
`payer_choice`	string

POST`/v1/authorizations/required`

Does Medicare require it

Up to one hundred procedure codes checked against CMS’s published Medicare fee-for-service lists on a date of service: the DMEPOS Required Prior Authorization List and the hospital outpatient department list, each named and dated, with the state or the setting asked for where the list depends on it. A code on neither list is said as not on the lists held, never as not required, and for any other payer the answer is that no published list is held.

Request

curl -sS -X POST "$PAYERWORKS_BASE_URL/v1/authorizations/required" \
  -H "Authorization: Bearer $PAYERWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

With the JavaScript client

const answer = await pw.postAuthorizationsRequired(body);

With the Python client

answer = pw.post_authorizations_required(body)

request.jsonJSON

{
  "procedure_codes": [
    "L1833",
    "L3761",
    "E0601"
  ],
  "date_of_service": "2026-11-02",
  "payer_type": "medicare_fee_for_service"
}

The answer (200)JSON

{
  "date_of_service": "2026-11-02",
  "payer_type": "medicare_fee_for_service",
  "state": null,
  "setting": null,
  "payer_choice": "Payerworks sends nothing. Whether a payer accepts an X12 278 or a FHIR prior authorization request at all is the payer's choice: many take them only on a portal, by fax or by phone, and its companion guide says what it requires.",
  "codes": [
    {
      "code": "L1833",
      "kind": "hcpcs",
      "required": true,
      "lists": [
        {
          "list": "dmepos",
          "name": "CMS DMEPOS Required Prior Authorization List",
          "url": "https://www.cms.gov/research-statistics-data-and-systems/monitoring-programs/medicare-ffs-compliance-programs/dmepos/downloads/dmepos_pa_required-prior-authorization-list.pdf",
          "updated": "07/29/2026",
          "read": "10/19/2026",
          "group": "Orthoses",
          "words": "knee orthosis, adjustable joints, positional, off the shelf",
          "required": true,
          "from": "2026-10-28",
          "why": "nationwide"
        }
      ],
      "words": "L1833 needs prior authorization for Medicare fee-for-service on 11/02/2026: it is on the DMEPOS Required Prior Authorization List, required from 10/28/2026."
    },
    {
      "code": "L3761",
      "kind": "hcpcs",
      "required": "depends_on_state",
      "lists": [
        {
          "list": "dmepos",
          "name": "CMS DMEPOS Required Prior Authorization List",
          "url": "https://www.cms.gov/research-statistics-data-and-systems/monitoring-programs/medicare-ffs-compliance-programs/dmepos/downloads/dmepos_pa_required-prior-authorization-list.pdf",
          "updated": "07/29/2026",
          "read": "10/19/2026",
          "group": "Orthoses",
          "words": "elbow orthosis, adjustable locking joint, off the shelf",
          "required": "depends_on_state",
          "from": "2026-10-28",
          "states": [
            "NY",
            "MI"
          ],
          "nationwide_from": "2027-04-26",
          "why": "phased"
        }
      ],
      "words": "L3761 is on the DMEPOS Required Prior Authorization List, phased in by state: on 11/02/2026 it is required where the beneficiary lives in NY, MI, FL, CA, and nationwide from 04/26/2027. Send the state the beneficiary lives in to settle it."
    }
  ],
  "sources": [
    {
      "name": "CMS DMEPOS Required Prior Authorization List",
      "url": "https://www.cms.gov/research-statistics-data-and-systems/monitoring-programs/medicare-ffs-compliance-programs/dmepos/downloads/dmepos_pa_required-prior-authorization-list.pdf",
      "updated": "07/29/2026",
      "read": "10/19/2026"
    },
    {
      "name": "CMS Hospital Outpatient Department Services That Require Prior Authorization",
      "url": "https://www.cms.gov/files/document/opd-services-require-prior-authorization.pdf",
      "updated": "09/25/2026",
      "read": "10/19/2026"
    }
  ],
  "note": "Medicare fee-for-service claims for these items, by the date of delivery (for a rental, of the initial rental claim). It does not apply to Medicare Advantage plans. Medicare fee-for-service services furnished in a hospital outpatient depart…"
}

Shortened here: lists show their first two items and long strings are cut. The whole answer is this route’s example in /openapi.json.

Field, Type, What it is
Field	Type	What it is
`date_of_service`	string
`payer_type`	string
`state`	string or null
`setting`	string or null
`payer_choice`	string
`codes`	list of object
`sources`	list of object
`note`	string

Reading the answer

Each review in an explain answer has a verdict and its words, the decision and reason codes in words, the certification_number when the payer gave one, and the next_step.
A request to the sandbox with a member ID the eligibility sandbox cannot find is not found here either, and a claim the claims sandbox denies is not certified here.

Troubleshooting

invalid_authorization_requests (422): One request would be refused, so nothing was written; each request’s errors are listed.
not_a_278_response (422): This 278 holds requests only: send the payer’s response.

Every refusal these routes may answer, with its status. Any route may also answer the codes every route shares, on Every error.

Code, Status, What it means
Code	Status	What it means
`invalid_asked_requests`	400	asked is the review request, or the list of them, that the response answers.
`invalid_date_of_service`	400	date_of_service is a day, YYYY-MM-DD.
`invalid_explain_include`	400	include names what to add to the answer: answer (the read of the 278).
`invalid_output`	400	output is "x12" (the default), "fhir" (the Da Vinci PAS bundle shape) or "both".
`invalid_payer_type`	400	payer_type is medicare_fee_for_service, medicare_advantage, medicaid, commercial or other.
`invalid_procedure_codes`	400	Each procedure code is a HCPCS Level II code (a letter and four digits) or a five-character CPT code.
`invalid_sender_id`	400	sender_id is your submitter id at the receiver: 2 to 15 letters, digits or spaces.
`invalid_setting`	400	setting is hospital_outpatient or other (where the service is furnished), or left out.
`invalid_state`	400	state is the two-letter state the patient lives in, such as CA.
`no_authorization_answer`	400	Send the 278 response as `x12` (the file's text), as `json` (Payerworks' own read of one) or as `fhir` (a Da Vinci PAS response Bundle or ClaimResponse).
`no_authorization_request`	400	The body has no review request: send `requests` (a list), `request`, or the request itself in the JSON shape the docs describe.
`no_procedure_codes`	400	Send `procedure_codes`: a list of HCPCS or CPT codes, such as L1833 or 64490.
`too_many_authorization_requests`	400	At most 100 review requests a call.
`too_many_procedure_codes`	400	At most 100 procedure codes a call.
`test_key_production_file`	403	A test key writes test interchanges only (ISA15 = T). Use a live key for a production file.
`answer_too_large`	413	This answer is larger than one response can carry: send less in each call (split the file, or send fewer claims or requests).
`file_too_large`	413	This file holds more than one call can read: the error names what was counted (`unit`) and the most one call reads (`limit`). Split it and send each part in its own call.
`duplicate_authorization_trace`	422	Two review requests in one file carry the same trace (controlNumber); each must be unique so its response matches back.
`invalid_authorization_requests`	422	One or more review requests would be refused; nothing was written. Each request's errors are listed.
`not_a_278`	422	This is not an X12 278 request for review and response (005010X217): send the 278 with its ISA envelope.
`not_a_278_json`	422	This JSON is not a read 278: it holds no `reviews` with a decision or a rejection.
`not_a_278_response`	422	This 278 holds requests only (BHT02 13): send the payer's response (BHT02 11).
`not_a_pas_response`	422	This FHIR resource is not a PAS response: send a Bundle holding a ClaimResponse, or the ClaimResponse, with a reviewAction or an error.

Code lists

The prior authorization sandbox’s member ID endings

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:

Ending, Outcome, What it answers
Ending	Outcome	What it answers
`NOTFOUND`	`subscriber_not_found`	A member ID ending in NOTFOUND is not found: the response refuses in the subscriber’s loop with AAA 75 and reviews nothing.
`BADDOB`	`birth_date_mismatch`	A member ID ending in BADDOB is found, but the birth date does not match: AAA 71 in the patient’s loop, and nothing reviewed.
`DOWN`	`payer_unavailable`	A member ID ending in DOWN reaches a payer that cannot answer: AAA 42 in the payer’s loop, follow-up R. Send it again later, unchanged.
`REJ`	`member_id_invalid`	A member ID ending in REJ is refused as a member ID the payer does not accept: AAA 72 in the subscriber’s loop, the same refusal the claims sandbox gives.
`INACTIVE`	`not_eligible`	A member ID ending in INACTIVE is not certified because the patient was not covered on the date of service: HCR A3 with reason 53, as the eligibility sandbox ends that coverage last year.
`NOTREQ`	`not_required`	A member ID ending in NOTREQ needs no authorization: HCR NA with reason 0H, and no certification number.
`PARTIAL`	`partially_approved`	A member ID ending in PARTIAL is certified in part: each service asked for two or more units is approved for half of them, rounded down (HCR A2, reason 10); a service of one unit is approved in full.
`MODDATE`	`modified_dates`	A member ID ending in MODDATE is certified with changes (HCR A6): the dates approved start two weeks after the dates asked and run for thirty days.
`DENY`	`denied`	A member ID ending in DENY is not certified as not medically necessary (HCR A3, reason 0F), as the claims sandbox denies the claim.
`INFO`	`more_information_needed`	A member ID ending in INFO is pended until the payer has more patient information (HCR A4, reason 0U), and a message names the visit notes it needs.
`PEND`	`pended`	A member ID ending in PEND is pended while the first utilization review runs (HCR A4, reason 30), with an administrative reference number to follow it by.
``	`approved`	Any other member ID is certified in total (HCR A1) with a certification number, every service approved for the units asked, effective from the first date asked for at least ninety days.

Example

prior-authorization.mjs runs every step below against the API with a test key. It needs payerworks.mjs and sample-data.mjs beside it.

prior-authorization.mjsJavaScript

// Payerworks example: prior authorization, a 278 written and its response read. Docs: https://payerworks.com/docs/prior-authorization
//
// 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 prior-authorization.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 { AUTHORIZATION_REQUEST, SENDER_ID, PAYER_ID, copy, refusalOf } from './sample-data.mjs';

/** @param {Payerworks} pw */
export async function run(pw) {
  // 1. The request written as a 278, to send the way the payer takes it.
  const written = await pw.postAuthorizations278({ sender_id: SENDER_ID, receiver_id: PAYER_ID, control_number: 31, request: copy(AUTHORIZATION_REQUEST) });

  // 2. The authorization sandbox answers it with a 278 response, already explained.
  const request = { ...copy(AUTHORIZATION_REQUEST), tradingPartnerServiceId: 'PWSANDBOX' };
  const sandbox = await pw.postSandboxAuthorizations({ request });

  // 3. Explain a response you hold: the same reading, from the file alone.
  const explained = await pw.postAuthorizationsExplain({ x12: sandbox.files.authorization_response_278 });

  // 4. The failure path: the request you sent is not the payer's response, and the route says so.
  const refused = await refusalOf(() => pw.postAuthorizationsExplain({ x12: written.x12 }), { PayerworksError });

  return {
    written: { transmitted: written.transmitted },
    verdict: explained.reviews[0].verdict,
    next_step: Boolean(explained.reviews[0].next_step),
    refused,
  };
}

// Run as a script: node <this file>, with PAYERWORKS_API_KEY and PAYERWORKS_BASE_URL set.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run(new Payerworks()), null, 2));
}

What it answered, run against the API in Payerworks’ own tests (your request ids will differ)JSON

{
  "written": {
    "transmitted": false
  },
  "verdict": "approved",
  "next_step": true,
  "refused": {
    "status": 422,
    "code": "not_a_278_response",
    "request_id": "req_4"
  }
}

Prior authorization

Routes

POST`/v1/authorizations/278`

POST`/v1/authorizations/explain`

POST`/v1/sandbox/authorizations`

POST`/v1/authorizations/required`

Reading the answer

Troubleshooting

Code lists

The prior authorization sandbox’s member ID endings

Example

What happens next

Talk to Payerworks

Prior authorization

Routes

POST/v1/authorizations/278

POST/v1/authorizations/explain

POST/v1/sandbox/authorizations

POST/v1/authorizations/required

Reading the answer

Troubleshooting

Code lists

The prior authorization sandbox’s member ID endings

Example

What happens next

Talk to Payerworks

POST`/v1/authorizations/278`

POST`/v1/authorizations/explain`

POST`/v1/sandbox/authorizations`

POST`/v1/authorizations/required`