Professional Claims v3

Summary API Attachments FAQ CHANGE LOG   
awss
  

Overview

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

The ASC X12N Health Care Claim: Professional (837P) 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. Use the Validation API to check and validate your upcoming submission. Your transaction will not be sent to the payer. The validation does not examine the actual contents of your claim; it checks for the correct well-formed syntax of the submission, and elements such as correctly summing service line charges and verifying codes.

About Claims Validation

Prior to submission, the Professional Claims Validation endpoint allows the submitter to run claims through extensive repositories of rules and logic to detect potential errors before submitting to the payer. By enabling you to correct mistakes, you can gain significant savings in time and a higher chance for acceptance on the first submission.

API Endpoints

The Professional Claims API endpoints are as follows.

  • Use the Validation endpoint to check your request:

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

    The Validation endpoint does not send your transaction to the payer.

  • The Submission endpoint submits your transaction to the payer:

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

    The Validation and Submission endpoints both use the same request model.

  • The Professional Claims API Healthcheck service endpoint is:

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

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. You use a separate Change Healthcare-issued secret pair for your production API work.

Try our Postman Collection! Run in Postman

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

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

For effective API onboarding and automation, assess the information in your typical transactions to understand the full requirements and best practices for your organization's specific use cases.

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 are using our Postman collection or a similar development console, ensure your 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 Sandbox API testing, you can also edit the request body. We provide a set of predefined values that you can apply to see how the API works with key claim data, and predefined values to simulate Personal Medical Information (PMI) in the Sandbox environment. For successful use of Sandbox APIs, you must use these "fake patient" values for your testing. Check the FAQ tab -> Sandbox predefined fields and values section for details. Avoid using real-world values in our Sandbox API endpoints!

For further details about Institutional Claims API usage, see the FAQ page.

Links to Professional Claims FAQ Topics

You'll find the following topics on this page:

Accessing the Professional Claims APIs

What are the Professional Claims API endpoints?

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 Professional Claims APIs

What does a typical Professional Claims API request look like?

What do Professional Claims Validation API responses look like?

What do Professional Claims Submissions API responses look like?

Understanding API features

Do you bill for a failed claim due to technical error?

A provider has two different teams; one enters the claim and the other verifies and submits it. Before submitting, can they enter the claim, save it and have it released when ready?

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

What is the claimReference field in the Submission response?

How many line items can be on a single claim?

Accessing the Professional Claims APIs

NOTE:Use the Validation API to test your request and prevent claims with incorrect information from being sent to the payer. This gives you a chance to correct the claim, avoid delays, and reduce claim rejections from the payer.

What are the Professional Claims API endpoints?

  • Use the validation endpoint to check your request:

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

    Validation does not send your transaction to the payer. It checks for the correct well-formed syntax of your submission.

  • The Submission endpoint submits your transaction to the payer:

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

    The Validation and Submission endpoints both use the same request model.

  • The Professional Claims API Healthcheck service endpoint is:

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

What are the endpoints for getting authorization tokens?

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.

What information needs to go in the API Request header?

The Professional Claims API request header must 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"
}'

The authorization token is a requirement for making a Professional Claims API call, which will contain the header:

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 (3600 seconds).

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

We have a list of test service ID values to use in Sandbox to test varieties of different responses. See the section Sandbox predefined fields and values below.

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 Professional Claims Validation endpoint is as follows:

    https://sandbox.apis.changehealthcare.com/medicalnetwork/professionalclaims/v3/validation

  • The Sandbox Professional Claims Submission endpoint is as follows:

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

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

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

Sandbox predefined fields and values

You can edit fields in the HTTP request body to see how the API works with changes to the data. For Sandbox use, you are limited to a specific set of values. 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: All fields must use a predefined value to have a successful response in the Sandbox.


If you don't use the predefined values in the Sandbox environment, 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": "providers[2]",
            "description": "Please use predefined canned users for non-prod environments: lastName was not predefined."
        }
    ]
}

