Attachments Submission v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Attachments Submission API supports the X12 EDI 275 Patient Information transaction. It translates this standard to JSON, so it is more accessible to developers for integration into users’ applications.

An attachment, in the context of healthcare electronic data interchange (EDI), is an electronic rendition of medical documentation, such as an X-ray, lab report, or questionnaire, to support a healthcare administrative transaction.

Change Healthcare supports the following formats for 275 attachments: JPG, BMP, GIF, TIF, TIFF, PDF, DOC, DOCX, TXT, RTF, JPEG, and PNG.

Change Healthcare’s attachment solution includes workers’ compensation attachments and medical attachments. Any receiver who does not support electronic attachments will receive the documentation via fax or mail.

API Onboarding

See the Security and Authorization section in this portal to learn more about using our APIs. Most of our APIs are private and require credentials to gain access.

After receiving your client_id and client_secret for our sandbox environment, you can test the API from within our interactive documentation, use an application such as Postman, or exercise the API from your own console. You use a separate Change Healthcare-issued secret pair for your production API work.

Try our Postman Collection! Run in Postman

Documentation

For details on the request model, see the FAQ tab. This documents the field names and examples of the request.

In depth mapping of the JSON field to the X12 EDI can be found in the Attachments tab.

Links to Attachments Submissions FAQ Topics

You'll find the following topics on this page:

Do you have a sandbox that I can test before signing a contract?

What information needs to go in the API Request header?

What are the endpoints for getting authorization tokens?

How do I access the Production APIs?

What does a typical API call look like?

How do Raw-X12 Requests and Responses work?

What does a typical API response look like?

Sandbox predefined fields and values

Trading Partners and Attachment Requirements

Example Contract for Request

How do I use an Optional payerFaxNumber?

How do I use an Optional payerAddress?

What are some Typical Errors and Error codes?

How do I Call the statusList Endpoint?

Do you have a sandbox that I can test before signing a contract?

We do! You can use our Sandbox environment even before signing a contract. It requires a separate set of secure credentials which you can obtain from your Change Healthcare representative. After receiving your client_id and client_secret for our Sandbox environment, you can test the API in our interactive documentation, use an application such as Postman, or test APIs using your own development console.

Try our Postman Collection! Run in Postman

What information needs to go in the API request header?

The Attachments Submission API request header needs an authorization token. You can get the token by making an API call to:

curl -X POST \
  'https://sandbox.apis.changehealthcare.com/apip/auth/v2/token' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "<Your-ClientId>",
  "client_secret": "<Your-ClientSecret>",
  "grant_type": "client_credentials"
}

The authorization token is a requirement for making an API call, which will have the following headers:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>

What are the endpoints for getting authorization tokens?

The Sandbox endpoint URL for authorization tokens is as follows:

https://sandbox.apis.changehealthcare.com/apip/auth/v2/token/

The Production endpoint URL for authorization tokens is as follows:

https://apis.changehealthcare.com/apip/auth/v2/token/

In production, the lifespan of a token is two hours (7200 seconds). For Sandbox use, a token lifespan is one hour.

Find out more about our security protocols in the Security -> Authorization section of this portal.

How do I access the Production APIs?

When you're ready for production, simply remove sandbox from the URL. For example, the Sandbox URL for this API is as follows:

https://sandbox.apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/

For Production:

https://apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/

Attachment Submissions also supports the Concord Fax cloud fax solution for handling paper documents:

https://apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/uploads/

To use Uploads and fax, you'll need to add the file name to the attachmentDetails section of the request body, or an error will occur:

      },
      "attachmentDetails": {
        "name": "attachments_rightarm.jpg"
      }
    }]
  }
}' \
  -F files=@~/images/attachments_rightarm.jpg

What does a typical API call look like?

The API uses a POST HTTPS call. You provide the input as JSON in the body of the request:

curl -X POST \
  https://sandbox.apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/uploads \
  -H 'Accept: application/json' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'request={
  "controlNumber": "123459999",
  "tradingPartnerServiceId": "9497",
  "submitter": {
    "organizationName": "happy doctors grouppractice",
    "etin": "1942788757"
  },
  "provider": {
    "organizationName": "happy doctors group",
    "npi": "1760854442",
    "address": {
      "address1": "123 address1",
      "city": "city1",
      "state": "wa",
      "postalCode": "981010000"
    },
    "phoneNumber": "123456789",
    "faxNumber": "123456789"
  },
  "subscriber": {
    "memberId": "0000000001",
    "firstName": "johnone",
    "lastName": "doeone"
  },
  "claimInformation": {
    "patientControlNumber": "12345",
    "beginClaimServiceDate": "20050513",
    "endClaimServiceDate": "20050514",
    "serviceLines": [{
      "payerClaimControlNumber": "123456789",
      "serviceLineDateInformation" : {
          "submissionDate" : "20050514"
      },
      "attachmentDetails": {
        "name": "attachments_rightarm.jpg"
      }
    }]
  }
}' \
  -F files=@~/images/attachments_rightarm.jpg

