List claims

curl --request GET \
  --url https://api.maxcare.ai/v1/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <x-organization-id>'

import requests

url = "https://api.maxcare.ai/v1/claims"

headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Organization-Id': '<x-organization-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.maxcare.ai/v1/claims', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maxcare.ai/v1/claims",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maxcare.ai/v1/claims"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v1/claims")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "code": "success",
  "data": {
    "claims": [
      {
        "id": "c9d0e1f2-a3b4-4c5d-6e7f-8a9b0c1d2e3f",
        "claimAmount": "450.00",
        "balance": "120.00",
        "claimStatus": "accepted",
        "submittedDate": "2025-01-16",
        "claimCreatedDate": "2025-01-15",
        "billId": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
        "dateOfService": "2025-01-15",
        "billHumanId": "BILL-78432",
        "patientId": "c56103bc-d39c-46d3-9f31-38dd2b5e05f6",
        "patientFirstName": "Sarah",
        "patientLastName": "Johnson",
        "patientDob": "1985-03-15",
        "primaryProviderName": "Dr. James Wilson",
        "billUnderName": "Dr. James Wilson",
        "facilityId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "facilityName": "West LA Dermatology",
        "specialty": "Dermatology",
        "primaryInsurance": "Blue Cross Blue Shield",
        "secondaryInsurance": null,
        "payerName": "Blue Cross Blue Shield of Michigan",
        "payerCode": "BCBSM",
        "payerPosition": 1,
        "deepLinkUrl": "https://practice.modmed.com/ema/web/practice/staff/#/practice/staff/financial/home/claims/78432",
        "createdAt": "2025-01-15T09:30:00.000Z",
        "updatedAt": "2025-01-20T14:22:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 100,
      "totalCount": 250,
      "totalPages": 3
    }
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Claims

List claims

Returns a paginated list of claims. Requires read:claims scope. TOTALS ARE ALWAYS RETURNED here — pagination.totalCount/totalPages are never null and there is no includeTotals opt-out (unlike /bills, where the second aggregate dominates the request). They are counted over the whole filtered set on every page, so they move with concurrent writes: treat a totalCount that SHRINKS between pages of one walk as a walk you must not trust — a delete has slid rows past your offset — and re-read the window rather than concluding you saw everything.

GET

claims

List claims

curl --request GET \
  --url https://api.maxcare.ai/v1/claims \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <x-organization-id>'

import requests

url = "https://api.maxcare.ai/v1/claims"

headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Organization-Id': '<x-organization-id>', Authorization: 'Bearer <token>'}
};

fetch('https://api.maxcare.ai/v1/claims', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maxcare.ai/v1/claims",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maxcare.ai/v1/claims"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v1/claims")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "code": "success",
  "data": {
    "claims": [
      {
        "id": "c9d0e1f2-a3b4-4c5d-6e7f-8a9b0c1d2e3f",
        "claimAmount": "450.00",
        "balance": "120.00",
        "claimStatus": "accepted",
        "submittedDate": "2025-01-16",
        "claimCreatedDate": "2025-01-15",
        "billId": "9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
        "dateOfService": "2025-01-15",
        "billHumanId": "BILL-78432",
        "patientId": "c56103bc-d39c-46d3-9f31-38dd2b5e05f6",
        "patientFirstName": "Sarah",
        "patientLastName": "Johnson",
        "patientDob": "1985-03-15",
        "primaryProviderName": "Dr. James Wilson",
        "billUnderName": "Dr. James Wilson",
        "facilityId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
        "facilityName": "West LA Dermatology",
        "specialty": "Dermatology",
        "primaryInsurance": "Blue Cross Blue Shield",
        "secondaryInsurance": null,
        "payerName": "Blue Cross Blue Shield of Michigan",
        "payerCode": "BCBSM",
        "payerPosition": 1,
        "deepLinkUrl": "https://practice.modmed.com/ema/web/practice/staff/#/practice/staff/financial/home/claims/78432",
        "createdAt": "2025-01-15T09:30:00.000Z",
        "updatedAt": "2025-01-20T14:22:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 100,
      "totalCount": 250,
      "totalPages": 3
    }
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

Authorization

string

header

required

Marketplace API key

Headers

X-Organization-Id

string

required

Target clinic organization ID

Query Parameters

dateFrom

string

Filter from date (ISO 8601)

Example:

"2025-01-01"

dateTo

string

Filter to date (ISO 8601)

Example:

"2025-12-31"

billId

string

Filter by bill ID

status

string

Filter by normalized claim status (comma-separated). Values: draft, submitted, invalid, rejected, denied, approved_partially, completed, unknown, ready_for_postage, worked, on_hold, scrub_failure. Supplying the parameter with NO values — ?status= or ?status=, — is a 400, not an empty filter: omit the parameter when you have no statuses to filter on.

Example:

"completed,denied"

code

string

Filter to claims whose BILL carries a line item with any of these procedure codes (CPT/HCPCS, comma-separated). THE BILL'S CODES, not the claim's own: a claim can carry a claim-scoped coding group whose line items disagree with the bill's, and this filter deliberately reads the bill, with the same scoping /v4/bills uses. A consumer joining dose -> bill -> claim wants this reading; filtering on the claim's own codes instead would drop exactly the bill/claim divergence cases such a consumer needs to see. The response cannot tell you which reading you got, which is why it is stated here. Archived bills are excluded, matching /v4/bills, so a claim whose bill was voided does not satisfy this filter — it would otherwise be a claim you cannot reconcile against any bill this API will return. NOT COVERED BY THE updatedSince CURSOR — do not combine the two for delta sync. This filter is evaluated against BILL-side rows, and the cursor is the CLAIM's own updatedAt, which does not move when a bill's coding changes. A claim whose bill gains this procedure code AFTER your cursor passed it is never delivered on any later page: it satisfies the filter, but its updatedAt stays below every subsequent cursor, and a claim in a final state is not re-synced. The reverse is as bad for a delete-by-exclusion consumer — remove the code from the bill and the claim simply stops appearing, with no tombstone to distinguish that from 'nothing changed'. Use code for full or date-windowed re-walks, which re-cover their ground, and walk updatedSince unfiltered. Exact match, case-insensitive on both the value you send and the code as stored. Supplying the parameter with NO values — ?code= or ?code=, — is a 400, not an empty filter: build the query string so an empty cohort OMITS the parameter, because silently dropping it would return every claim in the organization for a request that asked for a few.

Example:

"J3245,J0717"

integrationStatus

string

Filter by integration status

updatedSince

string

Only return claims whose record was created or modified at/after this timestamp (ISO 8601). A status change re-touches updatedAt even when the date of service does not move. When set, results are ordered by updatedAt ascending so pages are monotonic: page through to the end, then use the LAST row's updatedAt as the next cursor. Do not advance the cursor mid-pagination.Rows sharing the boundary updatedAt can re-deliver on the next pull, since the bound is inclusive — dedupe on id.

Example:

"2025-06-01T00:00:00.000Z"

updatedUntil

string

Only return claims whose record was last modified at/before this timestamp (ISO 8601).

Example:

"2025-06-30T23:59:59.999Z"

Response

Success

code

string

required

Response code

Example:

"success"

data

object

required

Show child attributes