Attachment Submissions API JSON-to-EDI Contents

Use our OpenAPI Spec JSON file as a reference for development. Notes on the data in the following sections include:

  • The Constraints column describes the minimum and maximum number of alphanumeric characters that a field entry can occupy: for example, 1/60 R is a Required field with a minimum of one and maximum of 60 characters.
  • If a field is required, the Constraints entry notes it.

For the Constraints column in each table, the following letters stand for specific meanings:

  • R = Required (must be used if/when the object is part of the transaction);
  • S = Situational (may be required depending on how the transaction content is structured).

Situational loops, segments, or elements can be Situational in two forms:

  • Required IF a condition is met, but can be used at the discretion of the sender if it is not required (for example, some descriptive notes can be added to a claim if necessary);
  • Required IF a condition is met, but if not, the sender must not use it in the request ("Do not send").

📘

NOTE

To obtain a license that also provides access to the full requirements for these transactions, visit https://x12.org/licensing. We make every effort to ensure consistency between our APIs and the X12 TR3. If there is a discrepancy, the X12 TR3 is the final authority.

Table of Mappings Tables

Header

Submitter

Provider

Subscriber

Claim Information

Service Lines

📘

NOTE

The OpenAPI Spec file for this API lists out the complete contents of the Attachment Submission request body. In the file, look for the Request object. Whenever you submit a request with an unsolicited or solicited attachment, it will contain instances of all the other JSON objects that are described in this document and in the OpenAPI Spec.

Header

Table Key: C/R: C= field constraints, R = Required

FieldDescriptionC/R
controlNumberInterchange Control Number/ Transaction Set Control Number.
ISA13, GS06, ST02, SE02, GE02, IEA02
9/9 R
tradingPartnerServiceIdThe payer ID that determines where the transaction is sent.
Maps to: Loop 1000A, NM109
2/80 R
tradingPartnerNameLoop 1000A, NM103 If not sent, the value will be ‘unknown’.1/60 R
payerFaxNumberFax number of the payer if they do not have electronic connectivity.10/20
payerAddress
  • address1: Payer Address Line 1
  • address2: Payer Address Line 2
  • city: Payer City
  • state: Payer State
  • postalCode: Payer Postal Code
  • 1/55 R
  • 1/55 S
  • 2/30 R
  • 2/2 S
  • 3/15 S

Submitter

NameLoopElementDescriptionC/R
NM1 - SUBMITTER
INFORMATION
1000BIdentification of the provider, including information, such as the organizationName.
1000B NM103 is Required. Either organizationName or lastName is required.
R
organizationName1000BNM103Submitter Organization Name. NM101 = 41
Submitter NM102 = 2 Non-Person Entity
1/60 R
lastName1000BNM103Submitter Last Name. NM101 = 41 Submitter
NM102 = 1 Person Entity
1/60 R
firstName1000BNM104Submitter First Name1/35 S
etin1000BNM109Electronic Transmitter
Identification Number (ETIN)
NM108 = 46
If not sent, your onboarded
Submitter Id will be used.
2/80 S

Provider

📘

NOTE

For all REF segment identification values postalCode and state, the TR3 calls them out as Situational in this Guide; these values are required in all United States-based transactions. Elements such as firstName apply when the provider entity type is a person and not a non-person entity, and possesses a first name. In other words, these are required for virtually all transactions and should be treated as such.

NameLoopElementDescriptionC/R
Provider (Object)


1000C


NM103


The providers involved with the medical claim.
1000C NM103 is Required.
Either organizationName or lastName
is required.
R


  organizationName


1000C


NM103


Provider Organization Name.
NM101 = 1P Provider
NM102 = 2 Non-Person Entity
1/60
R

  lastName


1000C


NM103


Provider Last Name.
NM101 = 1P Provider
NM102 = 1 Person Entity
1/60
R

  firstName1000CNM104Provider First Name1/35 S
  middleName1000CNM105NM105 when NM102 = 1; LOOP 1000C1/35 S
  suffix1000CNM107NM105 when NM102 = 1; LOOP 1000C1/35 S
  Address (Object)Required in all submissions.R
    address11100CN301Provider Address Line 11/55 R
    address21100CN302Provider Address Line 21/55 S
    city1100CN401Provider City2/30 R
    state1100CN402Provider State2/2 S
    postalCode1100CN403Provider Postal Code3/15 S
  taxonomyCode




