Overview

Apex’s claims Partner Integration v4 enables developers to submit claims via Apex and to receive updates on the status of claims after submission. The protocol is completely file-based. A partner uploads claims to the their inbound folder at Amazon AWS S3. Intermediate status of claims is listed in the claim status file, which is periodically published by Apex in the outbound folder. X12 835 remittance advice files are also published to the outbound folder. The Apex payer list is published to the outbound folder from time to time. The partner is required to periodically download and then delete the claim status file, payer list, and remittance advice files. Any file that is not downloaded and deleted (in particular, the claim status file or payer list) will be overwritten the next time it is generated.

The payer list and the claim status file are in CSV (comma-separated values) format. The CSV format is documented here: https://tools.ietf.org/html/rfc4180. In brief, CSV files consist of lines of text separated by carriage-return linefeed pairs (0x13, 0x10). Each line of text is a row. The row consists of columns separated by commas. Any column that contains a comma (,), double-quote ("), carriage-return, or linefeed must be enclosed in double quotes. Within a column enclosed in double quotes, any double quotes are escaped by doubling, e.g., "This column has a ""quoted"" word." The first row is a header row where the values in the columns give the names of the columns in the rest of the file. The remaining rows are data rows. Each row has the same number of columns. When parsing a CSV file, the partner should use the header row to identify the columns and not depend on column positions. New columns may be added or the order of columns may change at any time.

The Root File Interchange Folder

When a partner establishes a relationship with Apex, a root file interchange folder will be established by Apex for the partner in Amazon AWS S3. Apex will give the partner the path to this folder along with credentials to access it. The partner may use The Amazon AWS S3 API to submit and retrieve files. Other options may be offered by Apex – please contact Apex for details.

Under the root file interchange folder will be two subfolders. The partner will write all submitted claim files to the inbound folder and will retrieve all replies from the outbound folder. (The inbound and outbound folders are named with respect to Apex.)

Submitting Claim Files

Claims must be submitted in X12 837 claim format. A claim file may contain one or more claims. If claims are submitted one per file, then the file name may be used as the partner’s claim ID. There may be other ways to identify claims – please contact Apex for details.

Apex will poll the inbound folder periodically. When it detects one or more claim files, it will make internal copies of them for processing and then delete the originals from the inbound folder.

The submitter must provide the Apex-assigned submitter ID in three places in the 837:

• ISA06 of the ISA segment. Also, ISA05 must be set to ZZ (Mutually Defined).
• GS02 of the GS segment.
• NM109 in loop 1000A.

Payer List

The Apex payer list is uploaded once a day by Apex to the outbound folder. This generally happens around midnight Mountain Time. The name of the payer list is payers.csv. The file is in CSV format. The file has a header row with column names Payer Name, Payer ID, Enrollment Required, and Profession.

In a claim, in loop 2010BB, the payer ID must be submitted as NM109. Also, NM109 should be set to PI (Payor Identification). (Payer is spelled "Payor" in the X12 837 document.)

Enrollment Required is set to 1 if the payer requires enrollment; otherwise, the value is 0. Profession is set to 1 for medical payers and 2 for dental payers. When submitting claims to a payer that requires enrollment, the provider must be enrolled with the payer, or else the claim will be rejected. See the Provider Maintenance section below for more information.

Retrieving Status

A status file is generated on a periodic basis, generally every three hours. The status file is named StatusReport.csv and is located in the outbound folder. The file is in CSV format, as described above. The status file contains an entry for each claim that has been submitted to Apex in the last 30 days, except for claims for which each service line has appeared in an X12 835 remittance advice file.

Status is reported on a per-service-line basis. It is possible for some service lines in a claim to appear in an 835 while others are deferred for additional processing. In such a case, the service lines that have appeared in an 835 are removed from the status file, while the rest remain in the status file. Once 30 days have passed since a claim was submitted, it will no longer appear in the status file.