NOTE: tradingPartnerServiceId 9496 is a test payer and is the only payer allowed for testing in Sandbox.

Using the Professional Claims APIs

What does a typical Professional Claims API request look like?

The Professional Claims APIs use a POST HTTPS call. You provide the claim submission as JSON in the body of the request:

POST /medicalnetwork/professionalclaims/v3/[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": "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": "ABK",
      "diagnosisCode": "S93401A"
    },{
      "diagnosisTypeCode": "ABF",
      "diagnosisCode": "S72044G"
    }],
    "serviceFacilityLocation": {
      "organizationName": "HAPPY DOCTORS GROUP",
      "address": {
        "address1": "000 address1",
        "city": "city2",
        "state": "tn",
        "postalCode": "372030000"
      }
      },
    "serviceLines":[ {
      "serviceDate": "20180514",
      "professionalService": {
        "procedureIdentifier": "HC",
        "lineItemChargeAmount": "25",
        "procedureCode": "E0570",
        "measurementUnit": "UN",
        "serviceUnitCount": "1",
        "compositeDiagnosisCodePointers": {
          "diagnosisCodePointers": ["1","2"]
        }
      }
      },
      {
        "serviceDate": "20180514",
        "professionalService": {
          "procedureIdentifier": "HC",
          "lineItemChargeAmount": "3.75",
          "procedureCode": "A7003",
          "measurementUnit": "UN",
          "serviceUnitCount": "1",
          "compositeDiagnosisCodePointers": {
            "diagnosisCodePointers": ["1" ]
          }
        }
        }
    ]

  }
}

What do Professional Claims Validation API responses look like?

Let's consider a case where there's a typo in the claim's diagnosisTypeCode:

{
    "errors": [
        {
            "field": "claimInformation.validHealthCareCodeInformation",
            "description": "First healthCareCodeInformation.diagnosisTypeCode list item value must equal 'BK' or 'ABK' and subsequent values must equal 'BF' or 'ABF'"
        },
        {
            "field": "claimInformation.healthCareCodeInformation[0].validCodeCategory",
            "description": "Allowed Values are: 'BK' International Classification of Diseases Clinical Modification (ICD-9-CM) Principal Diagnosis, 'ABK' International Classification of Diseases Clinical Modification (ICD-10-CM) Principal Diagnosis, 'BF' International Classification of Diseases Clinical Modification (ICD-9-CM) Diagnosis, 'ABF' International Classification of Diseases Clinical Modification (ICD-10-CM) Diagnosis"
        }
    ]
}

Another case where the diagnosisTypeCode is correct but its associated diagnosisCode is wrong, Here, the API shows the EDI loop where the error can be found and fixed:

{
    "status": "EDITS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201210R999898~2008177834152729",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-12-10T18:23:58.559-06:00",
        "claimType": "PRO",
        "formatVersion": "5010"
    },
    "errors": [
        {
            "field": "01-2",
            "value": "46",
            "code": "BK",
            "description": "When entered, the Diagnosis Code must be valid.\n\n
            Note: The decimal point is not allowed in the diagnosis code.\n\n
            LOOP 2300 HI",
            "location": "2300 HI"
        }
    ]
}

Consider a case where a service line chargeable amount has a typo or an incorrect value:

{
    "status": "EDITS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201210R999898~31433371895808763",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-12-10T18:59:38.596-06:00",
        "claimType": "PRO",
        "formatVersion": "5010"
    },
    "errors": [
        {
            "field": "02",
            "value": "22.75",
            "description": "The Total Claim Charge Amount must balance to the sum of all the Service Line Charge Amounts.\n\nLOOP 2300 CLM02",
            "location": "2300 CLM"
        }
    ]
}

A successful validation of a professional claim gives a response similar to the following:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201210R999898~2014364838718969",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-12-10T20:07:05.4-06:00",
        "claimType": "PRO",
        "formatVersion": "5010"
    }
}

