Claim Status v2

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The Claims Status API supports the X12 EDI 276 transaction. It translates this standard to JSON for developer accessibility and integration into users’ applications.

We also support a dedicated Raw X12 Claims Status API to format your submission in X12 EDI format. It supports the standard syntax for a complete X12 EDI 276 transaction set.

The submitter uses a Claim Status request to ask about the status of a previously submitted claim. The payer returns the response, as an X12 EDI 277 transaction, which is translated back to JSON by the API gateway. It describes where the claim is in the adjudication process (for example, Pending or Finalized).

If the claim is finalized, the response provides the disposition of the claim (for example, Paid, or Denied). For denied or rejected outcomes, the response includes the reason for the denial or rejection.

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.)

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

Using the API

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.

For Sandbox API testing, you can also edit the request body. We provide a set of predefined values that you can apply to see how the API works with key claim data, and predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. For successful use of Sandbox APIs, you must use these "fake patient" values for your testing. Check the FAQ tab -> Sandbox predefined fields and values section for details. Avoid using real-world values in our Sandbox API endpoints!

Raw-X12 EDI Support

We also support a traditional X12 EDI request if you choose to implement the 276 transaction set in its native EDI format. The 277 transaction responses you receive will also appear in EDI format.

The Claims Status Raw-X12 endpoint is as follows:

https://apis.changehealthcare.com/medicalnetwork/claimstatus/v2/raw-x12

See the Claims Status FAQ page for more information.

Links to Claim Status FAQ Topics

You'll find the following topics on this page:

Accessing the Claims Status 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 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 Claim Status APIs

What does a typical API request look like?

What does a typical API response look like?

How do Raw-X12 Requests and Responses work?

Accessing the Claim Status APIs

How do I access the Production APIs?

For the Change Healthcare Claim Status API, the endpoint is:

https://apis.changehealthcare.com/medicalnetwork/claimstatus/v2/

Claim Status also offers a Healthcheck API, with which you can check the operating status of the cloud-based API engine:

https://apis.changehealthcare.com//medicalnetwork/claimstatus/v2/healthcheck

A separate Claim Status API supports the X12 EDI standard if you choose to implement the 276 transaction set in its native EDI format. The 277 transaction responses you receive will also appear in EDI format.

The Claims Status Raw-X12 endpoint is as follows:

https://apis.changehealthcare.com/medicalnetwork/claimstatus/v2/raw-x12

What information needs to go in the request header?

The Claim Status 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 a Claim Status 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.

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/

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

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

We have a list of test service ID values to use in Sandbox for testing a variety of different responses. See the section Sandbox predefined fields and values below.

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/claimstatus/v2/

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

https://sandbox.apis.changehealthcare.com//medicalnetwork/claimstatus/v2/healthcheck

Sandbox predefined fields and values

You can edit fields in the HTTP request body to see how the API works with changes to the data. For Sandbox use, you are limited to a specific set of values for experimenting. 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. For Sandbox usage, it must have a correct predefined value to have a successful response.

Note: tradingpartnerserviceid 9496 is a test payer and is the only payer allowed for use in Sandbox.

If you don't use the predefined Sandbox values, the Sandbox will display errors such as the following:

{
    "errors": [
        {
            "field": "claimInformation.claimSupplementalInformation",
            "description": "Please use predefined canned users for non-prod environments: claimNumber was not predefined."
        },
        {
            "field": "subscriber",
            "description": "Please use predefined canned users for non-prod environments: policyNumber was not predefined."
        },
        {
            "field": "claimInformation",
            "description": "Please use predefined canned users for non-prod environments: patientControlNumber was not predefined."
        },
        {
            "field": "providers[0]",
            "description": "Please use predefined canned users for non-prod environments: employerId was not predefined."
        },
        {
            "field": "providers[1]",
            "description": "Please use predefined canned users for non-prod environments: lastName was not predefined."
        },
        {
            "field": "subscriber.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[0].address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[0].contactInformation",
            "description": "Please use predefined canned users for non-prod environments: phoneNumber was not predefined."
        },
        {
            "field": "claimInformation.serviceFacilityLocation.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "dependent.address",
            "description": "Please use predefined canned users for non-prod environments: city was not predefined."
        },
        {
            "field": "providers[2]",
            "description": "Please use predefined canned users for non-prod environments: lastName was not predefined."
        }
    ]
}

Using the Claim Status APIs

What does a typical API request look like?

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

POST /medicalnetwork/claimstatus/v2 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json

{
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "serviceId",
    "providers": [{
        "organizationName": "TestProvider",
        "taxId": "0123456789",
        "providerType": "BillingProvider"
    },
    {
        "organizationName": "happy doctors group",
        "npi": "1760854442",
        "providerType": "ServiceProvider"
    }],
    "subscriber": {
        "memberId": "0000000000",
        "firstName": "johnone",
        "lastName": "doeone",
        "gender": "M",
        "dateOfBirth": "18800102",
        "groupNumber": "0000000000"
    },
    "dependent": {
        "firstName": "janeone",
        "lastName": "doeone",
        "gender": "F",
        "dateOfBirth": "18800101",
        "groupNumber": "0000000000"
    },
    "encounter": {
        "beginningDateOfService": "20100101",
        "endDateOfService": "20100102",
        "trackingNumber": "ABCD"
    }
}

What does a typical API response look like?

Responses to our Medical Network APIs can be lengthy due to the many data points that a payer or trading partner provides in the query response. Our APIs translate back and forth between JSON and X12 EDI when the information departs into, and returns from, the medical network. We also support Raw X12 APIs should you wish to directly communicate using that data format.

