Claim Status v2

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The Claims Status API takes the standard established in the X12 EDI 276/277 transaction and translates this standard to JSON so that it is more accessible to developers and easily integrated into users’ applications.

The Request is used by the submitter of the claim to determine the status of a claim previously submitted. The Response is returned by the payer and the information provided indicates where the claim is in the adjudication process (for example, pending, finalized) and if finalized, the disposition of the claim (for example, paid, denied). For denied or rejected, the reason for the denial or rejection is included.

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, using an application such as Postman, or from your own stack.

Try our Postman Collection Run in Postman

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

We sure do. After receiving your client_id and client_secret for our sandbox environment, you can test the API from within our interactive documentation, using an application such as Postman, or from your own stack.

Try our Postman Collection Run in Postman

What information needs to go in the request header?

In the header for a Claim Status API request, you need to pass 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"
}'

This is a precursor to making a Claim Status API call, which might have the following headers:

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

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

When you're ready for production, simply remove sandbox from the URL.

What does a typical API call 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?

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

Sandbox predefined fields and values

The following fields must have one of the canned values provided.

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, it must have the canned value to have a successful response
Note: tradingpartnerserviceid 9496 is a test payer and is the only payer that should be used in sandbox.
If you don't use the provided canned values, you will get errors like 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."
        }
    ]
}

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

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