Introduction

Apex’s Claims API enables developers to submit claims via Apex and to receive updates on the status of claims after submission.

The Apex Claims API v3 is HTTP-based. All API calls require the POST method. Some information is passed in HTTP headers, while other information is sent as query parameters in the URL. Claim data in SubmitClaims and the list of payer response document IDs in GetPayerResponseDocuments are passed in the body of the POST request in JSON (http://www.json.org/) format. Returned information is supplied in JSON format in the body of the HTTP response.

The process of submitting claims and obtaining the status of the claims consists of four steps:

Acquire a list of supported payers by calling GetPayers. Each claim must contain the payer ID of a supported payer. (It is not necessary to call GetPayers before each call to SubmitClaims.)
Submit one or more claims by calling SubmitClaims.
Request a list of claims for which payer responses have been received within the requested date range. This returns the document IDs of the response documents. These document IDs may be passed to GetClaimStatusByDate in order to receive the actual payer responses.
Request one or more payer-generated claim status and remittance advice documents by calling GetPayerResponseDocuments and supplying the document IDs of the desired documents.

Once a claim has been submitted, the payer will typically return a claim status document (X12 277) and, if the claim was not rejected, a remittance advice document (X12 835). There are typically delays of one or a few days after claims are submitted before responses are received. GetClaimStatusByDate is used to identify the claims for which one or more response have been received from payers within the specified date range. The related document ID returned from calls to GetClaimStatusByDate can then be passed in to GetPayerResponseDocuments in order to receive the responses themselves.

In general, Apex transforms claims into X12 837P format (for medical claims) or X12 837D format (for dental claims) for transmission to payers. Knowledge of these specifications by developers submitting claims via the Apex Claims API 3.0 is not required; however, some developers may find it useful, particularly if submitting very complex claims. The specifications may be obtained for a fee from the Washington Publishing Company (http://www.wpc-edi.com). There are occasional references to these and other related EDI document formats throughout the Apex documentation for the benefit of those who are familiar with the specifications.

The Apex Claims API v3 consists of four calls: GetPayers, SubmitClaims, GetClaimStatusByDate, GetClaimStatusWithHistoryByDate GetClaimStatusWithHistoryByClaims and GetPayerResponseDocuments. The use of these calls is explained below. The calls are documented in more detail in the document Claim API Reference. There is also a document describing Authentication and Privacy.

GetPayers

GetPayers is used to retrieve the list of payers supported by Apex. The payer type, medical or dental must be specified. The return value is a list of payer objects. The ApexPayerId value for the desired payer when submitting a claim. Developers save the results of this call and present the payer list to clients to allow them to select the desired payer for a claim.

The list of payers does change from time to time, but the changes are not frequent, and they do not typically involve the most frequently-used payers. Consider updating your copy of the list periodically, for example, once a week. It is certainly not necessary or desirable to call GetPayers every time that a payer list must be presented to a client.

SubmitClaims

Claims are submitted via the SubmitClaims call. One or more claims may be submitted per call.

Each submitted claim is a JSON object with multiple fields. There are many possible fields, as documented in the Claim Field Reference. Certain fields are required, as listed below, and also as identified in the table, but most fields are optional.

A claim consists of general information that applies to the entire claim, plus one or more services lines which represent individual services identified by procedure codes. The claim as a whole is submitted as a JSON object whose fields contain the information that applies to the entire claim. The services lines are represented by JSON objects, each one of which contains fields that apply to the service line. The table has a column, Level, which identifies for each field whether it belongs to the claim-level object or to one of the service-line-level objects.

For details on the contents of the claim, please see the page Claim API Reference.

In the table, each row is for one of the fields, while each column contains information about the fields. The columns are as follows:

Level. Identifies whether the field should appear at the claim level or the line level.
The next five columns form a cross-reference to the printed CMS 1500 form and to the X12 837P specification.
- Item Number. The number of the corresponding block in the printed CMS 1500 form. If the item number is X12, then the field is supported in the X12 837P specification, but does not appear on the printed form. The corresponding JSON field names are given in the column Name of JSON Field. Each field name either begins with F or X12. Fields whose names start with F appear on the standard CMS 1500 claim form, dated February 2012. The number after the F is the number of the corresponding block in the printed claim form, e.g. F11_InsuredsPolicyGroupOrFecaNumber appears in block 2 of the printed form with the title Insured’s Policy Group or FECA Number. X12_DelayReasonCode is a field that is supported in the X12 837P specification, but does not appear on the printed form.
- Title. The name given to the corresponding block on the printed CMS 1500 form, or an identifying name if the field does not appear on the printed form.
- Loop ID. The name of the loop in the X12 document where the value in the field appears.
- Segment/Data Element. The name of the segment where the value appears in the X12 document. In some cases the name of the data element within the segment is also given.
- Notes. Additional information relating to the field as it appears in the X12 837P document.
General notes. General information about the field.
Name of JSON Field. The name of the corresponding JSON field. This is the name that should be used in building the JSON document for the claim.
Data Type. The type of the field. When the type is enumeration, then the value in the JSON document must be a string selected from a list of pre-defined values.
Min Value or Length. When present, the minimum valid value (for numeric fields), the minimum valid length (for string fields) or the minimum valid number of items (for array fields).
Max Value or Length. When present, the maximum valid value (for numeric fields), the maximum valid length (for string fields) or the maximum valid number of items (for array fields).

The fields whose names start with X12 are fields that are supported by the X12 837P specification, but which do not appear on the printed CMS 1500 claim form. These fields are used much less frequently than those that appear on the printed form. If you are dealing with a unique case that is not addressed in our documentation, please contact us and we will work with you to address it.

There are segments in the X12 837P specification where there are two related values: one contains a value, and another contains a qualifier that indicates the role of that value. Apex has simplified many of these value pairs by providing a dedicated field for each role. For example, in the X12 837P specification, CTP04 contains a qualifier that identifies the role of the value in CTP05. In the Apex JSON claim object, at most one of the fields X12_DrugQuantityInternationalUnits, X12_DrugQuantityGrams, X12_DrugQuantityMilligrams, X12_DrugQuantityMilliliters, and X12_DrugQuantityUnits may be set. The identity of the field which is set determines the qualifier value output by Apex to CTP04. Either F25_FederalTaxIdEin or F25_FederalTaxIdSsn must be set.

Required fields

Apex_PayerId – this is the payer ID of the desired payer from the payer list returned by the GetPayers call
Apex_VendorClaimId – a unique ID assigned to the claim to allow matching to payer responses
F00_PayerName
F01A_InsuredId
F02_PatientNameLast
F02_PatientNameFirst
F03_PatientDob
F03_PatientSex
F04_InsuredNameFirst
F04_InsuredNameLast
F05_PatientCity
F05_PatientState
F05_PatientZip
F06_PatientRelationshipToInsured
F07_InsuredAddress1
F07_InsuredCity
F07_InsuredState
F07_InsuredZip
F11A_InsuredDob
F11A_InsuredSex
F12_PatientAuthorization
F13_InsuredAuthorization
F21_DiagnosisCodes
F24_ClaimLines (an array which must contain at least one claim line)
F24A_DateOfServiceFrom
F24B_PlaceOfServiceCode
F24D_HcpcsProcedureCode
F24E_DiagnosisPointers
F24F_Charges
X12_ProviderControlNumber (Not required but strongly recommended. This value comes back in the remittance advice object in field LineItemControlNumber, which allows payments to be tied back to claim lines.)
F31_PhysicianOrSupplierSignatureIsOnFile
F33_BillingProviderNameLast
F33_BillingProviderAddress1
F33_BillingProviderCity
F33_BillingProviderState
F33A_BillingProviderNpi
F33B_BillingProviderEmployersIdentificationNumber or F33B_BillingProviderSsn

Return Value

SubmitClaims returns a list of objects with the following fields:

ApexClaimId
VendorClaimId
Errors – a list of objects as described below
Status – one of Success, Duplicate, or FailedValidation

Errors contains objects with the following fields:

Id
LineNumber – the number of the service line on which the error occurred, if applicable, else null.
Description

GetClaimStatusByDate

This call returns claim status for the set of claims for which the most recent status change occurred during the specified range of dates. All dates are interpreted as United States Mountain Time, and Daylight Saving Time is observed. Both startDate and endDate are required

This call returns only a summary object of the most recent status change for a particular claim. Included in this claim status summary object is the RelatedDocumentID of the most recent response received from the payer during the specified time period.

If no claims are found within the specified date range, an empty list is returned.

VendorClaimId is a unique ID that is required for submitted claims. Software developers may use the vendor claim ID to match submitted claims to responses received. The RelatedDocumentId identifies a particular response document from a payer.

Note that there may be multiple objects returned for the same claim, with one RelatedDocumentId. Thus there may be multiple claim status objects and/or multiple remittance advice objects for the same claim returned by GetPayerResponseDocuments. There might be multiple remittance advice documents if, for example, there is a remittance advice with payment information and another remittance advice with adjustment information, or if the payer split remittance into two different payments.

GetClaimStatusByDate returns a list of claim status objects with the following fields:

VendorId
VendorSiteId
ClaimNumber
CurrentState
StateChangeDate
PayerAction
PayerActionDate
PayerControlNumber
CreateDate
LastUpdateDate
RelatedDocumentType
RelatedDocumentId
TotalClaimAmount
PayerAmount
Adjustments
PatientAmount
PayerName
PaymentMethod
PaymentReferenceNumber
PaymentEffectiveDate
VendorClaimId

GetClaimStatusWithHistoryByDate, GetClaimStatusWithHistoryByClaims

These calls return claim status and all claim status histories for the set of claims for which the most recent status change occurred during the specified range of dates. All dates are interpreted as United States Mountain Time, and Daylight Saving Time is observed. Both startDate and endDate are required parameters

Summary objects are returned for the most recent status change for a particular claim, together with the array of Claim Histories showing all statuses of the claim including all payer responses in the order received from the payer by Apex. Included in the claim status summary object is the RelatedDocumentID of the most recent response received from the payer during the specified time period. For each Claim History object representing a payer response there will also be a RelatedDocumentId for the response document.

VendorClaimId is a unique ID that is required for submitted claims. Software developers may use the VendorClaimId to match submitted claims to responses received. The RelatedDocumentId identifies a particular response document from a payer.

If no claim status updates are found within the specified date range, with matching VendorId and VendorSiteId, an empty list is returned.

GetClaimStatusWithHistoryByDate returns a list of claim status objects with the following fields:

ClaimNumber
VendorId
VendorSiteId
VendorClaimId
CurrentState
StateChangeDate
PayerAction
PayerActionDate
PayerControlNumber
CreateDate
LastUpdateDate
SubmittedDate
RelatedDocumentType
RelatedDocumentId
RelatedDocumentVersion
TotalClaimAmount
PayerAmount
Adjustments
PatientAmount
PayerName
PaymentMethod
PaymentReferenceNumber
PaymentEffectiveDate
ServiceDate
DisiplayDate
ActorType
ActorText
ClearingHouseStatus
PayerStatus
StatusText
PayerStatusList (array of strings)
PatientLastName
PatientFirstName
PatientMiddleName
PatientSuffix
ProviderLastName
ProviderFirstName
ProviderMiddleName
OrganizationName
SubClaims (array of Claim Status objects)
HistoryEntries (array of Claim History object)
HasOtherSubscriber
LastProcessDate

Each object in the array of Claim History objects, HistoryEntries, contain the following fields:

HistoryType
ClaimHistoryId
OtherClaimHistoryId
EntryDate
EntryType
RelatedDocumentType
RelatedDocumentId
RelatedDocumentVersion
Documentation
OriginalValue
NewValue
ActorType
ActorText
ClearingHouseStatus
PayerStatus
StatusText
Action
PayerAction
NewState
HistoryDetailStrings (array of strings)
PaymentReferenceNumber
PayerControlNumber
ServiceChargeAmount
ServiceLines

GetPayerResponseDocuments

This call returns payer responses for a set of document IDs. The returned object contains two lists, one for remittance advices and one for claim statuses. If no responses are found, an empty list is returned.

This method only returns the current status of claims, not a history of status changes.

GetClaimStatusByDate must be called to obtain the document IDs needed by GetPayerResponseDocuments. GetClaimStatusByDate returns an array of objects, one for each claim with a status change within the specified date range. Among the properties of these returned objects are RelatedDocumentType, RelatedDocumentId, and ClaimNumber. If the value of RelatedDocumentType is ClaimStatus or RemittanceAdvice then RelatedDocumentId should be a non-empty string. This string is the document ID to be passed into GetPayerResponseDocuments to get the payer response for the claim identified by ClaimNumber.

A RelatedDocumentType of ClaimStatus corresponds to a response of type 277 – Health Care Claim Acknowledgment. If the value of RelatedDocumentType is of this type, the corresponding object returned by GetPayerResponseDocuments should be in the claim status array.

A RelatedDocumentType of RemittanceAdvice corresponds to a response of type 835 – Health Care Claim Payment/Advice. If the value of RelatedDocumentType is of this type, then the type of corresponding object returned by GetPayerResponseDocuments should be in the remittance advice array.