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.

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

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 Claims Status APIs are as follows.

  • The primary Claims Status endpoint:

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

  • The Claims Status collection also provides a GET /healthcheck call to check that the service you're trying to use is up and running:

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

  • Each of our API collections also contains an endpoint for obtaining new authorization tokens:

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

For further details about Claims Status API usage, see the FAQ page.

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 are using our Postman collection or a similar development console, ensure your 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.

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!

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

Can I check for the status of multiple claims in a single transaction?

How frequently can I check the status of pending claims?

What does a typical API request look like?

What does a typical API response look like?

What is the Tracking Number field?

What claim identifiers are needed in the Claim Status request?

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

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

Find out more about our security protocols and their implementation here.

What information needs to go in the request header?

You must pass a Bearer authorization token in the header for an Claim Status 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"
}'

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 Sandbox usage, all fields must have the correct predefined values to obtain a successful response. Inventing new PMI values or using real-world PMI values will result in errors such as the messages listed below.

The following JSON fields must use one of the following predefined values in Sandbox:

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.


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."
        }
    ]
}

Using the Claim Status APIs

How frequently can I check the status of pending claims?

A general recommendation is every 5-7 days. A customer can determine if that fits their needs and adjust as necessary.

Can I check for the status of multiple claims in a single transaction?

A claim status request supports several search options like claims for a member or service. If it isn't specific to just one, the payer can respond with all the claims that fit that description.

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.

{
    "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"
}

What is the Tracking Number field?

The trackingNumber field is a value that you can use at your discretion. It will accept any value and is not required. It exists so that you can link the 277 response back to your original request, and the payer will always echo this value back exactly as you sent it.

What claim identifiers are needed in the Claim Status request?

Several identifier options exist in the request to help the payer find the correct claim to provide status on: the payer’s claim number, dates of service, claim amount, type of bill, patient control number, etc. Send as much information in the claim status request as you have available for best results.

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

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. Claim Reports and Responses is a fetching tool for claims information from your mailbox. For more information, go to the Claims Responses and Reports API page.

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:

v1

  • Initial offering of claim status

v2

  • Security and Authorization changes in v3
  • Host and url changes
  • Documentation updates