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
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
Field | Description | C/R |
---|---|---|
controlNumber | Interchange Control Number/ Transaction Set Control Number. ISA13, GS06, ST02, SE02, GE02, IEA02 | 9/9 R |
tradingPartnerServiceId | The payer ID that determines where the transaction is sent. Maps to: Loop 1000A, NM109 | 2/80 R |
tradingPartnerName | Loop 1000A, NM103 If not sent, the value will be ‘unknown’. | 1/60 R |
payerFaxNumber | Fax number of the payer if they do not have electronic connectivity. | 10/20 |
payerAddress |
|
|
Submitter
Name | Loop | Element | Description | C/R |
---|---|---|---|---|
NM1 - SUBMITTER INFORMATION | 1000B | Identification of the provider, including information, such as the organizationName. 1000B NM103 is Required. Either organizationName or lastName is required. | R | |
organizationName | 1000B | NM103 | Submitter Organization Name. NM101 = 41 Submitter NM102 = 2 Non-Person Entity | 1/60 R |
lastName | 1000B | NM103 | Submitter Last Name. NM101 = 41 Submitter NM102 = 1 Person Entity | 1/60 R |
firstName | 1000B | NM104 | Submitter First Name | 1/35 S |
etin | 1000B | NM109 | Electronic 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
andstate
, the TR3 calls them out as Situational in this Guide; these values are required in all United States-based transactions. Elements such asfirstName
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.
Name | Loop | Element | Description | C/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 |
firstName | 1000C | NM104 | Provider First Name | 1/35 S |
middleName | 1000C | NM105 | NM105 when NM102 = 1; LOOP 1000C | 1/35 S |
suffix | 1000C | NM107 | NM105 when NM102 = 1; LOOP 1000C | 1/35 S |
Address (Object) | Required in all submissions. | R | ||
address1 | 1100C | N301 | Provider Address Line 1 | 1/55 R |
address2 | 1100C | N302 | Provider Address Line 2 | 1/55 S |
city | 1100C | N401 | Provider City | 2/30 R |
state | 1100C | N402 | Provider State | 2/2 S |
postalCode | 1100C | N403 | Provider Postal Code | 3/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.
Name | Loop | Element | Description | C/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
Name | Loop | Element | Description | C/R |
---|---|---|---|---|
claimInformation (Object) | 1000D | A 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
Name | Loop | Element | Description | C/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
Name | Loop | Element | Description | C/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
orpayerClaimControlNumber
attributes in the inbound file, Optum replaces these characters with a blank in the ACN in the outbound 275.
Name | Loop | Element | Description | C/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 | |
claimStatusCategoryCode | 2000A | STC01-1 | Health Care Claim Status Category Code | 1/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
Updated 4 months ago