Most partners will use a strategy similar to this to track the status of claims. After submitting claims, the status file will be downloaded and processed from time to time. If the submitted file was rejected for syntax errors, there will be a request entry in the status file for the submitted file, which can be identified by its filename. There will be error messages associated with the rejected file. Otherwise, the claim or claims in the file will be entered into the Apex system and will appear in the status file, identified by both the submitter’s claim ID and Apex’s claim number. Apex’s claim number can be used to find the claim in Apex’s website or when communicating with Apex about the claim. The claim and its associated claim lines will continue to appear in the status file while the claim is sent to the payer and processed by the payer. When the status of a service line changes, the LastUpdatedUtc column will be updated. When a particular service line appears in an 835 generated by the payer, Apex will pass that 835 on to the partner. At this point, the service line will disappear from the status file because the partner will have the full, final status of the service line in the 835. If for some reason (such as the claim being rejected by the payer for syntax errors or the claim being denied by the payer) the service line never appears in an 835, then the service line will be dropped from the status report 30 days after submission to Apex.

Tracking the status of a claim

Initially the partner submits a claim to Apex. The claim should then appear in the status file for a period of time, as discussed above. The claim can be identified by SubmitterClaimId.

If the claim is syntactically incorrect, Apex will not be able to parse the claim completely and will reject the claim. Such claims are identified in the status file as requests (see below) as opposed to claims, since there is no Apex-assigned claim number. A request file can be identified by the value in SubmitterFile. If the claims in the file can be parsed by Apex, then the SubmitterClaimId may also be present. Otherwise, the errors associated with the request apply to the entire file.

If the claim is syntactically correct, then the claim will be assigned a value for ClaimNumber. This is the number by which the claim will be identified in Apex’s web site.

The status of the service lines will be updated when the claim is sent to the payer, and then again if there are any status updates from the payer. For example, the payer may report that the services lines in the claim have been accepted into the adjudication system. The payer may also reject the claim and its service lines. In the latter case, the service lines will not appear in an 835 because the service lines have reached a final status.

When a service line appears in an 835, the service line and associated messages will disappear from the status file. The final status of the service line may be determined from the 835 itself.

Messages (typically error messages) may be associated with a request, a claim, or a service line within a claim. The details of how this is done are described in more detail below. For example, if a request is rejected for syntax errors, the request will appear in the status file, and there will typically be one or more error messages that identify the syntax errors associated with the request. If there are claim-level errors, they will appear in the status file associated with the claim. Similarly, if there are service-line-level errors, they will appear in the status file associated with the service line.

The column LastUpdatedUtc is updated each time the status of a service line changes. The date and time are UTC and in ISO 8601 format.

Status file format

This section describes the status file format. A file with this information is also included in the outbound folder under the name readme.txt.

There is a header row that names the columns in the file. The order of the columns may change from time to time. New columns may be added in the future. Automated processing should identify columns by the column names in the header row rather than by position.

The meanings of the columns are defined below.

• Level. This column defines the role of the row. The values of this column are as follows.
  • 0. Comment. Rows at this level should be ignored when parsing the file.
  • 1. Claim. This row identifies a claim that has been accepted by Apex for processing.
  • 2. Claim message. This row contains a message associated with a claim. Typically it will contain an error message. There may be zero or more message rows associated with a single claim. The claim messages are tied to the parent claim by the value in the ClaimNumber column.
  • 3. Service line. This row contains a service line associated with a claim. The service lines are tied to the parent claim by the value in the ClaimNumber column.
  • 4. Service line message. This row contains a message (typically an error message) associated with a service line. There may be zero or more service line message rows associated with a single service line. The service line messages are tied to the parent service line by the value in the ServiceLineId column.
  • 5. Request. A "request" is a claim that was submitted to Apex, but which was rejected because of syntax errors. A "request" does not have an Apex claim number or claim ID, but it will have a value for SubmitterFile. It may have a value for SubmitterClaimId if that can be determined.
  • 6. Request message. This row contains a message associated with a request. Typically it will contain an error message describing one of the syntax errors that caused the claim to be rejected by Apex.
