Rules as a Service Institutional v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Rules as a Service (RaaS) Institutional Claims API enables you to perform claim scrubbing and fix any possible errors before sending the institutional claim to the payer. Using our RaaS Knowledge Packs, our representatives can tailor your RaaS institutional Claims error checks and validations to the needs of your medical team. If you need a powerful General Billing capability, or you specialize in Medicare, Ambulance Place of Service, Dialysis, Prior Authorization, and many other options, you can order a Knowledge Pack that matches your medical company's specific Claims requirements.

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.

Try our Postman Collection! Run in Postman

The goal for onboarding is to ensure API customers can automate their API consumption process. For end use, API consumption shouldn't require 'seeing' the APIs; preferably, you can automate a number of tasks:

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

API Endpoints

The endpoints for Rules as a Service Institutional API are as follows.

  • The primary Rules as a Service Institutional Claims Validation API:

    https://apis.changehealthcare.com/medicalnetwork/professionalclaims/advanced/v1/validation

  • The Raw X12 Validation endpoint applies the same logic directly to EDI-formatted request bodies. You can submit the entire claim in X12 EDI format and send it to this API for analysis:

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

  • The RaaS Institutional Claims API 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/professionalclaims/advanced/v1/healthcheck

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

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

  • The standard Institutional Claims APIs have the following HTTP path:

    https://apis.changehealthcare.com/medicalnetwork/professionalclaims/v1/

  • The RaaS institutional API adds the advanced suffix in its path:

    https://apis.changehealthcare.com/medicalnetwork/professionalclaims/advanced/v1/

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're using Postman, after pasting the bearer token into the Authorization page, click Send to test-run the API. If you are using our Postman collection or a similar development console, you can also ensure that the 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 further details about Rules as a Service Institutional APIs, see the FAQ page.

Links to RaaS (Rules as a Service) Institutional Claims FAQ Topics

You'll find the following topics on this page:

Accessing the RaaS Institutional Claims APIs

How do I access the Production APIs?

How do I submit my edited claims?

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 with 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 RaaS Institutional Claims API request look like?

What does a typical API response look like?

Does the RaaS Institutional Claims API have a Submission endpoint?

How do Raw-X12 requests and responses work?

What do RaaS 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

Does Rules as a Service support Assurance-related edit capabilities?

What is the biggest value-add from using this API?

Does your API support HIPAA Validations?

What's the difference between this API and the Claims Lifecycle AI API?

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

What's the difference between this API and the regular Institutional Claims API?

Accessing the RaaS Institutional Claims API

How do I access the Production APIs?

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

  • The Rules as a Service (RaaS) Institutional API endpoint for rules-based claims validation, is as follows:

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

  • The associated Raw X12 Validation endpoint is as follows:

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

  • The RaaS Institutional Healthcheck API endpoint is as follows:

    https://apis.changehealthcare.com/medicalnetwork/institutionalclaims/advanced/v1/healthcheck

How do I submit my edited claims?

The RaaS Institutional Claims APIs are designed for advanced rules-based checking and validation of Institutional claims, based on medical business specialties. It does not submit your claim to the payer.

  • You can submit your completed claims to the payer through the standard Institutional Claims Submission API (this will incur an additional charge):

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

  • You may use the the standard Institutional Claims API validation endpoint to check and validate your upcoming submission. It applies a different set of rules that don't affect or repeat the functions from the RaaS Institutional API. Your transaction will not be sent to the payer:

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

You can also use your in-house claim submission workflow.

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.

NOTE: Click here to find out more about our security protocols.

What information needs to go in the API request header?

You must pass a Bearer authorization token in the header for a RaaS Institutional Claims API request. You can get the token by sending an API request 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 with 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.

  • For testing, the Sandbox Rules as a Service Institutional API endpoint is as follows:

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

  • For Raw X12 validation:

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

  • The Sandbox's RaaS Institutional API Healthcheck endpoint is as follows:

    https://sandbox.apis.changehealthcare.com/medicalnetwork/institutionalclaims/advanced/v1/healthcheck

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: TradingPartnerServiceId 9496 is a test payer and is the only payer allowed for use in Sandbox.

