Rules as a Service Professional v1

Summary API Attachments FAQ CHANGE LOG     

Overview

The Rules as a Service (RaaS) Professional Claims API enables you to perform claim scrubbing and fix any possible errors before sending the Professional claim to the payer. Using our RaaS Knowledge Packs, our representatives can tailor your RaaS Professional 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 Professional API are as follows.

  • This is the primary Rules as a Service Professional 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 Professional 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 Professional Claims APIs have the following HTTP path:

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

  • The RaaS Professional 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 Professional APIs, see the FAQ page.

Links to RaaS Professional API FAQ Topics

You'll find the following topics on this page:

Accessing the RaaS Professional 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 before signing a contract?

How do I access the Sandbox environment?

Sandbox predefined fields and values

Using the RaaS Professional APIs

What does a typical RaaS Professional Claims API call look like?

Does the RaaS Professional Claims API have a Submission endpoint?

What does a typical API response look like?

How do Raw-X12 Validation requests and responses work?

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 Professional Claims API?

Accessing the RaaS Professional APIs

How do I access the Production APIs?

  • The endpoint URL for authorization tokens is as follows:

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

  • The Rules as a Service Professional API endpoint for rules-based claims validation, is as follows:

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

  • The associated Raw X12 Validation endpoint is as follows:

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

  • The RaaS Professional API Healthcheck endpoint is as follows:

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

How do I submit my edited claims?

The RaaS Professional 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 Professional Claims Submission API (this will incur an additional charge):

    https://apis.changehealthcare.com/medicalnetwork/professionalclaims/v3/submission

  • You may use the the standard Professional 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/professionalclaims/v3/validaion

If you use a different claim submission workflow, you can also submit your claim that way. Consult your Change Healthcare representative for more information.

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 Professional 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 a RaaS Professional API call, which uses 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.

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

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

  • The Sandbox Rules as a Service Professional Raw X12 Validation endpoint is as follows:

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

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

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

Sandbox predefined fields and values

For Sandbox use, the following fields must use one of the following predefined values:

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: For claims APIs, tradingpartnerserviceid 9496 is a test payer and is the only payer that should be used in the Sandbox environment.

If you don't use the predefined sandbox values, you will get 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": "claimInformation",
            "description": "Please use predefined canned users for non-prod environments: patientControlNumber was not predefined."
        }
    ]
}

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

Using the RaaS Professional APIs

What does a typical RaaS Professional Claims API call look like?

The Rules as a Service Professional API uses a POST HTTPS call. You provide the input as JSON in the body of the request. The input is a complete professional claim that you submit as the request body:

{
  "controlNumber": "000000001",
  "tradingPartnerServiceId": "9496",
  "submitter": {
    "organizationName": "REGIONAL PPO NETWORK",
    "contactInformation": {
      "name": "SUBMITTER CONTACT INFO",
      "phoneNumber": "123456789"
    }
  },
  "receiver": {
    "organizationName": "EXTRA HEALTHY INSURANCE"
  },
  "subscriber": {
    "memberId": "0000000001",
    "paymentResponsibilityLevelCode": "P",
    "firstName": "johnone",
    "lastName": "doeOne",
    "gender": "M",
    "dateOfBirth": "19800102",
    "policyNumber": "00001",
    "address": {
      "address1": "123 address1",
      "city": "city1",
      "state": "wa",
      "postalCode": "981010000"
    }
  },
  "dependent": {
    "memberId": "0000000002",
    "paymentResponsibilityLevelCode": "P",
    "firstName": "janeone",
    "lastName": "doeOne",
    "gender": "F",
    "dateOfBirth": "19800102",
    "policyNumber": "00002",
    "relationshipToSubscriberCode": "01",
    "address": {
      "address1": "123 address1",
      "city": "city1",
      "state": "wa",
      "postalCode": "981010000"
    }
  },

  "providers": [{
    "providerType": "BillingProvider",
    "npi": "1760854442",
    "employerId": "123456789",
    "organizationName": "HAPPY DOCTORS GROUPPRACTICE",
    "address": {
      "address1": "000 address1",
      "city": "city2",
      "state": "tn",
      "postalCode": "372030000"
    },
    "contactInformation": {
      "name": "janetwo doetwo",
      "phoneNumber": "0000000001"
    }
  },{
    "providerType": "ReferringProvider",
    "npi": "1942788757",
    "firstName": "johntwo",
    "lastName": "doetwo",
    "employerId" : "123456"
  },{
    "providerType": "RenderingProvider",
    "npi": "1942788757",
    "firstName": "janetwo",
    "lastName": "doetwo",
    "middleName": "middletwo",
    "ssn" : "000000000"
  }],
  "claimInformation": {
    "claimFilingCode": "CI",
    "patientControlNumber": "12345",
    "claimChargeAmount": "28.75",
    "placeOfServiceCode": "11",
    "claimFrequencyCode": "1",
    "signatureIndicator": "Y",
    "planParticipationCode": "A",
    "benefitsAssignmentCertificationIndicator": "Y",
    "releaseInformationCode": "Y",
    "claimSupplementalInformation": {
      "repricedClaimNumber": "00001",
      "claimNumber": "12345"
    },
    "healthCareCodeInformation": [{
      "diagnosisTypeCode": "BK",
      "diagnosisCode": "496"
    },{
      "diagnosisTypeCode": "BF",
      "diagnosisCode": "25000"
    }],
    "serviceFacilityLocation": {
      "organizationName": "HAPPY DOCTORS GROUP",
      "address": {
        "address1": "000 address1",
        "city": "city2",
        "state": "tn",
        "postalCode": "372030000"
      }
      },
    "serviceLines":[ {
      "serviceDate": "20050514",
      "professionalService": {
        "procedureIdentifier": "HC",
        "lineItemChargeAmount": "25",
        "procedureCode": "E0570",
        "measurementUnit": "UN",
        "serviceUnitCount": "1",
        "compositeDiagnosisCodePointers": {
          "diagnosisCodePointers": ["1","2"]
        }
      }
      },
      {
        "serviceDate": "20050514",
        "professionalService": {
          "procedureIdentifier": "HC",
          "lineItemChargeAmount": "3.75",
          "procedureCode": "A7003",
          "measurementUnit": "UN",
          "serviceUnitCount": "1",
          "compositeDiagnosisCodePointers": {
            "diagnosisCodePointers": ["1" ]
          }
        }
        }
    ]

  }
}

