278 request — generate278()

Outcome

A service authorization request is composed as a syntactically valid 278 (Health Care Services Review — Request), routed to the right partner, submitted with the correct envelope and control numbers, and tracked with the trace number that ties response back to request.

Prerequisites

Scope	What it lets you do
edi.transaction.read	View transactions
edi.auth.run	Originate 278 requests through the gateway

A trading partner with 278 outbound and 278 inbound capabilities (2.4 — Capabilities). A program configured with authorizationWorkflow = AUTOMATIC_278 (set on the rcm-app side; the gateway honors this routing).

278 request anatomy

Source: packages/x12/src/outbound/services-review-278.ts. Implementation convention: 005010X217.

ISA → GS → ST*278 → BHT
  Loop 2000A — Utilization Management Organization (UMO)
    HL*1**20*1
    NM1*X3 (UMO — payer)
  Loop 2000B — Requester
    HL*2*1*21*1
    NM1*1P (provider)
  Loop 2000C — Subscriber
    HL*3*2*22*1
    NM1*IL (subscriber)
    DMG (DOB / gender)
  Loop 2000D — Dependent (when patient is not subscriber)
    HL*4*3*23*0
    NM1*03
  Loop 2000E — Patient Event
    HL*5*4*EV*1
    UM (services review type, certification type)
    HCR (services review when applicable)
    DTP*AAH (admission), *AAJ (discharge), or *472 (DOS)
    HI (diagnoses)
  Loop 2000F — Service
    HL*6*5*SS*0
    UM (per-service review)
    SV1/SV2/SV3 (line — same shape as 837)
    HSD (quantity / frequency / unit-of-measure)
SE → GE → IEA

UM segment — the request shape

UM carries the kind of services review being requested. Both 2000E and 2000F can carry UMs; 2000E is for the patient-level event, 2000F for each individual service.

UM01 Request Category	Meaning
AR	Admission Review
HS	Health Services Review
IN	Individual
SC	Specialty Care Review
RT	Treatment

UM02 Certification Type	Meaning
I	Initial
R	Renewal
S	Revised
C	Cancel

UM03 Service Type	Meaning
1	Medical Care
47	Hospital
48	Inpatient
49	Outpatient
54	Long Term Care
73	Diagnostic Medical
BU	Psychiatric — Outpatient
MH	Mental Health

UM04 Place of Service	POS code (11 office, 21 inpatient hospital, …)
UM05 Related Causes	Composite — accident, employment, etc.
UM06 Level of Service	E Emergency, U Urgent, R Routine

HSD segment — quantity / frequency

The HSD carries the amount of service being requested:

HSD*VS*30*WK*5*34*1~

Position	Value	Meaning
HSD01	VS	Quantity qualifier — Visits
HSD02	30	Quantity — 30 visits
HSD03	WK	Unit of measure — Week
HSD04	5	Sample selection modulus
HSD05	34	Time period — Months
HSD06	1	Time period count — 1 month

Common quantity qualifiers:

Code	Meaning
DA	Days
MO	Months
MN	Minutes
UN	Units
VS	Visits

Steps

The flow is fully automated — operator awareness exists for the rare case where the gateway needs intervention.

1. A clinician creates an authorization in the rcm-app. The authorization is in DRAFT status.

2. Submit triggers an event — the rcm-core API publishes auth.request_queued to Service Bus.

3. The gateway's auth-request-consumer (see apps/edi-gateway/src/consumers/auth-request-consumer.ts) picks up the event:

   • Resolves the trading partner via routing rules.
   • Allocates ISA / GS / ST control numbers.
   • Composes the 278 by mapping the auth record onto the loop structure.
   • Applies any companion guide bound to 278 for this partner.
   • Submits via the partner's transport.

4. The transaction record appears at /transactions filtered to tx_type = 278, direction outbound, status submitted. Click in to see the segment trace and the source authorization (correlation id back to authorization_request.auth_request_id).

5. Wait for the 278 response (real-time partners respond in seconds; batch partners in minutes-to-hours). See 5.2 — 278 response.

Reading the segment trace

The 278 trace surfaces every loop. Confirm:

• 2000A NM1*X3 carries the UMO's name and ID.
• 2000B NM1*1P carries our provider NPI.
• 2000C NM1*IL carries the subscriber.
• 2000E UM carries the right request category + certification type.
• 2000F UM carries each service's review type.
• 2000F HSD carries the right qty + UOM.
• 2300 HI carries diagnoses if applicable.

A 278 with no 2000F loop is asking for a level-of-care certification at the patient-event level only — valid but unusual for our use cases.

Validation

Check	Expected
278 outbound record appears with status submitted	Yes.
Allocated control numbers are monotonic per partner	Yes — control-number-manager guarantees.
Trace number tracks back to authorization_request row	Yes — via correlation_id.
Test envelope (ISA15 = T) does not produce a real auth at the payer	Yes.

Troubleshooting

Symptom	Cause	Fix
Auth stays in DRAFT after submit	auth.request_failed event raised; consumer rejected the build	Open the transaction; read error_details. Common: missing routing rule, missing UMO snapshot, control-number contention (transient).
278 routed to wrong UMO	Routing rule misconfigured	Edit the routing rule to filter by tx_type = 278 and the program's UMO.
Trace number missing on the 278	Allocated value did not stamp the transaction	Should not happen — file an issue.
278 generates but partner rejects with 999 IK3*UM*…	Service type code or certification type combination not accepted	Check the partner's companion guide for accepted UM combinations.

Next

5.2 — 278 response