How do Raw-X12 Requests and Responses work?

We support a traditional X12 EDI request if you choose to implement the 275 transaction set in its native EDI format.

The Attachments Submission Raw-X12 request endpoint is:

https://apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/raw-x12

An X12 EDI 275 Attachments Submission request appears similar to the following:

{"x12": "ISA*00*          *01*          *ZZ*56781234       *ZZ*1234           *200805*1750*|*00501*123459999*0*T*:~GS*PI*56781234       *ATTCHMENTCH    *20200805*1750*123459999*X*005010X210~ST*275*123459999*005010X210~    BGN*11*123456789*20200805~NM1*PR*2*unknown*****PI*9497~NM1*41*2*happy doctors grouppractice*****46*1942788757~NM1*1P*2*happy doctors group*****XX*1760854442~NX1*1P*~N3*123 address1~N4*city1*wa*981010000~NM1*QC*1*johnone*doeone****MI*0000000001~REF*EJ*12345~    DTP*472*RD8*20050514-20050515~LX*1~TRN*2*123456789~                    DTP*368*D8*20050514~    CAT*AE*MB~    EFI*05~    BIN*92366*Mime-version: 1.0 Content-Type: image/jpeg Content-Transfer-Encoding: base64 Content-Disposition: attachment filename=attachments_rightarm.jpg <FILE DATA HERE>~SE*18*123459999~GE*1*123459999~IEA*1*123459999~"}

See examples from our postman collection for this API: Run in Postman

Note: This API submits via form-data. The form will appear as part of the Body page in Postman, for example.

Note: The controlNumber field must be unique per request.

What does a typical API response look like?

Responses will be the same whether the submission is made using the standard API or the Raw-X12 API:

{
    "status": "success",
    "attachmentId": "4182d4b5-9f0c-4f69-b31c-f63fb4acdcd1_9497_1234"
}

Note: You can use the attachmentId value to get the status.

Sandbox predefined fields and values

The following fields for Sandbox Attachment Submission requests must have one of the predefined Sandbox values listed below. The following fields must use one of the following predefined values.

Field Values
memberId "0000000000", "0000000001", "0000000002", "1234567890", "0000000004", "0000000005", "0000000006","0000000007", "123456789"
firstName "johnone", "johntwo", "janeone", "janetwo"
lastName "doeone", "doetwo"
middleName "middleone", "middletwo"
gender "m", "u", "f"
dateOfBirth "18800102", "18800101", "18160421", "19800101", "19800102", "20000101", "20000102"
ssn "000000000", "555443333", "1111111111", "000000001", "891234567", "123456789"
groupNumber "0000000000", "1111111111","1234567891","0000000001", "0000000002", "0000000003", "0000000004", "0000000005"
address1 "123 address1", "000 address1"
address2 "apt 123", "apt 000", "123", "000"
city "city1", "city2"
state "wa", "tn"
postalCode "981010000", "372030000"
employerId "00000", "12345","00001","00002","000000000", "123456789","123456"
propertyCasualtyClaimNumber "00000", "12345","00001","00002"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
repricedClaimNumber "00000", "12345","00001","00002"
investigationalDeviceExemptionNumber "00000", "12345","00001","00002"
claimNumber "00000", "12345","00001","00002"
name "johnone doeone", "johntwo doetwo", "janeone doeone", "janetwo doetwo", "submitter contact info"
phoneNumber "0000000000", "123456789", "0000000001", "0000000002"
faxNumber "0000000000", "123456789", "0000000001", "0000000002"
email "email@email.com", "email@email.net"
stateLicenseNumber "0000000", "0000001", "123456"
contractVersionIdentifier "111111", "222222", "123456"
patientControlNumber "00000", "12345","00001","00002"
priorAuthorizationNumber "00000", "12345","00001","00002"
referralNumber "00000", "12345","00001","00002"
claimControlNumber "00000", "12345","00001","00002"
cliaNumber "12D4567890", "00D0000001"
repricedClaimNumber "00000", "12345","00001","00002"
mammographyCertificationNumber "00000", "12345","00001","00002"
medicalRecordNumber "00000", "12345","00001","00002"
demoProjectIdentifier "00000", "12345","00001","00002"
carePlanOversightNumber "00000", "12345","00001","00002"
policyNumber "00000", "12345","00001","00002"
npi "1760854442", "1942788757"
organizationName "happy doctors group", "happy doctors grouppractice","extra healthy insurance", "regional ppo network"