• SubmitterClaimId. The submitter's claim ID, if it can be determined.
• SubmitterFile. The file that was submitted to Apex.
• ClaimNumber. The main Apex identifier for the claim.
• ClaimId. Another Apex ID associated with the claim.
• CreateDateUtc. The date and time UTC that the claim or request was received by Apex. The date is in ISO 8601 format.
• Message. A message, typically an error message.
• RequestId. Apex's internal ID for the claim request. A claim with a RequestId instead of a ClaimNumber was rejected by Apex because of syntax errors.
• LineItemControlNumber. The submitter's line item control number. If the submitter did not submit a line item control number, an Apex line item control number may appear here.
• ServiceLineId. Apex's ID for the service line.
• LastUpdatedUtc. The date and time UTC that the status of the service line was most recently updated, in ISO 8601 format.
• ProcedureCodeBilled. The procedure code that was submitted to Apex. Note that the payer may pay based on a different procedure code, or may split the service line into multiple service lines with different procedure codes.
• StatusInt. The status of the service line, in integer form. Automated processing should use this version of the status. The possible values for StatusInt are:
  • Apex statuses
    • Unknown = -1
    • Unvalidated = 0
    • Ready = 1
    • Done = 2
    • Failed = 3
    • Pending = 4
    • DuplicateClaim = 6
    • DoNotProcess = 7
    • NewDocClaim = 8
    • PendingAttachment = 9
    • OutputException = 10
    • Test = 11
  • Payer statuses
    • Unknown = 100
    • Submitted = 101
    • Accepted = 102
    • Rejected = 103
    • Pending = 104
    • Adjudicated = 105
    • Paid = 106
    • Complete = 107
    • Denied = 108
    • Reversed = 109
    • Corrected = 110
    • Finalized = 111
    • FinalizedPayment = 112
    • FinalizedDenied = 113
    • FinalizedRevised = 114
    • Unresolved = 115
  • StatusText. The status of the service line in textual form. Automated processing should ignore this version of the status. It may change without warning at any time.
  • Key. Present only in rows with a Level value of 0. Automated processing should ignore this column (and indeed the entire row) at this time.
  • Value. Present only in rows with a Level value of 0. Automated processing should ignore this column (and indeed the entire row) at this time.

  Retrieving Remittance Advice Files

  X12 835 remittance advice files are placed in the outbound folder associated with the partner. The partner should download and then delete these files.

  Provider Maintenance

  There are two options for maintaining providers in the Apex system: manual provider maintenance, and automated provider maintenance. With manual provider maintenance, provider information must be submitted to Apex before claims are sent for a provider. In this scenario, an individual medical or dental practice creates an account with Apex, communicates directly with Apex, and submits information for each provider in the practice to Apex before submitting claims for that provider.

  With automated provider maintenance, all provider information is submitted as part of the claim, so there is no need for the provider record to be created within the Apex system before submitting claims for the provider. This option may be appropriate for a vendor of cloud-based practice management software, where the vendor submits claims for multiple medical or dental practices directly to Apex on behalf of the practices.

  If the partner chooses manual provider maintenance, then any claim directed to a payer which requires enrollment and for a provider that has not been enrolled will be rejected by Apex. If automated provider maintenance is selected, then such claims will not be rejected by Apex and will be sent to the payer in the normal manner, even though the claim will most likely be rejected. In this case it is the responsibility of the submitter (typically a vendor of practice management software) to ensure that the provider is enrolled with the payer before submitting claims.

  SFTP Support

  The Partner Integration v4 was originally designed to use Amazon Web Services Simple Storage Service (AWS S3) for file interchange. Apex has now added support for SFTP as the preferred method of file interchange.

  To use SFTP for file interchange, Integration v4 Partners can go to the Api Credentials tab of the Manage Account page of the website. Click the Generate Key button to generate a set of credentials. Be sure to save the password since it will not be available again after navigating away from this tab.

  Up to two sets of credentials may be in use at one time. This is to allow a new set of credentials to be generated and deployed while the original set continues to work. Once the original set of credentials has been removed from service, it may be deleted by using the Revoke button, or Partner Support can be contacted to revoke these credentials

  To interchange files with Apex via SFTP, use the username and password generated as described above to connect to sftp.apexedi.com via SFTP. You will be placed in the root file interchange folder as described in the Overview and Root File Interchange Folder above. This can be done with a third party SFTP app of the user’s choosing, or it can be done from a Windows command prompt, entering the command as follows:

  C:\>sftp @sftp.apexedi.com

  A password prompt will appear at which point the password received from Apex should be entered.

  If successful, you will receive a “Connected” message with an sftp> prompt. From here type:

  sftp> ls

  Two folders will be shown:

  inbound  outbound

  The inbound folder is where claims are submitted, the outbound folder is where payer responses and claim status updates will appear. Files can be transferred into the inbound folder with the following commands:

  cd outbound
  get statusreport.csv

  Additional SFTP shell commands can be found online

  Testing

  Apex EDI maintains a sandbox environment for clients that use the new file-based protocol, also known as Partner Integration v4. The sandbox environment has a simulated payer system that will generate automated responses. Claims must be routed to the simulated payer — any other claims will be ignored.

  In order for claims to be processed automatically, the following must occur:

  • The payer ID must be set in the NM1 segment in loop 2010BB of the 837. NM108 must be PI (Payor identification). NM109 must be TST01.
  • The subscriber ID defines the behavior of the simulated payer. The subscriber ID must be set in the NM1 segment of loop 2010BA (Subscriber). NM108 must be MI (Member Identification Number). NM109 should be set as described below.
  • In order for generated 835 files to appear in the outbound folder, the client’s numeric account ID must appear as NM105 (Middle Name) of the NM1 segment of loop 2010BA (Subscriber), the same segment in which the modified subscriber ID appears. If a patient segment is used (loop 2010CA), then the client's numeric account ID can be used in the same NM105 of the NM1 segment for the patient. If neither of these steps are taken, 835 files generated by the simulated payer will be processed by the system and claim status will be updated in the status file, but the 835 will not appear in the outbound folder.

  The default behavior of the simulated payer is to return a 277 acknowledging the receipt of the claim or claims. A short time later an 835 is generated in which all claims appear and all of the service lines are paid. 80% of the submitted amount for each service line is paid, and the other 20% is identified as patient responsibility. Note that the partner will receive any generated 835. Any generated 999 or 277 documents are processed by the system and the status of the affected claims is updated in the status report file, but the partner will not receive the files themselves.

  The following alternative behaviors are invoked by setting the subscriber ID to the indicated numeric value.

  • 2001. The receipt of the claim is acknowledged in the 277, but the claim does not appear in an 835. (Suppress835)
  • 2002. The claim is rejected in the 277. The claim will not appear in an 835. (Rejection277)
  • 2003. Not used.
  • 2004. The claim is rejected in the 277. The first service line in the claim is mentioned in loop 2220D of the 277 where a reason for the rejection is given. (ServiceLineRejection277)
  • 2005. The claim is rejected in a 999. The error is reported to be a syntax error. (This error is generated even if no actual syntax error was present in the claim.) (Rejection999)
  • 2006. Multiple STC segments are generated for the claim in the 277. (MultipleStcsIn277)
  • 2007. A claim with this subscriber ID should have multiple service lines. The claim is split. The first service line is denied in the 835. The other service lines are omitted as if they would appear in a subsequent 835, but no subsequent 835 is generated. (SplitEobDenyFirstServiceLine)
  • 2008. A claim with this subscriber ID should have multiple service lines. The claim is split. The first service line is omitted from the 835, as if it had appeared in a previous 835 (although no previous 835 is actually generated). The other service lines are paid. (SplitEobPaySubsequentServiceLines)