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.

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 Onboarding

See the Security and Authorization section in this portal to learn more about securely 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 use your own development console.

Try our Postman Collection! Run in Postman

Links to Professional Claims FAQ Topics

You'll find the following topics on this page:

Do you have a sandbox that I can test before signing a contract?

What information needs to go in the API Request header?

What are the endpoints for getting authorization tokens?

What are the Professional Claims Validation and Submission endpoints?

What does a typical API call look like?

How do Raw-X12 Requests and Responses work?

What does a typical API response look like?

What are some typical Errors and Error codes?

Sandbox predefined fields and values

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.

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.

What are the endpoints for getting authorization tokens?

The Sandbox endpoint URL for authorization tokens is as follows:

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

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 are the Professional Claims Validation and Submission endpoints?

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.

Use the validation endpoint to check your request:

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

Your transaction will not be sent to the payer.

The submission endpoint submits your transaction to the payer:

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

Both use the same request model.

What does a typical API call look like?

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

Example JSON 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": "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" ]
          }
        }
        }
    ]

  }
}

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?

Example JSON Response

{
    "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 first using the Validation API before sending the claim request to the payer. You can also use the Professional Claims Healthcheck API to check on the operating status of the service endpoint before sending the claim.

How do Raw-X12 Requests and Responses work?

We also support a traditional X12 EDI API if you choose to implement the 837P transaction set in its native EDI format.

The Eligibility Raw-X12 endpoints are as follows:

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

https://apis.changehealthcare.com/medicalnetwork/professionalclaims/v3/submission/raw-x12

You can validate a Professional Claim X12 EDI request before you send it to the payer.

An X12 EDI Professional Claims submission request appears similar to the following:

POST /medicalnetwork/professionalclaims/v3/raw-x12 HTTP/1.1
Host: sandbox.apis.changehealthcare.com
Authorization: Bearer <Your-Access-Token>
Content-Type: application/json
{
  "x12": "ISA*00*          *01*CYCTRANS  *ZZ*009998999898   *ZZ*CLAIMSCH       *200714*1925*|*00501*000000001*0*T*:~GS*HC*418581RTEXGEAR*1465*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~"
}

Because the X12 837P standard does not define an EDI-formatted response, your response from a Professional Claims X12 API call will be in JSON format.

What are some typical Errors and Error codes?

{
    "status": "ERRORS",
    "controlNumber": "000000001",
    "tradingPartnerServiceId": "9496",
    "claimReference": {
        "timeOfResponse": "2019-04-08T16:06:37.454-05:00"
    },
    "errors": [
        {
            "code": "7000",
            "description": "An internal error was encountered while processing the Claim. Support has been notified of the issue. Please try again later."
        }
    ]
}

Where can I find more information about error codes?

You can find further information on API error codes here.

Note: We recommend routinely using the Professional Claims Validation API to check your submissions before sending them. Validation rules help prevent claims with incorrect information from being sent to the payer. This gives you a chance to correct the claim, avoid delays, and increase acceptance of claim requests by the payer.

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.

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: A field can appear at any level of the request model, but it must have ta predefined value from the list above to receive 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 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": "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
Professional Claims v3 4/17/19 TBD
Professional Claims v2 4-1-19 Deprecated
Professional Claims v1 1-1-19 Deprecated

Release Notes:

v3

  • 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

v2

  • Error response model changes

v1

  • Initial offering of claims submission