The field can appear at any level of the request model, but it must have a predefined value to have a successful Sandbox response.

If you don't use Sandbox predefined values, you will get errors like the following:

{
    "traceId": null,
    "tradingPartnerId": null,
    "tradingPartnerServiceId": null,
    "status": null,
    "files": [],
    "errors": [
        {
            "field": "subscriber",
            "description": "Please use predefined users for non-prod environments: firstName was not predefined."
        }
    ]
}

Trading Partners and Attachments Requirements

  • 3657: Workers Compensation Institutional
  • 5861: Workers Compensation Professional
  • 83867: QualLynx
  • 84146: CHAMPVA - HAC
  • 12115: VA Fee Basis Programs
  • LACAR: LA Care
  • 14163: WELLCARE HEALTH PLAN
  • PIPREPAY: Payment Integrity

For non-electronic payers, always use the actual Payer ID and Payer Name values. You can look up the complete list of Payer IDs and their names on the Change Healthcare Payer IDs page.

Any tradingPartnerServiceId can be used to send a fax to the payer by setting payerFaxNumber on the request.

"payerFaxNumber": "fax number of the payer",

Any tradingPartnerServiceId can be used to send a physical mail to the payer by setting payerAddress on the request.

"payerAddress" : { "address1": "123 address1", "city": "city1", "state" : "wa", "postalCode": "981010000"},

Example Contract for Request

{
  "controlNumber": "controlNumber",
  "tradingPartnerId": "tradingPartnerId",
  "tradingPartnerServiceId": "LOOP 1000A; NM109",
  "tradingPartnerName": "LOOP 1000A NM103",
  "payerFaxNumber": "fax number of the payer",
  "payerAddress": {
        "address1": "",
        "address2": "",
        "city": "",
        "state": "",
        "postalCode": ""
  },
  "submitter": 
    {
      "organizationName": "LOOP 1000B NM103",
      "firstName": "LOOP 1000B NM104",
      "lastName": "LOOP 1000B NM103",
      "etin": "LOOP 1000B NM109; "
    },
  "provider":
    {
      "organizationName": "LOOP 1000C NM103",
      "lastName": "LOOP 1000C NM103",
      "firstName": "LOOP 1000C NM104",
      "middleName": "LOOP 1000C NM105",
      "suffix": "LOOP 1000C NM107",
      "npi": "LOOP 1000C NM109",
      "taxonomyCode": "LOOP 1000C PRV03",
      "providerCommercialNumber": "Loops to 1000C; Maps to REF02; REF01=G2",
        "locationNumber": "Loops to 1000C; Maps to REF02; REF01=LU",
        "stateLicenseNumber": "Loops to 1000C; Maps to REF02; REF01=0B",
        "providerUpinNumber": "Loops to 1000C; Maps to REF02; REF01=1G",
      "address": 
         {
           "address1": "LOOP 1100C",
           "address2": "LOOP 1100C; maps N302",
           "city": "LOOP 1100C; N401",
           "state": "LOOP 1100C; N402",
           "postalCode": "LOOP 1100C; N403"
         },
      "phoneNumber": "Used in fax cover sheet",
      "faxNumber": "Used in fax cover sheet"
    },
  "subscriber": 
    {
      "memberId": "LOOP 1000D NM segment; NM108=MI",
      "firstName" : "LOOP 1000D NM segment; NM104",
      "lastName" : "LOOP 1000D NM segment; NM103"
    },
  "claimInformation":
    {
      "patientControlNumber": "LOOP 1000D REF=EJ segment",
      "billingTypeIdentifier": "LOOP 1000D REF=BLT",
      "medicalRecordIdentifier": "LOOP 1000D REF=EA",
      "claimNumber": "LOOP 1000D REF=D9",
      "beginClaimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=RD8",
      "endClaimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=RD8",
      "claimServiceDate": "LOOP 1000D DTP segment; DTP01=472; DTP02=D8",
      "serviceLines":[ //Note: for each serviceLine, we will add LX segment and keep incrementing LX01
      {
        "payerClaimControlNumber": "LOOP 2000A; TRNO1=2; Payer Claim Control Number is the value from the TRN segment loop 2200D of the 277 when in response to a solicited request",
        "providerAttachmentControlNumber" : "LOOP 2000A TRN01=1; For the unsolicited 275, the Attachment Control Number is the value from PWK06 loop 2300 of the 837. This is the main matching criteria and must be unique on a per attachment basis.",
        "claimStatus": [
          {
            "claimStatusCategoryCode": "LOOP 2000A; STC01-1",
            "additionalInformationRequestCode": "LOOP 2000A; STC01-2"
          }],
        "providerControlNumber": "LOOP 2000A; REF01=6R",
        "lineItemControlNumber": "LOOP 2000A; REF01=FJ",
        "procedureOrRevenueDetails": 
          {
            "procedureOrRevenueCode": "LOOP 2000A; REF01; valid values: CPT, F8, FO, PRT,RB, VP, YJ, ZZ",
            "procedureOrRevenueValue": "value of the code provided in REF01; this would be REF02",
            "revenueCode": "LOOP 2000A; REF04-02"
          },
        "procedureCodeModifier": 
          {
            "serviceChangeNumber": "LOOP 2000A; REF01=SK; REF02",
            "objectCode" : "LOOP 2000A; REF04-1=XX4; REF04-2",
            "systemNumber": "LOOP 2000A; REF04-3=06; REF04-4",
            "specialPaymentReferenceNumber": "LOOP 2000A; REF04-5=4N; REF04-6"
          },
        "serviceLineDateInformation": 
          {
            "serviceDate": "LOOP 2100A; DTP01=472; DTP03=value; DTP02=D8",
            "beginServiceDate": "LOOP 2100A; DTP01=472; DTP03=value ; DTP02=RD8",
            "endServiceDate": "LOOP 2100A; DTP01=472; DTP03=value ; DTP02=RD8",
            "submissionDate": "LOOP 2100B; DTP01=472; DTP03=value; DTP02=D8"
          },
        "attachmentDetails": 
          {
              "name": "Should match a file name sent with Form-Data files, Used to complete LOOP 2110B; BIN02 and LOOP 2110B; BIN01"
          }
      }
    ]
  }
}

