Institutional Claims v1

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The ASC X12N Health Care Claim: Institutional (837i) transaction enables healthcare providers to submit healthcare claims for a service or encounter. A healthcare claim includes patient information, related diagnoses, procedures performed or services provided, and any related charges. This API also translates standard X12 EDI 837i transactions to JSON so that it is more accessible to claim readers and developers.

Prior to submitting an institutional claim, the Institutional Claims Validation endpoint allows the submitter to run claims through extensive repositories of rules and logic in order to correct potential errors before to sending to the payer. This allows for significant savings in time and a higher propensity for acceptance on the first submission.

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 that our 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.

For effective API onboarding and automation, assess the information in your typical transactions to understand the full requirements and best practices for your organization's specific use cases.

API Endpoints

The endpoints for the Institutional Claims API collection are as follows.

  • For the Change Healthcare Medical Network Institutional Claims (Submission) API, the endpoint is:

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

    Use the Submission endpoint to submit transactions to the payer.

  • Use the Validation endpoint to check and validate your upcoming submission. Your transaction will not be sent to the payer:

    https://apis.changehealthcare.com/medicalnetwork/institutionalclaims/v1/validation

  • The Institutional Claims 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/institutionalclaims/v1/healthcheck

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

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

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.

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!

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

Links to Institutional Claims FAQ Topics

You'll find the following topics on this page:

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

What does a typical Institutional Claims API request look like?

What does a typical Institutional Claims API response look like?

What do Institutional Claims error responses look like?

A Note on Institutional Claims for Medicare

How many line items can be on a single claim?

Understanding API Features

Do you bill for a failed claim due to technical error?

A provider has two different teams; one enters the claim and the other verifies and submits it. Before submitting, can they enter the claim, save it and have it released when ready?

What's the difference between a Professional claim and an Institutional claim?

What is the claimReference field in the /Submission response?

Can we electronically bill Worker's Compensation?

Accessing the Institutional Claims API

How do I access the Production APIs?

  • For the Change Healthcare Medical Network Institutional Claims (Submission) API, the endpoint is:

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

    Use the Submission endpoint to submit the actual transaction to the payer.

  • Use the Validation endpoint to check and validate your upcoming submission. Your transaction will not be sent to the payer:

    https://apis.changehealthcare.com/medicalnetwork/institutionalclaims/v1/validation

Both APIs use the same request model.

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 Claim Submission API request header needs an authorization token. You can get the token by making an API call to:

You must pass a Bearer authorization token in the header for an Institutional Claims API request. 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 an Institutional Claims API call, which will have the following headers:

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

NOTE: In production, the lifespan of a Bearer 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.

The Sandbox URLs for this API set are as follows:

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

https://sandbox.apis.changehealthcare.com/medicalnetwork/institutionalclaims/v1/validation

Sandbox predefined fields and values

The following Institutional Claims JSON fields must have one of the listed predefined values shown below.

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: All fields must use a predefined value to have a successful response in the Sandbox.


If you don't use predefined Sandbox values, you will receive 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."
        }
    ]
}

Using the Institutional Claims APIs

What does a typical Institutional Claims API request look like?

The Institutional Claims Submission API uses a POST HTTPS call. 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.

POST https://apis.changehealthcare.com/medicalnetwork/institutionalclaims/v1/[validation|submission] HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization:Bearer <Your-Access-Token>
Content-Type: application/json

{
  "controlNumber": "000000001",
  "tradingPartnerServiceId": "9496",
  "submitter" : {
    "organizationName" : "happy doctors group",
    "taxId":"12345",
    "contactInformation": {
      "name": "janetwo doetwo",
      "phoneNumber": "123456789",
      "email": "email@email.com",
      "faxNumber": "123456789"
    }
  },
  "receiver": {
    "organizationName": "EXTRA HEALTHY INSURANCE",
    "taxId":"67890"
  },
  "subscriber" : {
    "memberId": "0000000001",
    "paymentResponsibilityLevelCode": "P",
    "firstName": "johnOne",
    "lastName": "doeOne",
    "gender": "M",
    "dateOfBirth": "19800101",
    "address": {
      "address1": "123 address1",
      "city": "city1",
      "state": "wa",
      "postalCode": "981010000"
    }
  },
  "providers": [{
    "providerType": "BillingProvider",
    "npi": "1760854442",
    "employerId": "123456789",
    "organizationName": "HAPPY DOCTORS GROUPPRACTICE",
    "address": {
      "address1": "123 address1",
      "city": "city1",
      "state": "wa",
      "postalCode": "981010000"
    }
  }],
  "claimInformation" : {
    "claimFilingCode": "CI",
    "patientControlNumber": "12345",
    "claimChargeAmount": "3.75",
    "placeOfServiceCode": "11",
    "claimFrequencyCode": "1",
    "signatureIndicator": "Y",
    "planParticipationCode": "A",
    "releaseInformationCode": "Y",
    "benefitsAssignmentCertificationIndicator": "Y",
    "billingNote":"ADD",
    "claimDateInformation": {
      "statementBeginDate": "20181209",
      "statementEndDate": "20181214",
      "dischargeHour":"1130",
      "admissionDateAndHour": "201810131242"
    },
    "claimCodeInformation": {
      "admissionTypeCode": "1",
      "patientStatusCode": "10",
      "admissionSourceCode": "7"
    },
    "serviceLines":[{
      "assignedNumber": "1",
      "institutionalService": {
        "serviceLineRevenueCode": "1",
        "lineItemChargeAmount":  "72.50",
        "measurementUnit": "UN",
        "serviceUnitCount": "1"
      }
    }],
    "principalDiagnosis": {
      "qualifierCode": "ABK",
      "principalDiagnosisCode": "S93401A",
      "presentOnAdmissionIndicator":  "Y"
    },
    "admittingDiagnosis":{"qualifierCode": "ABJ",
      "admittingDiagnosisCode": "S93401A"
    },
    "otherSubscriberInformation": {
      "paymentResponsibilityLevelCode": "A",
      "individualRelationshipCode": "19",
      "benefitsAssignmentCertificationIndicator": "Y",
      "claimFilingIndicatorCode": "11",
      "releaseOfInformationCode": "Y",
      "otherPayerName":{
        "otherPayerOrganizationName": "ABC Insurance Co",
        "otherPayerIdentifierTypeCode": "PI",
        "otherPayerIdentifier": "11122333"

      },
      "otherSubscriberName": {
        "otherInsuredQualifier": "1",
        "otherInsuredLastName": "DOE",
        "otherInsuredIdentifierTypeCode": "MI",
        "otherInsuredIdentifier": "123456"
      }

    }
  }
}