If you don't use predefined Sandbox values, you will receive errors such as 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": "subscriber",
            "description": "Please use predefined canned users for non-prod environments: policyNumber was not predefined."
        }
      }
    ]
}

NOTE: Data fields must use a predefined value to have a successful response in the Sandbox.

Using the RaaS Institutional Claims APIs

What does a typical RaaS Institutional Claims 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. The input is a complete institutional claim that you submit as the request body. The RaaS Institutional validation API engine evaluates the request body and responds with messages indicating success or listing the issues with the claim:

{
  "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 UNIVERSITY HOSPITAL",
    "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"
      }

    }
  }
}

What does a typical RaaS Institutional Claims API response look like?

If the /validation endpoint successfully evaluates an institutional claim, you'll get a summary message stating so, with the basic claim reference information:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "200925R639534~847432178458572",
        "submitterId": "395795639534",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-09-25T18:13:48.136-05:00",
        "claimType": "PRO",
        "formatVersion": "5010"
    }
}

When the validation API encounters issues, it will list each in the reply:

{
    "status": "EDITS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201117R999898~53196482361992277",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-11-17T17:46:02.792-06:00",
        "claimType": "INS"
    },
    "errors": [
        {
            "field": "01",
            "value": "1",
            "description": "The Type of Admission is required and must be valid.\n\nLOOP 2300 CL101",
            "location": "2300 CL1"
        },
        {
            "field": "claimInformation.otherSubscriberInformation.validIndividualRelationshipCode",
            "description": "Allowed Values are: '01' Spouse, '18' Self, '19' Child, '20' Employee, '21' Unknown, '39' Organ Donor, '40' Cadaver Donor, '53' Life Partner, 'G8' Other Relationship"
        }
    ]
}

Some error listings will also show the EDI loop and segment in which the error occurred. Other errors, such as the second listed above, show any fields that are missing relevant information for the claim.

Does the RaaS Institutional Claims API have a Submission endpoint?

No, it does not. When you finish evaluating and correcting your claim through this rules-based API, you can submit your corrected claim through the standard Change Healthcare Institutional Claims API, or through your accustomed workflow for that task.

How do Raw-X12 Validation requests and responses work?

You can use the Rules as a Service Raw-X12 Validation endpoint to validate your EDI request; your transaction will not be sent to the payer. A sample request appears in EDI format:

{"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 HOSPITAL CHAIN*****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~"}

Both JSON and EDI endpoints use the same API request model.

Your responses appear in JSON format, including any errors that the API engine discovers.

NOTE: When your EDI formatted request is corrected and validated, use your normal claim submission workflow to submit the claim.

Understanding API features

Does Rules as a Service support Assurance-related edit capabilities?

Our RaaS Institutional Claims API supports Level 100, Level 200, General Bill and customers that do not log into Assurance to access Edit updates (headless customers). Our specialty Knowledge Packs encompass these requirements based upon each medical specialty.

What is the biggest value-add from using this API?

For all RaaS Institutional API applications, be familiar with the term Edits, which has a specific meaning in this context.

Payers control their own claims edit specifications. Edit specifications govern how medical practices must submit correct claims information for payer processing and approvals or disapprovals. Claims Edits can change at any time, and notifications of these changes may or may not reach you before you submit an institutional claim, much less be integrated into your claims submission software.

Because of this likelihood, you may encounter unexpected errors and incur delays when filing claims, even when you think your software and processes are up to date.

