Appointment Based Claim Creation

With the POST /appointments/{appointmentid}/claim call, API users are able to submit a claim for an appointment. A claim must contain all charges for the appointment. By focusing the API on generating a claim for a given appointment several common errors seen with HL7 claim creation are avoided. 

To create a claim the POST /appointments/{appointmentid}/claim requires API users to input a Practice ID, Appointment ID, and the Claim Charges as a valid JSON object. Please see the Documentation for this API call found in the Insurance and Financial folder of the Documentation Page.

What happens after a claim is created:

The API response for a successfully generated claim will output ‘Success: True’ along with the ClaimID of the newly created claim. GET /claims/{claimid} allows for insight of individual claims which users can use to check status/progress on various claims. API users can also leverage POST /claims/{claimid}/note to add a claim note to the newly created claim.

For each new claim that is added, the athenaNet rules engine scrubs the claim, identifies if any additional information is required, and adds the claim to claims queue.  If the athenaNet rules engine finds a problem with the claim, it will obtain a HOLD status. Practice staff members review each claim, resolve any issues and set the claim to the proper status according to their claim workflow. Once the issues have been resolved (or if the rules engine found no issues in the first place), the claim will go into DROP status and be sent to the payer.


  • API users can submit only one claim per call.
  • API users are not able to edit or delete a claim once it is submitted.
  • A maximum of 4 diagnosis codes can be tied to a procedure code.


claimcharges= [{
   "procedurecode" : "99213",
   "units" : "1",
   "icd9code1" : "V700",
   "icd10code1" : "Z0000"

Note: Currently, IO Docs doesn't fully support POST /appointments/{appointmentid}/claim call. There seems to be an issue processing input, this is actively being looked into. Other methods, such as Curl, are still functional. 

API Response:

The API response for a successfully generated claim will always indicate Success: True and the ClaimID of the newly created claim.


    "claimids" : [
    "success" : "true"

Common Errors:

API users should validate that a given procedure code, or codes, are in a physician's fee schedule using GET /feeschedules/checkprocedure. If a submitted procedure code is not in a physician's fee schedule, API will not create a claim and an error message will be returned ("One or more of the procedure codes specified are not valid.").

In addition, if users want to include modifiers with a procedure code, append all modifiers with a comma after the procedure code (e.g. "99213,GT,26").  The GET /feeschedules/checkprocedure API can be used with modifiers included to be sure all modifiers are valid.

 API users can also leverage POST /claims/{claimid}/note to add a claim note to the newly created claim.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others