1000C




PRV03




Provider Taxonomy Code.
Required: when the payer’s
adjudication is impacted
by the provider taxonomy code
PRV01 = BI PRV02 = PXC
1/50
S



REF - PROVIDER SECONDARY
IDENTIFICATION




1000C




REF




Note: A 1000C REF02
is required when the provider is
not covered under the NPI
mandate. When required,
use one of the following fields.
S




  providerCommercialNumber

1000C

REF02

Provider Commercial Number
REF01 = G2
1/50
S
  locationNumber

1000C

REF02

Provider Location Number
REF01 = LU
1/50
S
  stateLicenseNumber

1000C

REF02

Provider State License Number
REF01 = 0B
1/50
S
  providerUpinNumber

1000C

REF02

Provider UPIN Number REF01 = 1G

1/50
S

Patient

Basic information about the patient.

NameLoopElementDescriptionC/R
memberId


1000D


NM109


Patient Primary Identifier.
NM101 = QC Patient
NM108 = MI Member Identification Number
2/80
R

lastName

1000D

NM103

Patient Last Name NM101 = QC
Patient NM102 = 1 Person
1/60
R
firstName

1000D

NM104

Patient First Name

1/35
S

📘

NOTE

For some Loop 1000D NM segment identification values, the TR3 calls them out as Situational as does this Guide; these values are required in all United States-based transactions. Elements such as firstName are an example. On rare occasions, the patient may not use or have a first name; this field will otherwise be required for virtually all transactions and should be treated as such.

Claim Information

NameLoopElementDescriptionC/R
claimInformation (Object)1000DA key block of medical coding information that defines the actual procedures and services rendered for the medical encounter. It contains other JSON blocks including the serviceLines objects that contain the professionalService line item charges and diagnosis information.Required
  patientControlNumber


1000D


REF02


Patient Control Number Identifier. It tracks
the claim from creation by the provider through its payment. REF=EJ
1/50
R

  billingTypeIdentifier





1000D





REF02





Bill Type Identifier.
Required if the Institutional Type of Bill from the submitted claim is available from the payer and is included in the 2200D REF segment of the 277.
REF=BLT
1/50
S




  medicalRecordIdentifier



1000D



REF02



The Medical Record Identification
Number from the original claim.
Required when the original claim submits this value.
REF=EA
1/50
S


  claimNumber



1000D



REF02



Clearinghouse Trace Number.
Required when the payer sends the Claim ID number in the 277's 2200D REF segment.
REF=D9
1/50 S



  Claim Service Dates





1000D





Required when the submitted
or requested information
applies to the entire claim.
Either the Claim Service Date (1000D DTP3)
or Service Line Date of Service (2100A DTP3)
must be in place.
S





  beginClaimServiceDate


1000D


DTP03


Claim Start Date when service date
is a range. DTP01=472 (Service) and
DTP02=RD8 (Range CCYYMMDD-CCYYMMDD)
1/35
S

  endClaimServiceDate


1000D


DTP03


Claim End Date when service date is a range.
DTP01=472 (Service) and DTP02=RD8
(Range CCYYMMDD-CCYYMMDD)
1/35
S

  claimServiceDate



1000D



DTP03



Claim Service Date Use when service occurs on a single day.
DTP01=472 (Service) and DTP02=D8
(Format CCYYMMDD)
1/35
S


Attachment Details

NameLoopElementDescriptionC/R
AttachmentDetails
(Object)
CAT and BIN; LOOP 2100B and 2110B

  name




2100B




Should match a file name sent with Form-Data files.
File name is max 50 characters and cannot include:
# ,%, $, {}, *, |, ~, ^
Use to complete LOOP 2110B;
BIN01 and LOOP 2110B; BIN02.

Service Line Date Information

NameLoopElementDescriptionC/R
ServiceLineDateInformation (Object)

CAT and BIN; LOOP 2100B and 2110B
Cross-referenced in serviceLines object

Service Lines

📘

NOTE

If any standard character delimiters (underscore (_), tilde (~), up caret (^), and pipe (|)) are present in the providerAttachmentControlNumber or payerClaimControlNumber attributes in the inbound file, Optum replaces these characters with a blank in the ACN in the outbound 275.