These issues can occur at any time. Some medical practices may subscribe to continuous payer updates and submission edits, and receive their notifications from the payer. Others may not do so, finding the costs prohibitive. The RaaS Institutional Services team monitors regulatory requirements from Medicare and from industry organizations of many different types, and develops the RaaS Knowledge Packs based upon the Packs' medical disciplines and the Rules/Edits that apply to them.

We continuously track and follow the Rules/Edits changes so you don't have to. Using the Knowledge Packs that you order as a match for your business, we tailor your RaaS Institutional Claims API to your specific needs. Currently available Knowledge Packs for Institutional Claims include the following:

  • General Billing
  • Ambulance
  • Dialysis/End Stage Renal Disease (ESRD) (Institutional claims only)
  • Medicare
  • Post Acute Care
  • Prior Authorization
  • Rural FQHC (Institutional claims from Rural Health Clinics and Federally Qualified Health Centers)
  • Medical Necessity
  • National Correct Coding Initiative (NCCI)
  • Therapy (Institutional claims with Therapy Revenue Code, HCPCS/CPT-4 codes)
  • Validation Codes

Providers of each of the various Edit/Rule types select the Knowledge Pack that fits their needs. Rules within each category also may apply to specific Payers. For example, rules within the Durable Medical Equipment pack may be applicable for Aetna or for Medicare.

Another benefit: not all fields in an Institutional Claim request will be applicable for every service. A single claim may be a very substantial request body. Our Rules and Knowledge Packs enable you to narrow your claims down to the bodies of information that are only necessary for your claim type.

NOTE: Edits are directly comparable to individual validation rules in our API, hence we use the term Rules as a Service for our API.


The majority of RaaS Claims Edit categories support both Professional and Institutional claims. Some Edit/Rule categories are supported only through Institutional claims; others are supported only by Professional claims and hence are not listed here.

Does your API support HIPAA Validations?

Our RaaS Institutional Claims EDI supports the following Edit Types and compliance checking for HIPAA Types 1 through 7:

  • Type 1 EDI Standard Integrity Testing: Validate basic syntactical integrity of the EDI submission.
  • Type 2 HIPAA Implementation Guide Requirement Testing: Validate HIPAA requirement-guide-specific syntax requirement by checking limits on repeat counts, used or not used qualifiers, code, elements, and segments.
  • Type 3 HIPAA Balance Testing: Validate that claim line items amounts are equal to total claim amount.
  • Type 4 HIPAA Inter-Segment Situation Testing: Validate inter-segment relationship. For example, if element A exists, then element B must be populated.
  • Type 5 HIPAA External Code Set Testing: Validate specific code set values for HIPAA standards.
  • Type 6 Product Type/Type of Service Testing: Validate that segments that differ based on certain Healthcare services are properly created and processed.
  • Type 7 Trading Partner-Specific Testing: Compliance with payer specific requirement.

What's the difference between this API and the Claims Lifecycle AI API?

The Claims Lifecycle AI API flags claims based on the volume of all claims of particular types that Change Healthcare observes in its API data flows. Using machine learning, it detects discrepancies and gives a percentage likelihood for denial of a claim. Rules as a Service does not use machine learning; it relies on lengthy Rule/Edit collections for many medical specialties to validate your claims. Consider Claims Lifecycle AI API to be a complementary API for grooming and claim scrubbing.

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

Professional billing typically uses the 837p transaction (or the CMS-1500 form in hard copy); Institutional billings use the 837i transaction. We support both types of electronic claims and transactions. Institutional billing also sometimes encompasses collections while Professional claims and billing typically don'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. Our APIs help support and automate insurance coding.

What's the difference between this API and the regular Institutional Claims API?

The standard Institutional Claims API uses a separate set of rules and logic for scrubbing an institutional claim, and is automatically applicable across a range of institutional specialties. It can also be considered complementary to the RaaS Institutional APIs. The RaaS Institutional Claims API provides greater specialization through the selection of Knowledge Packs to support your provider's medical specialties.

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
  • 12/31/2020: Updates to Documentation