API Quickstart Guide

Basic API Workflow

Please review the API Technical Documentation for guidance on configuring the Claim.MD API.

Workflow Considerations

• Consult with someone in your company who handles billing to better understand the normal workflow for submitting claims, receiving ERA and checking patient eligibility.

• Familiarize yourself with the typical process of receiving both a claim status update from the payer and payment details as part of a payer EOB/Remittance. Understanding this workflow can enhance your integration and utilization of the provided services.

• The ‘Accept’ HTTP header controls if API results are returned in the XML (application/xml) or JSON (application/JSON) formats.

You must determine if your users will have their own Claim.MD accounts with direct access to the portal, or if the software vendor will retain a single Claim.MD account and offer no Provider access.

Provider Direct Access - Minimum Requirements

If each provider/customer will have their own Claim.MD account, you will need to store a separate API key, last_responseid and last_eraid for each customer. The API key will control which account data is submitted to, and received from.

Enrollment

Each provider/customer will have direct access to the Claim.MD portal to complete necessary enrollments on initial setup of their account.

Support

Each provider/customer may directly contact Claim.MD and use the support ticketing system for an EDI related support and for questions on using the portal.

No Provider Access - Minimum Requirements

To use a single account with Claim.MD and provide no direct access to your providers, a minimum set of functionality will be required via the API. If using this model, only the software vendors staff may have credentials into the Claim.MD portal.

Your software will need to present claim rejections and denials to your users, and give a way to resubmit claims with errors. The software must at a minimum support Uploading Files, receiving Claim Status and Receive ERA.

Enrollment

Note the above services may require enrollment by each provider before they can be used. Either your staff will need to manually send each enrollment form & instructions to your providers or you will need to implement the /enroll/ API services to present the required steps and forms directly to them.

Support

Only the staff of the software vendor will have access to support through a single vendor account type. Providers may not contact Claim.MD directly for

Retrieve API Credentials:

• Obtain the API key. These credentials are necessary for authenticating your requests.

Upload Files

The /upload/ endpoint can be used to upload these types of files:

• Batch claim files (Supported Formats)

• Individual claims (Supported Formats)

• Electronic attachments (PDF / X12 275)

• External 835 ERA (X12 835)

• Batch eligibility (note: Realtime Eligibility is the recommended method)

Claim.MD Acknowledgment or Rejection

When claim files are submitted using the /upload/ endpoint you will receive an acknowledgement or rejection from Claim.MD validating receipt of every claim.

Transmitting Claims Immediately Without Approval

Claims can be configured to transmit immediately without the need for approval by navigating to Settings -> Account Settings -> Transmit Approval. Simply un-select the Transmit Approval checkbox.

Claim Status

As claims are processed by the Payers and their 3rd party trading partners, further claim status messages will return. Use the /response/ endpoint to periodically poll for these updates. You will accumulate these status messages in your own database, and take action as appropriate.

To continually download the most current status updates for ALL claims submitted, store the last_responseid and include it in subsequent API requests as ResponseID.

The test accounts in Claim.MD are designed to simulate the claims process by generating rejections or denials based on the value of the insured ID or policy number entered. This feature allows users to test and validate their claim submissions without affecting real patient data or financial transactions.

Electronic Remittance Advice (ERA)

The /eralist/ endpoint will return a list of checks, EFT’s or non-paying remittance. Periodically call the /era/ service to obtain a list of payments/No-Pay details sent by the payer. To continually download the most current ERA, store the last_eraid and include it in subsequent API requests as ERAID.

Use the ‘eraid’ for each ERA to download the full details including claim data, payments and adjustments. The ERA details can be downloaded in any of these formats:

• /era835/

  Download the remittance in the standard 835 data format.

• /erapdf/

  Download the remittance in a human-readable PDF report format.

• /eradata/

  Download the remittance in the XML or JSON format (Controlled via the HTTP ‘accept’ header)

Note: Test Accounts

Test accounts support two special methods for creating rejections or denials:

• Send a policy number of "REJECT" to force a rejection on an otherwise valid claim.

• Send a policy number of "DENY" to force a denial to return on the claim ERA.

Auto Posting Payment or Denial Data

Payers return one ERA to coincide with each check or EFT sent to the provider. The ERA contains details on which claims are being paid, or adjusted. Our portal attempts to match the ERA to a claim in our system, but the API does not do this. It is up to your software to complete this task.

