Claims Responses and Reports v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Claims Responses and Reports API provides a direct connection to your mailbox where payers will send their responses and reports to your claims. Use this API to access your mailbox for claim payments, claim status updates, and other communications regarding the revenue cycle from the payer.

API Onboarding

Most of our APIs are private and require credentials to gain access. Begin by obtaining your client_id and client_secret for our sandbox test environment. (Contact your Change Healthcare representative if you do not have this information.)

Find out more about our security protocols and their implementation.

NOTE: You use a separate Change Healthcare-issued credential pair for your production API work.

You can test the APIs from within our interactive documentation, use an application such as Postman, or use your own development platform. You use a separate Change Healthcare-issued secret pair for your production API work.

Try our Postman Collection! Run in Postman

The goal for onboarding is to ensure API customers can automate their API consumption process. For end use, API consumption shouldn't require 'seeing' the APIs; preferably, a number of tasks can be automated:

  • API bearer token automation, using OAuth2 token retrieval.
  • A data entry console to make claims requests and eligibility requests. It's a characteristic feature of medical facilities where public medical encounters take place.
  • Abstraction of the majority of complex data that's required for a successful request, so you can easily make requests and get replies efficiently without confusion. For example, Control Numbers exist in all of our APIs as a required value that's generated, assigned and sent by the provider or institution to identify each transaction. When the provider's office sends a request, they should never have to worry about defining and entering those values, and they should be handled programmatically.
  • Auditing and tracking for all transactions.

For token automation, you can apply one of the following:

  • Get a unique token for each transaction.
  • Apply the same token across all transactions in the full token lifespan (tokens for production APIs have a two-hour/7200 second lifespan) and automatically refresh the token just before it expires.

NOTE: We suggest automating token generation over the token lifespan, or close to it, instead of tokenizing each individual transaction.

API Endpoints

Endpoints for the Reports APIs are as follows.

  • Access your mailbox with a GET request to /medicalnetwork/reports/v1:

    https://apis.changehealthcare.com/medicalnetwork/reports/v1/

    This endpoint returns a list of all the available reports.

    A single report can be opened with a GET request to the same endpoint with the file name appended to the end:

    https://apis.changehealthcare.com/medicalnetwork/reports/v1/{filename}

Using the APIs

In our interactive documentation, select the API tab, and select the green POST API object. Scroll down to the Authorization field, enter the word Bearer, and paste your token into the Bearer Token field.

Many of our API collections also provide a GET /healthcheck call to check that the service you're trying to use is up and running.

If you're using Postman, after pasting the bearer token into the Authorization page, click Send to test-run the API. If you are using our Postman collection or a similar development console, you can also ensure that the client_id and client_secret for your production account are installed in your Authorization API's request body, or that you set up your environment variables to refer to these credentials whenever you require a token. If you correctly set up your environment variables, you can install the collection in Postman (for example), and simply run the Authorization API to obtain a token whenever you need it, which will automatically be used by the other APIs in the collection.

See the Reports FAQ page for more information.

Links to Reports FAQ Topics

You'll find the following topics on this page:

Accessing the Reports APIs

How do I access the Production APIs?

What are the endpoints for getting authorization tokens?

What information needs to go in the API Request header?

Using the Reports Sandbox environment

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

How do I access the Sandbox environment?

Sandbox predefined fields and values

Using the Reports APIs

What is the supported date format?

What does a typical Reports API request and response look like?

What does the filename structure mean?

What does a typical EDI response look like?

Where can I look up Reports File Name and File Types?

What's the difference between Claim Status and Claim Reports and Responses?

Accessing the Reports APIs

How do I access the Production APIs?

Endpoints for the Reports APIs are as follows.

  • Access your mailbox with a GET request to /medicalnetwork/reports/v1:

    https://apis.changehealthcare.com/medicalnetwork/reports/v1/

    This endpoint returns a list of all the available reports.

    A single report can be opened with a GET request to the same endpoint with the file name appended to the end:

    https://apis.changehealthcare.com/medicalnetwork/reports/v1/{filename}

What are the endpoints for getting authorization tokens?

  • The endpoint URL for authorization tokens is as follows:

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

Bearer tokens have a two-hour lifespan (7200 seconds) in production.

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

What information needs to go in the API Request header?

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

curl -X POST \
  'https://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 any Reports API call, which will have the following headers:

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

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