What does a typical RaaS Professional 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.

Does the RaaS Professional 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 Professional 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       *200714*1925*|*00501*000000001*0*T*:~GS*HC*testUserName*ECGCLAIMS*20200714*1925*000000001*X*005010X222~ST*837*000000001*005010X222~BHT*0019*00*000000001*20200714*1925*CH~NM1*41*2*REGIONAL PPO NETWORK*****46*009998999898~PER*IC*SUBMITTER CONTACT INFO*TE*123456789~NM1*40*2*EXTRA HEALTHY INSURANCE*****46*CLAIMSCH~HL*1**20*1~NM1*85*2*HAPPY DOCTORS GROUPPRACTICE*****XX*1760854442~N3*000 address1~N4*city2*tn*372030000~REF*EI*123456789~PER*IC*janetwo doetwo*TE*0000000001~HL*2*1*22*1~SBR*P********CI~NM1*IL*1*doeOne*johnone****MI*0000000001~DMG*D8*19800102*M~NM1*PR*2*EXTRA HEALTHY INSURANCE*****PI*9496~HL*3*2*23*0~PAT*01~NM1*QC*1*doeOne*janeone~N3*123 address1~N4*city1*wa*981010000~DMG*D8*19800102*F~CLM*12345*28.75***11:B:1*Y*A*Y*Y~REF*9A*00001~REF*D9*12345~HI*BK:496*BF:25000~NM1*DN*1*doetwo*johntwo****XX*1942788757~NM1*82*1*doetwo*janetwo*middletwo***XX*1942788757~NM1*77*2*HAPPY DOCTORS GROUP~N3*000 address1~N4*city2*tn*372030000~LX*1~SV1*HC:E0570*25*UN*1***1:2~DTP*472*D8*20050514~LX*2~SV1*HC:A7003*3.75*UN*1***1~DTP*472*D8*20050514~SE*38*000000001~GE*1*000000001~IEA*1*000000001~"}

Both JSON and EDI use the same request model.

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

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

Understanding API features

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

Our RaaS Professional 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 Professional 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 a professional claim, much less be integrated into your claims submission software.

Because of this likelihood, you may encounter unexpected errors and incur unexpected delays when filing claims, even when you think your software is 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 Professional Services team monitors regulatory requirements from Medicare and from industry organizations of many different types, and builds the RaaS Knowledge Packs based upon the medical disciplines and the Rules/Edits that apply to them. Using the Knowledge Packs that you order as a match for your business, we tailor your RaaS Professional Claims API to your specific needs. Available Knowledge Packs for Professional Claims include the following:

  • General Billing
  • Ambulance
  • Medicare
  • Durable Medical Equipment (Professional claims only)
  • Post Acute Care
  • Prior Authorization
  • Professional Radiology (Professional claims only)
  • Vision (Professional claims only)
  • Medical Necessity
  • National Correct Coding Initiative (NCCI)
  • 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 a Professional 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 Professional claims; others are supported only by Institutional claims and hence are not listed here.

Does your API support HIPAA Validations?

Our RaaS Professional 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 a Professional claim and an Institutional 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. People handling Professional claims typically understand both billing and insurance coding. Our APIs help support and automate insurance coding.

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

The standard Professional Claims API uses a separate set of rules and logic for scrubbing a professional claim, and is applicable across a range of professional specialties. The RaaS Professional 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 Professional v1 11/17/20 TBD
NOTE:the
Rules as a Service Professional v1 11/17/20 TBD

Release Notes:

v1

  • Initial offering of Rules as a Service Professional
  • Documentation Updates (12/15/2020)