ERA are not matched to a specific Claim.MD claim ID. You will need to build logic that uses the below values from the ERA data to match claims in your system:

- Remote Charge ID # (remote_chgid / REF*6R)

- PCN (pcn / Loop 2300 CLM01)

- Policy # (ins_number / Loop)

- Date of Service (from_date)

- Procedure and modifiers. (proc_code, mod1, mod2...)

Keep in mind that payments should normally be associated at the charge level, not the claim level. A payer can un-bundle claims and return remits for each charge line separately. If you send a unique charge identifier (REF*6R / remote_chgid), most payers will return this value on the ERA.

Claim History

To recreate claim history within your own system, you can aggregate data from several API services provided by the system:

1. Claim Status Updates: Use the /response// API to periodically request updates on claims you've submitted. Store the last_responseid to ensure you only receive new updates.

2. Payment Information (ERA): To download payment details, first use the /eralist/ API to get a list of new payment files returned by the payer. Then, use either the /eradata/ or /era835/ API to download the detailed payment information. Match these details with the original claim for accurate payment posting.

3. Also consider including data from /modify/ and /notes/ if your users will have direct access to the Claim.MD portal.

By storing the data from these API calls in your database, you can build and display the complete claim history.

Note

Note that there is no single API call for the entire claim history; it requires combining data from multiple sources.

For detailed explanations on API usage, refer to the following URL:

https://api.claim.md

Check Benefits/Eligibility

The /eligdata/ endpoint will query the payers eligibility database in real time. This endpoint accepts the patient/insured information as parameters and returns the payers eligibility results in XML or JSON formats.

Important Facts:

• Provider information (prov_name_l,prov_taxid, etc.) is only optional if you have pre-loaded the provider into Prov. Enrollment screen.

• Real provider NPI and information can be used, or the dummy NPI “1111111112” can be used.

• The test system returns one sample eligibility response regardless of the data sent. Once done testing your ability to communicate with this API you will need to move to production to see the full array of possible payer responses.

• Payers normally respond in under 20 seconds. Claim.MD will return a timeout error if the payer takes longer than 90 seconds.

Resubmitting Claims with Corrections

Effectively managing claim resubmissions involves resending the entire claim with the desired changes. The process may vary based on whether a claim was paid incorrectly or rejected.

Updating the claim record within Claim.MD

When resubmitting a claim, specific values in the claim data will control whether Claim.MD updates an existing claim record within our system or creates a new one. By default Claim.MD will update an existing claim record if these values match on the newly uploaded claim record:

• Patient Acct # (pcn / Loop 2300, CLM01)

• Rendering Provider (prov_npi / Loop 2310B, NM109)

• Legacy Provider ID (prov_id / Loop 2310B, REF*G2)

• Procedure Codes (proc_code_n / Loop 2400, SV10102)

• Charge Amounts (charge_n / Loop 2400, SV102)

• Service Dates (proc_code_n / Loop 2400, DTP03 Qual “472”)

• Payer Order (payer_order / Loop 2000B, SBR01)

Recommended
If your software is able to send a unique claim identifier and retain that value between each submission, contact support to request your claim update field be set to “remote_claimid”. This value must be sent in your claim file in either the “remote_claimid” field or Loop 2300, REF02 with “D9” qualifier.

Note: When the automatic corrected claims setting is active in Claim.MD, updating an existing claim record will cause Claim.MD to look for a payer ICN previously returned on an ERA or claim status. If one can be found, Claim.MD will automatically add frequency code 7 and the payers previous claim # to the claim, allowing for easier corrected claim submissions.

Correcting a claim record at the payer

To correct a claim previously processed by the payer you must have the payers ICN, this is the unique value assigned to the claim by the payer most, often returned on the EOB or Electronic Remittance Advice.

Identify to the payer the claim that should be corrected by sending a frequency code of “7” (frequency_code / Loop 2300 CLM0503) and the payers ICN (Loop 2300 / REF02 with “F8” qualifier).

Voiding a claim record at the payer

To void a claim previously processed by the payer you must have the payers ICN, this is the unique value assigned to the claim by the payer, most often returned on the EOB or Electronic Remittance Advice.

Identify to the payer the claim that should be voided by sending a frequency code of “8” (frequency_code / Loop 2300 CLM0503) and the payers ICN (Loop 2300 / REF02 with “F8” qualifier).

Supported Claim Formats

ANSI X12 (837)

Supported ANSI X12 file formats:

• 837P = Professional Claims

