List insurance policies

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

import requests

url = "https://api.maxcare.ai/v2/insurance-policies"

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/v2/insurance-policies', 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/v2/insurance-policies",
  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/v2/insurance-policies"

	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))

}

HttpResponse<String> response = Unirest.get("https://api.maxcare.ai/v2/insurance-policies")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v2/insurance-policies")

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": {
    "insurancePolicies": [
      {
        "id": "a1b2c3d4-5678-4abc-9def-0123456789ab",
        "patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
        "coverageOrder": 1,
        "memberId": "XYZ123456789",
        "groupNumber": "GRP001",
        "planName": "Blue Shield PPO",
        "policyType": "PPO",
        "payerName": "Blue Shield of California",
        "payerCode": "BS001",
        "subscriberFirstName": "Jane",
        "subscriberLastName": "Doe",
        "patientRelationshipToPolicyHolder": "SELF",
        "copayAmount": "25.00",
        "deductibleRemaining": "1250.00",
        "referralRequired": false,
        "policyEffectiveDate": "2025-01-01T00:00:00.000Z",
        "policyEndDate": "2026-01-01T00:00:00.000Z",
        "terminatedAt": null,
        "eligibilityStatus": "ACTIVE",
        "integrationEligibilityStatus": "Eligible",
        "eligibilityVerifiedAt": "2026-08-01T12:00:00.000Z",
        "payerPhone": "(800) 555-0123",
        "source": "modmed",
        "createdAt": "2026-03-20T18:35:10.209Z",
        "updatedAt": "2026-03-23T03:15:47.285Z"
      }
    ],
    "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"
}

GET

insurance-policies

List insurance policies

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

import requests

url = "https://api.maxcare.ai/v2/insurance-policies"

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/v2/insurance-policies', 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/v2/insurance-policies",
  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/v2/insurance-policies"

	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))

}

HttpResponse<String> response = Unirest.get("https://api.maxcare.ai/v2/insurance-policies")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v2/insurance-policies")

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": {
    "insurancePolicies": [
      {
        "id": "a1b2c3d4-5678-4abc-9def-0123456789ab",
        "patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
        "coverageOrder": 1,
        "memberId": "XYZ123456789",
        "groupNumber": "GRP001",
        "planName": "Blue Shield PPO",
        "policyType": "PPO",
        "payerName": "Blue Shield of California",
        "payerCode": "BS001",
        "subscriberFirstName": "Jane",
        "subscriberLastName": "Doe",
        "patientRelationshipToPolicyHolder": "SELF",
        "copayAmount": "25.00",
        "deductibleRemaining": "1250.00",
        "referralRequired": false,
        "policyEffectiveDate": "2025-01-01T00:00:00.000Z",
        "policyEndDate": "2026-01-01T00:00:00.000Z",
        "terminatedAt": null,
        "eligibilityStatus": "ACTIVE",
        "integrationEligibilityStatus": "Eligible",
        "eligibilityVerifiedAt": "2026-08-01T12:00:00.000Z",
        "payerPhone": "(800) 555-0123",
        "source": "modmed",
        "createdAt": "2026-03-20T18:35:10.209Z",
        "updatedAt": "2026-03-23T03:15:47.285Z"
      }
    ],
    "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

patientId

string

Filter by patient ID (UUID)

Example:

"8de03039-3a9e-417a-b2b3-a8b8df183631"

includeTerminated

boolean

default:false

Include terminated (archived) policies. Defaults to false.

Example:

false

eligibilityStatus

enum<string>

Filter by eligibility status

Available options:

ACTIVE,

INACTIVE,

PENDING,

UNKNOWN,

TERMINATED,

UNAVAILABLE

Example:

"ACTIVE"

updatedSince

string

Only return policies whose record was created or modified at/after this timestamp (ISO 8601). When set, results are ordered by updatedAt ascending with id as tiebreaker, overriding sortBy/sortOrder. Must carry an explicit UTC offset (...Z or ...+02:00) — a zone-less instant would be resolved against the database session timezone on some resources and the API process timezone on others, so the same string would mean two different moments. Pair with cursorId to walk safely — see that parameter; page/offset paging of this feed can drop rows. The bound is inclusive without cursorId, so boundary rows re-deliver — dedupe on id. A termination is visible as a change (terminatedAt is set), but pair with includeTerminated=true or the terminated row is filtered out of the delta entirely. One fidelity limit remains, which is why this feed is not a full substitute for a periodic full walk. payerName, planName, policyType and payerPhone are joined from the payer/plan tables, so a change to the payer or plan itself does not move the policy's updatedAt and is invisible here. The policy's own columns are covered: the EHR insurance sync compares values before writing, so a sync pass that changes nothing leaves updatedAt alone, and corrections made through the billing screens do move it. A hard delete cannot appear in a change feed either; a consumer that prunes still needs a full walk.

Example:

"2026-08-01T00:00:00.000Z"

updatedUntil

string

Only return policies whose record was last modified at/before this timestamp (ISO 8601). Pin this to the instant the walk started to freeze the window. Must carry an explicit UTC offset.

Example:

"2026-08-31T23:59:59.999Z"

cursorId

string

Id of the last row you already consumed, for a keyset walk. Pass it together with updatedSince set to that same row's updatedAt, always requesting page 1; the next page is everything ordered after (updatedAt, id). Use this rather than page/offset for any walk that must not drop rows. Paging a delta feed with page/offset is unsafe because the sort column is exactly what the sync workers rewrite: a row on an earlier page that changes mid-walk moves to the tail, every later row shifts one position toward the front, and the offset for the next page steps over whichever row moved into that slot. That row is never returned and its stamp is below the cursor the walk finishes on, so it is missed permanently while the walk still looks successful. On a cursor page pagination.totalCount counts the window starting at your cursor, so it shrinks as you walk — stop on a short page rather than on the count.

Example:

"pol_a1b2c3d456784abc9def0123456789ab"

sortBy

enum<string>

Sort field. Ignored when updatedSince/updatedUntil is set — see updatedSince.

Available options:

createdAt,

updatedAt,

coverageOrder

Example:

"coverageOrder"

sortOrder

enum<string>

Sort direction

Available options:

asc,

desc

Example:

"asc"

Response

Success

code

string

required

Response code

Example:

"success"

data

object

required

Show child attributes