Institutional Claims v1

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The Institutional Claims API takes the standard X12 EDI 837i transaction and translates this standard to JSON so that it is more accessible to developers and easily integrated into users’ applications.

The ASC X12N Health Care Claim: Institutional (837i) transaction allows 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.

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.

X12 EDI Support

We also support dedicated Raw X12 Institutional Claims APIs to format your validations and submissions in X12 EDI format. It supports the standard syntax for a complete X12 EDI 837i transaction set.

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

Links to Institutional Claims FAQ Topics

You'll find the following topics on this page:

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

What information needs to go in the API request header?

What are the endpoints for getting authorization tokens?

How do I access the Production APIs?

What does a typical Institutional Claims API call look like?

What does a typical API response look like?

How do Raw-X12 requests and responses work?

What are the Institutional Claims Raw-X12 endpoints?

What do Institutional Claims error responses look like?

A Note on Institutional Claims for Medicare

Sandbox predefined fields and values

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


What information needs to go in the request header?

The Claim Submission 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 an Institutional Claims 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 Sandbox endpoint URL for authorization tokens is as follows:

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

The Production 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.

How do I access the Production APIs?

When you're ready for production, simply remove sandbox from the URL. For example, 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

For Production:

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

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

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

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

Both use the same request model.

What does a typical Institutional Claims API call look like?

The Institutional Claims 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.

Example Request JSON

POST /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": "20041209",
      "statementEndDate": "20041214",
      "dischargeHour":"1130",
      "admissionDateAndHour": "200410131242"
    },
    "claimCodeInformation": {
      "admissionTypeCode": "1",
      "patientStatusCode": "10",
      "admissionSourceCode": "7"
    },
    "serviceLines":[{
      "assignedNumber": "1",
      "institutionalService": {
        "serviceLineRevenueCode": "1",
        "lineItemChargeAmount":  "72.50",
        "measurementUnit": "UN",
        "serviceUnitCount": "1"
      }
    }],
    "principalDiagnosis": {
      "qualifierCode": "BK",
      "principalDiagnosisCode": "99761",
      "presentOnAdmissionIndicator":  "Y"
    },
    "admittingDiagnosis":{"qualifierCode": "BJ",
      "admittingDiagnosisCode": "99762"
    },
    "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"
      }

    }
  }
}

Note: tradingpartnerserviceid 9496 is a test payer and is the only payer that should be used in the Sandbox environment.*


What does a typical API response look like?

Example Institutional Claims JSON Response

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

How do Raw-X12 requests and responses work?

We also support a traditional raw X12 EDI request if you choose to implement the X12 837i transaction set in its native EDI format. An Institutional Claims X12 EDI request appears as the following:

{
  "x12": "ISA*00*          *01*CYCTRANS  *ZZ*009998999898   *ZZ*CLAIMSCH       *200723*1401*|*00501*000000001*0*T*:~GS*HC*009998999898*1465*20200723*1401*000000001*X*005010X223A3~ST*837*000000001*005010X223A3~BHT*0019*00*000000001*20200723*1401*CH~NM1*41*2*happy doctors group*****46*009998999898~PER*IC*janetwo doetwo*EM*email@email.com~NM1*40*2*EXTRA HEALTHY INSURANCE*****46*CLAIMSCH~HL*1**20*1~NM1*85*2*HAPPY DOCTORS GROUPPRACTICE*****XX*1760854442~N3*123 address1~N4*city1*wa*981010000~REF*EI*123456789~HL*2*1*22*0~SBR*P*18*******CI~NM1*IL*1*doeOne*johnOne****MI*0000000001~N3*123 address1~N4*city1*wa*981010000~DMG*D8*19800101*M~NM1*PR*2*EXTRA HEALTHY INSURANCE*****PI*9496~CLM*12345*3.75***11:A:1**A*Y*Y~DTP*096*TM*1130~DTP*434*RD8*20041209-20041214~DTP*435*DT*200410131242~CL1*1*7*10~NTE*ADD*ADD~HI*BK:99761:::::::Y~HI*BJ:99762~SBR*A*19*******11~OI***Y***Y~NM1*IL*1*DOE*****MI*123456~NM1*PR*2*ABC Insurance Co*****PI*11122333~LX*1~SV2*1**72.50*UN*1~SE*32*000000001~GE*1*000000001~IEA*1*000000001~"
}

Because the X12 EDI standard for Institutional Claims doesn't define a corresponding EDI response, the Raw-X12 API returns the response in JSON format:

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

What are the Institutional Claims Raw-X12 Endpoints?

The Institutional Claims Raw-X12 endpoints are as follows:

https://apis.changehealthcare.com/medicalnetwork/institutionalclaims/v1/raw-x12-submission

For Institutional Claims Validation:

https://apis.changehealthcare.com/medicalnetwork//institutionalclaims/v1/raw-x12-validation

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: These validation rules and edits are in place to prevent claims with incorrect information from making it to the payer. This gives you a chance to correct the claim and avoid claim rejections from the payer.

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.

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"

A field can appear at any level of the request model, but it must have the predefined value to have a successful response in the Sandbox.

Note: tradingpartnerserviceid 9496 is a test payer and is the only payer that should be used in 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."
        },
        {
            "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."
        }
    ]
}

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