• 837I = Institutional Claims

• 837D = Dental Claims

Single Line Claim File (XLS/CSV)

Spreadsheet claim format, with all claim data and procedures on a single row. Format is CSV (Comma Separated Values) or XLS (Office Excel 97)

• Supported Column Definitions

• Professional Claims CSV Example

• Professional Claims XLS Example

Multi-line Claim File (XLSX)

Spreadsheet claim format, with a separate row per procedure. Format is XLSX (Excel 2007)

• Supported Column Definitions

• Professional Claims XLSX Example

XML Claim File (XML)

XML claim format

• Supported Field Definitions

• Professional Claims XML Example

• Institutional Claims XML Example

JSON Claim File (JSON)

JSON claim format

• Supported Field Definitions

• Professional Claims JSON Example

Batch Eligibility (CSV)

Spreadsheet batch eligibility file. Results must be viewed individually.

• Supported Column Definitions

• Batch Eligibility CSV Example

NSF

Legacy National Standard Format

Print Image

Legacy “Print Image” format. This is a plain text file format with the fields located roughly in the same location as the paper claim form. All values must be at a fixed location in the text file and have and equal number of lines for each claim record.

API Request and Response Samples

In the API documentation page, navigate to the test window to the right of the "Upload Batch Files" section. Here, you can choose the programming language for which you'd like to view a sample. For instance, the current selection is the "Node.JS" tab. The provided request sample serves as an illustrative example of how the programming could be structured. It is at the discretion of your programming team to determine how these requests should be implemented to align with your specific specifications.

Additionally, there are sample responses available that mirror the responses from Claim.MD, presented in X12, XML, and JSON formats.

Each of the sixteen sections includes sample programming and responses. These resources are provided to assist you in ensuring that your system accurately retrieves the necessary information from Claim.MD .

Request Body Schema

Take note of the Request Body Schema situated in the middle of the page. It explicitly highlights the crucial data required (indicated in red) for the request to operate correctly.

View Response Structure

Underneath the request schema, you'll find a green-shaded box for the response schema labeled "200." You can expand this box to view a screenshot illustrating the structure of the responses. By clicking the arrows, you can further expand the response schema to see the data identifiers and their descriptions. Additionally, note that you can switch the response structure from XML to JSON to view the schema in the respective format.

Attachments

You can send electronic attachments using the /upload/ service.

Attachments are uploaded as a separate file from the claim file. To upload a PDF attachment you will need to name the file with a unique attachment control number. Filename syntax: ACNNUM.pdf (Replace ACNNUM with a unique identifier of your choosing.)
Example: 11123456A.pdf
Then upload your claim file with the matching ACNNUM to link the attachment to the claim.

For XML/CSV/XLS/JSON claim files
Include these fields:
"attach_type_code" = Check available options in field list.
“attach_acn” = ACNNUM - This value should match the PDF filename sent [without the extension].
If your PDF file was named 11123456A, then your attach_acn value should be ”11123456A”.

Additional attachments can be added to the same claim using "attach_acn_2","attach_acn_3", etc..

For 837P / 837I claim files
Send the ACNNUM in the PWK06 segment.
If your PDF file was named 11123456A, then your PWK06 value should be ”11123456A”.

A maximum of 10 attachments can be linked to a claim. Each file cannot exceed 16MB.

CONNECTION ISSUES

Q Receiving a 403 Forbidden Error
A Please make sure you are not exceeding 100 API requests per minute.
If you do, you will receive a temporary block and a 403 error.

Q API failed to connect or did not respond after a period of time
A Make sure you are not exceeding 100 requests per minute and that no firewall or network device is blocking the connection.

UPLOAD ISSUES

Q Error message: Zero claims detected. error_code = 63
A This error means we did not receive any data in the "File" parameter. For the system to recognize a CSV/JSON/XML file you must send the ‘Filename’ parameter

ENROLLMENTS

Q In the API for enrollment, some enrollment needs a fillable pdf with signature. How can they be pulled for enrollment from the integrated application?
A The API enrollment endpoint returns a one time use URL. Your application should load this link into a popup or iframe.
This will allow your users to complete and submit the necessary paperwork from within your application, and does not require additional coding on your part.

INTEGRATION API & SFTP

Q Can an account have both API and SFTP working at the same time?
A Submitting claims via SFTP in addition to the API is no problem. Downloading responses and 835 from both can be problematic and may result in one method receiving updates and not the other.