Institutional Claims v1

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

The Institutional Claims API takes the standard established in the 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 submission, the 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

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 an Claim Submission 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 Institutional Claims API call, which would have the header:

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

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

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

Validation and Submission

Validation

sandbox.apis.changehealthcare.com/medicalnetwork/institutionalClaims/v1/validation endpoint can be used to validate your request, your transaction will not be sent to the payer.

Submission

sandbox.apis.changehealthcare.com/medicalnetwork/institutionalClaims/v1/submission endpoint will actually submit your transaction to the payer.

Both use the same request model.

What does a typical API call look like?

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

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


What does a typical API response look like?

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


Example Error Response

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 like the below:

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

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 as an alternative to waiting for the payer to return a rejection.

Error Codes:

Further information on API error codes can be found here.


Medicare Scenario

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

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

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