How do I use an Optional payerFaxNumber?

This is the payer fax number that can be used to send a digital fax to the payer. If payerfaxNumber is present and the trading partner is not set up for 275 transactions, a fax will be sent due to your request.

How do I use an Optional payerAddress?

When the trading partner is not set up for 275 transactions, and the payerFaxNumber is not present i.e. they don't support a fax, then the attachment can be printed and mailed to the payer if payerAddress is present. -->

What are some Typical Errors and Error codes?

Example errors:

{
    "status": "errors",
    "attachmentId": null,
    "errors": [
        {
            "description": "Unable to process the request at this time, please try again later"
        }
    ]
}
{
    "status": "errors",
    "attachmentId": null,
    "errors": [
        {
            "field": "Segment: STC",
            "location": "Loop: 2000, Segment Position: 13",
            "description": "Required Segment Missing"
        }
    ],
    "transactionSetAcknowledgement" : "Rejected",
    "implementationTransactionSetSyntaxError" : "One or More Segments in Error"
}

Error Codes: https://developers.changehealthcare.com/apis/error_info

How do I Call the statusList Endpoint?

curl --location --request POST https://sandbox.apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/statusList \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your-Access-Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "startDate": "2020-04-16 15:20:42.939259-04:00",
    "endDate": "2020-05-12 15:20:42.939259-04:00"
}'

If you pass size in the request you can specify the max size of attachments in the current dataset before using pagination. By default size is 1000.

curl --location --request POST https://sandbox.apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/statusList \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your-Access-Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "startDate": "2020-04-16 15:20:42.939259-04:00",
    "endDate": "2020-05-12 15:20:42.939259-04:00",
  "size": 200
}'

If you need to use pagination, pass lastEvaluatedSubmission in the request body and set it to the last record of the current dataset.

curl --location --request POST https://sandbox.apis.changehealthcare.com/medicalnetwork/attachments/submission/v1/statusList \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your-Access-Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "startDate": "2020-04-16 15:20:42.939259-04:00",
    "endDate": "2020-05-12 15:20:42.939259-04:00",
  "lastEvaluatedSubmission": {
    "transactionSubmittedDate": "2020-04-21 17:50:11.514391-04:00",
    "transactionTraceId": "c062268a-8aea-4ced-9c73-f845c42a0001"
  }
}'

Change Log

API Name API Version Date Introduced Available Until
Attachments Submission v1 11/01/19 TBD

Release Notes:

v1

  • Initial offering of attachmets submission

v1 05/14/2020

  • Adding statusList endpoint