Rules as a Service Institutional v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Rules as a Service Institutional API allows the submitter to run claims through extensive repositories of rules and logic in order to correct potential errors before 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 Rules as a Service Institutional 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 Rules as a Service Institutional 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 Raw X12 Validation

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

Raw X12 Validation sandbox.apis.changehealthcare.com/medicalnetwork/institutionalclaims/advanced/v1/raw-x12-validation endpoint can be used to validate your edi request, your transaction will not be sent to the payer.

Both use the same request model.

What does a typical API call look like?

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

POST /medicalnetwork/institutionalclaims/advanced/v1/[validation|raw-x12-validation] 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
Rules as a Service Institutional v1 10/30/20 TBD

Release Notes:

v1

  • Initial offering of Rules as a Service Institutional