NameLoopElementDescriptionC/R
Service Detail

2000A

Each service line adds an LX segment and continues incrementing LX01.
controlNumber



2000A



See
below


The 2000A TRN02 is required.
The value can only be either
the ‘Payer Claim Control Number’ or
the ‘Provider Attachment Control Number’.
R



payerClaimControlNumber



2000A



TRN02



Payer Claim Control Number TRN01 = 2
Payer Claim Control Number is the value
from the 277's TRN segment loop 2200D,
in response to a solicited request.
1/50



providerAttachmentControlNumber







2000A







TRN02







Provider Attachment Control Number.
TRN01 = 1.
For the unsolicited 275, the Attachment
Control Number is the value
in element PWK06, loop 2300 of the 837. It is the main matching criteria and must be unique
on a per attachment basis.
1/50







claimStatus (Object)







2000A







Conveys the status of the entire claim
or a specific service line.
Required for submitting an Attachment for a 277 Claim Status request.
This object contains the values
found in the STC segment of the 277.
When this is required, both STC01-1
and STC01-2 are required.
S







  claimStatusCategoryCode2000ASTC01-1Health Care Claim Status Category Code1/30
  additionalInformationRequestCode



2000A



STC01-2



LOINC® Code that defines any
requested information.
Identifies the status of
an entire claim or a service line.
1/30



  providerControlNumber









2000A









REF02









Provider Control Number.
Required when the added information
is associated with the service line
or revenue line information.
Used with unsolicited attachments
(BGN01=02).
This is the Provider Control Number
for the line reported in the 837,
in loop 2400 of the original claim.
REF01=6R
1/50
S








  lineItemControlNumber






2000A






REF02






Service line item Control Number.
Required when the new information
is associated with the service line
or revenue line information.
Used for solicited attachments (BGN01=11).
It is the 277's Line Item Control Number.
REF01=FJ
1/50
S





procedureOrRevenueDetails (Object)2000A
  procedureOrRevenueCode



2000A



REF01



Procedure or Revenue Code
Required if the new information ties to
the service line or revenue line data.
Values: CPT, F8, FO, PRT, RB, VP, YJ, ZZ
2/3
S


  procedureOrRevenueValue



2000A



REF02



Procedure Code or Revenue Code.
If a procedure code and a revenue code
both identify a service line item,
REF04 must report the revenue code.
1/50
S


  revenueCode




2000A




REF04-2




Revenue Code.
If a procedure code and a revenue code
both identify a service line item,
the revenue code must be reported
in REF04. REF04-1 = YJ
1/50
S



procedureCodeModifier (Object)2000A
  serviceChangeNumber



2000A



REF02



Procedure Code Modifier.
Required when the procedure code
on the original claim includes modifiers.
REF01=SK
1/50
S


  objectCode



2000A



REF04-2



Object Code.
Required when the original claim
includes more than one modifier.
REF04-1=XX4
1/50
S


  systemNumber



2000A



REF04-4



System Number.
Required when the original claim
includes more than two modifiers.
REF04-3=06
1/50
S


  specialPaymentReferenceNumber



2000A



REF04-6



Special Payment Reference Number.
Required when the original claim
includes more than 3 modifiers.
REF04-5=4N
1/50
S


serviceLineDateInformation
(Object)



Required when the date of service
is not reported at the claim level.
Either the Claim Service Date
(1000D DTP3) or the Service Line
Date of Service (2100A DTP3) must exist.
S




  beginServiceDate


2100A


DTP03


Service Start Date
DTP01=472 (Service) and DTP02=RD8
(Range CCYYMMDD-CCYYMMDD)
1/35
S

  endServiceDate


2100A


DTP03


Service End Date
DTP01=472 (Service) and DTP02=RD8
(Range CCYYMMDD-CCYYMMDD)
1/35
S

  serviceDate


2100A


DTP03


Service Date (singular).
DTP01=472 (Service) and DTP02=D8
(Format CCYYMMDD)
1/35
S

  submissionDate


2100B


DTP03


Submission Date.
DTP01 = 368 (Submittal) and DTP02=D8
(Format CCYYMMDD)
1/35
R

Related Topic