Using the Sandbox environment

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

How do I access the Sandbox environment?

  • The Sandbox endpoint URL for authorization tokens is as follows:

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

    Authorization tokens have a lifespan of 3600 seconds (1 hour) in the Sandbox environment.

  • For testing, the Sandbox Claim Status API endpoint is as follows:

    https://sandbox.apis.changehealthcare.com/medicalnetwork/reports/v1/

  • The Healthcheck Sandbox URL for this API set is as follows:

    https://sandbox.apis.changehealthcare.com//medicalnetwork/reports/v1/healthcheck

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"

NOTE: TradingPartnerServiceId 9496 is a test payer and is the only payer allowed for use in Sandbox.

Using the Reports APIs

What information needs to go in the request header?

You must pass a Bearer authorization token in the header for an Reports API request. 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"
}'
  • For testing, the Sandbox Claims Responses & Reports API endpoint is as follows:

    https://sandbox.apis.changehealthcare.com/medicalnetwork/reports/v1/

  • The Healthcheck Sandbox URL for this API set is as follows:

    https://sandbox.apis.changehealthcare.com//medicalnetwork/reports/v1/healthcheck

What information needs to go in the request header?

You must pass a Bearer authorization token in the header for an Reports API request. 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"
}'

This is a requirement for making an Reports API call, which might have the following headers:

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

The Reports API uses a GET HTTPS call:

GET /medicalnetwork/reports/v1 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json

Read more about our protocols in the Security -> Authorization section of this portal.

Further examples follow.

What is the supported date format?

The date format is YYYYMMDD with the year as a four-digit number.

What does a typical Reports API request and response look like?

The core request does not send a request body, and simply queries the customer's list of files:

https://apis.changehealthcare.com/medicalnetwork/reports/v1/

The API returns a complete listing of all documents available to a customer:

{
    "reports": [
        "05011338.00",
        "XB200654.PV",
        "XB200654.N2",
        "XB200654.QH",
        "XB200654.OE",
        "XB200654.OK",
        "06271006.00",
        "report.0405090800",
        "XB200654.OP",
        "XB200654.KG",
        ...
    ]
}

What does the filename structure mean?

The API returns a list of file names with the following structure:

AAnnnnnn.XX

where:

  • AA = the two character prefix that designates the type of file
  • nnnnnn = the six digit submitter ID
  • XX = the two character extension that separates files. Files begin with the prefix AA, AB, AC….A0, A1, A2…..BA, BB, BC…..ending with W9 before rolling back to AA (excluding the AU, BK, DB, DV, GI, GW, HT, JS, QT, RA, RP and WM prefixes as these are reserved).

The most common reports are the Claim Status Response (X3) and the Claim Remittance (R5). Electronic reports also exist to support all available transactions, including medical statements and Electronic Remittance Advice (ERA).

What does a typical report's EDI response look like?


{ "report_content": "ISA~00~ ~00~ ~ZZ~CLAIMSCH ~ZZ~010414 ~180511~1112~|~00501~100321569~0~P~^_TA1~020120501~131121~1506~A~000_GS~FA~ECGCLAIMS~K10353~20180511~1112~000000001~X~005010X231A1_ST~999~0001~005010X231A1_AK1~HC~1~005010X223A1_AK2~837~00704~005010X223A1_IK5~A_AK9~A~000001~000001~000001_SE~0000000006~0001_GE~000001~000000001_IEA~00001~100321569_" }

Where can I look up Reports File Name and File Types?

Review the File_Name_Matrix file in the Attachments tab.

What's the difference between Claim Status and Claim Responses and Reports?

Claim Status' main task is to check the status of a claim in the payer’s system. If a provider hasn't received a payer report on a claim, or if they have not received payment, they run a claim status request to find out the most recent status of that claim. Note that when a claim is paid, the claim status response from the payer provides only basic payment details, and excludes details such as payer adjustments to the total charge, the patient copays and coinsurance, and so on.

Claim Responses and Reports is a tool to fetch claims information files from your mailbox. For more information about the Claim Status API, go to the Claim Status API page

Change Log

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

Release Notes:

v1

  • Initial offering of Reports API from Change Healthcare

v1.1

  • 1) Update to add /277 and /835 EDI-to-JSON translation API endpoints
  • 2) Documentation updates