Apex EDI Vendor Portal

Apex EDI API V3 Documentation

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:

  1. 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.)
  2. Submit one or more claims by calling SubmitClaims.
  3. 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.
  4. 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 837D 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, 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. Another example is that at most one of F25_FederalTaxIdEin and F25_FederalTaxIdSsn should 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_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 absolutely required, but highly 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. The claims selected are those whose initial submission date fall within the specified range. All dates are interpreted as United States Mountain Time, and Daylight Saving Time is observed. Omitting endDate indicates that the current date (Mountain Time) should be used.

This call does not return all status changes for a particular claim, but rather the IDs of responses received from payers 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. RelatedDocumentId identifies a particular response document from a payer.

Note that there may be multiple objects returned for the same claim, and thus multiple values of RelatedDocumentId for the same document. 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.

GetClaimStatusByDate returns a list of 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

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