What does a typical Institutional Claims API response look like?

Responses to a claim submission are straightforward, consisting mainly of claim reference information:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerId": "RANDOM_ID",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "200319R999898~8430862503386208",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-03-19T14:24:08.253-05:00",
        "claimType": "INS"
    }
}

What do Institutional Claims error responses look like?

If something is wrong with the syntax of the data, you may get a response from our data validation like the below:

{
    "errors": [
        {
            "field": "claimInformation.validReleaseInformationCode",
            "description": "Allowed Values are: 'I' Informed Consent to Release Medical Information for Conditions or Diagnoses Regulated by Federal Statutes,'Y' Yes, Provider has a Signed Statement Permitting Release of Medical Billing Data Related to a Claim"
        }
    ]
}

If the syntax is correct but an error in the format of the claim makes it to the clearinghouse, you may get a response from our Edit engine similar to the following:

{
    "status": "EDITS",
    "controlNumber": "000000001",
    "tradingPartnerId": "RANDOM_ID",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "200331R999898~1612903439033376",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-03-31T16:41:00.895-05:00",
        "claimType": "INS"
    },
    "errors": [
        {
            "field": "03",
            "value": "981010000",
            "description": "When entered, the Billing Provider Postal Code must be nine numeric characters and valid for the state.\n\nLOOP 2010AA N403",
            "location": "2010AA N4"
        }
    ]
}

NOTE: We recommend using the Validation API before sending the claim request to the payer. Validation rules help prevent claims with incorrect information from being sent to the payer, such as a typo in the NPI, errors in calculations, or poor formatting and syntax in the claim. You can also use the Professional Claims Healthcheck API to check on the operating status of the service endpoint before sending the claim.

A Note on Institutional Claims for Medicare

Medicare payers accept claims only for subscribers. If you want to submit a dependent claim with a Medicare payer, submit the dependent as a subscriber in the claim request.

How many line items can be on a single claim?

A single institutional claim supports up to 999 service line items.

Understanding API Features

Do you bill for a failed claim due to technical error?

Every transaction that makes it to the clearinghouse is billable. All errors at the API level, and some errors at the ingress of the clearinghouse, are considered non-billable.

A provider has two different teams; one enters the claim and the other verifies and submits it. Before submitting, can they enter the claim, save it and have it released when ready?

Our APIs don't have a cache/drafting feature. Customers can develop and automate this feature. Customers should hold the claims on their end, and programmatically set up a console to separate working on claims from submitting them.

What's the difference between an Institutional claim and a Professional claim?

Institutional billings use the 837i transaction. Professional billing typically uses the 837p transaction (or the CMS-1500 form in hard copy). We support both types of electronic claims and transactions in separate API products. Institutional billing also sometimes encompasses collections, while Professional claims and billing typically doesn't. Professional billing controls the billing of claims generated for work performed by physicians, suppliers, and other non-institutional providers for both outpatient and inpatient services. People handling Professional claims typically understand both billing and insurance coding. Our APIs help support and automate insurance coding.

What is the claimReference field in the /Submission response?

The claimReference field is an object containing the list of identifiers that you and others can use to track an institutional claim. If questions arise about a claim, you can provide the information listed in the claimReference object to Change Healthcare support for troubleshooting purposes. It appears in all Submission responses for claims, and is shown elsewhere in this FAQ. The list of identifiers may differ depending on the context for the response. Here's an example:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201007R999898~49588871937782918",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-10-07T00:31:07.723-05:00",
        "claimType": "INS"
    }
}

The fields in the claimReference object include the following:

  • correlationId: ID used by support to locate a transaction at the clearinghouse.
  • submitterId: The customer's combined biller ID and submitter ID.
  • customerClaimNumber: ID set by the customer in the claim.
  • patientControlNumber: ID set by the customer in the claim for the patient.
  • timeOfResponse: Timestamp for the response.
  • claimType: The type of claim, Professional or Institutional.
  • formatVersion: EDI format version, will always be 5010 for the current version of the 837 claim.
  • rhclaimNumber: Number assigned by the clearinghouse. You use this value to search for the claim in ConnectCenter.

Can we electronically bill Worker's Compensation?

Yes, our APIs can transmit accident and worker's compensation claims.

Change Log

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

Release Notes:

v1

  • Initial offering of Institutional Claims
  • Updates 12/24/20: This update resolves issues IMNP-21000 and IMNP-21001. Added support for Country and Country Subdivision Codes. Required only when the billing address is not in Canada or in the United States of America, including its territories (e.g. American Samoa). Used when the billing address includes a country and an administrative subdivisions of any type such as states, provinces, or canton. These values reside in the EDI N404 and N407 fields in Loop 2010BA.