{
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "serviceId",
    "providers": [
        {
            "organizationName": "TestProvider",
            "taxId": "0123456789",
            "providerType": "BillingProvider"
        },
        {
            "organizationName": "happy doctors group",
            "npi": "1760854442",
            "providerType": "ServiceProvider"
        }
    ],
    "subscriber": {
        "firstName": "johnone",
        "lastName": "doeone",
        "memberId": "0000000000"
    },
    "claims": [
        {
            "claimStatus": {
                "statusCategoryCode": "F1",
                "statusCategoryCodeValue": "Finalized/Payment-The claim/line has been paid.",
                "statusCode": "65",
                "statusCodeValue": "Claim/line has been paid.",
                "entityCode": "1E",
                "entity": "Health Maintenance Organization (HMO)",
                "effectiveDate": "20170415",
                "submittedAmount": "1229",
                "amountPaid": "219",
                "paidDate": "20170415",
                "checkIssueDate": "20170415",
                "checkNumber": "1111111",
                "trackingNumber": "000000001",
                "claimServiceDate": "20160722",
                "tradingPartnerClaimNumber": "AAAAAAAAAAA1"
            }
        },
        {
            "claimStatus": {
                "statusCategoryCode": "F3",
                "statusCategoryCodeValue": "Finalized/Revised - Adjudication information has been changed",
                "statusCode": "101",
                "statusCodeValue": "Claim was processed as adjustment to previous claim.",
                "entityCode": "1E",
                "entity": "Health Maintenance Organization (HMO)",
                "effectiveDate": "20170412",
                "submittedAmount": "1229",
                "amountPaid": "184.05",
                "trackingNumber": "C1234567891028297LL",
                "claimServiceDate": "20160722",
                "tradingPartnerClaimNumber": "AAAAAAAAAAA2"
            }
        },
        {
            "claimStatus": {
                "statusCategoryCode": "F3",
                "statusCategoryCodeValue": "Finalized/Revised - Adjudication information has been changed",
                "statusCode": "101",
                "statusCodeValue": "Claim was processed as adjustment to previous claim.",
                "entityCode": "1E",
                "entity": "Health Maintenance Organization (HMO)",
                "effectiveDate": "20161201",
                "submittedAmount": "1229",
                "amountPaid": "219",
                "trackingNumber": "C1234567891028297LL",
                "claimServiceDate": "20160722",
                "tradingPartnerClaimNumber": "AAAAAAAAAAA3"
            }
        }
    ],
    "reassociationKey": "000000001",
    "status": "success"
}

How do Raw-X12 Claim Status requests and responses work?

We support a traditional X12 EDI request if you choose to implement the 276 transaction set in its native EDI format. The 277 transaction responses you receive will also appear in EDI format.

The Claims Status Raw-X12 endpoint is as follows:

https://apis.changehealthcare.com/medicalnetwork/claimstatus/v2/raw-x12

An X12 EDI 276 Claim Status request appears as the following:

POST /medicalnetwork/claimstatus/v2/raw-x12 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
    "x12": "ISA*00*          *01*password  *ZZ*something      *ZZ*EMDEON         *200729*0835*^*00501*000000001*0*P*:~GS*HR*LCX1210000*MTEXE*20200729*0835*000000001*X*005010X212~ST*276*000000001*005010X212~BHT*0010*13*000000001*20200729*0835~HL*1**20*1~NM1*PR*2*Unknown*****PI*serviceId~HL*2*1*21*1~NM1*41*2*TestProvider*****46*0123456789~HL*3*2*19*1~NM1*1P*2*happy doctors group*****XX*1760854442~HL*4*3*22*1~DMG*D8*18800102*M~NM1*IL*1*doeone*johnone****MI*0000000000~HL*5*3*23*0~DMG*D8*18800101*F~NM1*QC*1*doeone*janeone~TRN*1*ABCD~REF*6P*0000000000~DTP*472*RD8*20100101-20100102~SE*18*000000001~GE*1*000000001~IEA*1*000000001~"
}

An X12 EDI 277 response appears similar to the following:

{
    "x12": "ISA*00*          *01*SomePwd*ZZ*EMDEON         *ZZ*TPG00000*201006*1752*^*00501*000000001*0*T*:~GS*HN*MTEXE*LCX1210000*20131015*2219*000000001*X*005010X212~ST*277*000000001*005010X212~BHT*0010*08*000000001*20200729*0835*DG~HL*1**20*1~NM1*PR*2*Unknown*****PI*serviceId~HL*2*1*21*1~NM1*41*2*TestProvider*****46*0123456789~HL*3*2*19*1~NM1*1P*2*happy doctors group*****XX*1760854442~HL*4*3*22*0~NM1*IL*1*doeone*johnone****MI*0000000000~TRN*2*000000001~STC*F1:65:1E*20170415**1229*219*20170415**20170415*1111111~REF*1K*AAAAAAAAAAA1~DTP*472*D8*20160722~TRN*2*C1234567891028297LL~STC*F3:101:1E*20170412**1229*184.05~REF*1K*AAAAAAAAAAA2~DTP*472*D8*20160722~TRN*2*C1234567891028297LL~STC*F3:101:1E*20161201**1229*219~REF*1K*AAAAAAAAAAA3~DTP*472*D8*20160722~SE*23*000000001~GE*1*000000001~IEA*1*000000001~"}

Change Log

API Name API Version Date Introduced Available Until
Claim Status v2 4-17-19
Claims Status v1 1-1-19 Deprecated

Release Notes:

v2

  • Security and Authorization changes in v3
  • host and url changes

v1

  • Initial offering of claim status