After the API validates the claim, it's ready to submit to the payer unless you want to run further changes and checks on it.

What do Professional Claims Submissions API responses look like?

The Professional Claims Submission JSON response comes from the payer; it indicates that the payer successfully received the submission. This does not indicate whether the claim is approved:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "190405R999898~2046598143285592",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "ABC123-RI",
        "timeOfResponse": "2019-04-05T14:47:36.784-05:00",
        "claimType": "PRO"
    }
  } 
}

NOTE: We recommend using the Validation API before sending the claim request to the payer. Validation rules help prevent claims with incorrect information from being sent to the payer, such as a typo in the NPI, errors in calculations, or poor formatting and syntax in the claim. You can also use the Professional Claims Healthcheck API to check on the operating status of the service endpoint before sending the claim.

A Note on Professional 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.

Understanding API Features

Do you bill for a failed claim due to technical error?

Every transaction that makes it to the clearinghouse is billable. All errors at the API level, and some errors at the ingress of the clearinghouse, are considered non-billable.

A provider has two different teams; one enters the claim and the other verifies and submits it. Before submitting, can they enter the claim, save it and have it released when ready?

Our APIs don't have a cache/drafting feature. Customers can develop and automate this feature. Customers should hold the claims on their end, and programmatically set up a console to separate working on claims from submitting them.

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 hardcopy); Insitutional 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 doesn'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 is the claimReference field in the Submission response?

The claimReference field is an object containing the list of identifiers that you and others can use to track a claim. If questions arise about a claim, you can provide the information listed in the claimReference object to Change Healthcare support for troubleshooting purposes. It appears in all Submission responses for claims, and is shown elsewhere in this FAQ. The list of identifiers may differ depending on the context for the response. Here's an example:

{
    "status": "SUCCESS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "correlationId": "201113R999898~2634061369394033",
        "submitterId": "009998999898",
        "customerClaimNumber": "000000001",
        "patientControlNumber": "12345",
        "timeOfResponse": "2020-11-13T09:30:33.29-06:00",
        "claimType": "PRO",
        "formatVersion": "5010",
        "rhclaimNumber": "2031851503057"
    }
}

The fields in the claimReference object include the following:

  • correlationId: ID used by support to locate a transaction at the clearinghouse.
  • submitterId: The customer's combined biller ID and submitter ID.
  • customerClaimNumber: ID set by the customer in the claim.
  • patientControlNumber: ID set by the customer in the claim for the patient.
  • timeOfResponse: Timestamp for the response.
  • claimType: The type of claim, Professional or Institutional.
  • formatVersion: EDI format version, will always be 5010 for the current version of the 837 claim.
  • rhclaimNumber: Number assigned by the clearinghouse. You use this value to search for the claim in ConnectCenter.

Are there guidelines for predicting the rate of unique claims submitted for a practice?

Rates of unique claims are isolated to each individual provider. Every provider is different. Whenever you render a medical service, file a claim.

How many line items can be on a single claim?

A single professional claim supports up to 50 service line items.

Change Log

API Name API Version Date Introduced Available Until
Professional Claims v3 4/17/19 TBD
Professional Claims v2 4-1-19 Deprecated
Professional Claims v1 1-1-19 Deprecated

Release Notes:

v3 Release

  • Documentation updates and improvements
  • Security and Authorization changes in v3
  • host and url changes
  • Remove the Accept application/vnd.changehealthcare.claimsubmission-v2+json header mentioned in v2, no need to send or increment, Versioning will be managed via the url path.
  • review swagger open api spec more 837 objects have been added

v3 Updates 12/24/20:

  • Added support for Country and Country Subdivision Codes. Required only when the billing address is not in Canada or in the United States of America, including its territories (e.g. American Samoa). Used when the billing address includes a country and an administrative subdivisions of any type such as states, provinces, or canton. These values reside in the EDI N404 and N407 fields in Loop 2010BA.

v2

  • Error response model changes

v1

  • Initial offering of claims submission