Scopes

Scopes are permissions that control which API endpoints your app can access. When a clinic installs your app, they grant the scopes your app has requested.

How Scopes Work

When you create your app, you declare which scopes it needs
When a clinic installs your app, they review and approve those scopes
When you create an API key, you select which of the approved scopes it should have
At runtime, your effective permissions are the intersection of the key’s scopes and the clinic’s installation grants, and each API endpoint checks for the required scope before returning data

If you call an endpoint without the required scope, you’ll receive a 403 Forbidden response.

Available Scopes

Read Scopes

Patient Data

Scope	Endpoints	Description
`read:patients`	`GET /v3/patients`	List patients with search and pagination
	`GET /v3/patients/{id}`	Get a specific patient by ID

Appointments

Scope	Endpoints	Description
`read:appointments`	`GET /v3/appointments`	List appointments with filters (incl. type, reason for visit, cosmetic flag)
	`GET /v3/appointments/{id}`	Get a specific appointment by ID

Providers

Scope	Endpoints	Description
`read:providers`	`GET /v3/providers`	List providers
	`GET /v3/providers/{id}`	Get a specific provider by ID

Facilities

Scope	Endpoints	Description
`read:facilities`	`GET /v3/facilities`	List facilities
	`GET /v3/facilities/{id}`	Get a specific facility by ID

Billing

Scope	Endpoints	Description
`read:bills`	`GET /v3/bills`	List bills with pagination
	`GET /v3/bills/{id}`	Get detailed bill with line items and coding groups, including per-line paid (payer AND patient) and primary-payer allowed amounts
`read:encounters`	(legacy)	Same as `read:bills`

Claims

Scope	Endpoints	Description
`read:claims`	`GET /v3/claims`	List claims with pagination
	`GET /v3/claims/{id}`	Get detailed claim with insurance info, including per-line paid (payer AND patient) and primary-payer allowed amounts on its coding groups

Payer Remittances (ERAs)

Scope	Endpoints	Description
`read:eras`	`GET /v3/era-service-lines`	List payer remittance service lines with pagination
	`GET /v3/era-service-lines/{id}`	Get a specific ERA service line with its adjustments

Per-procedure allowed, paid and patient-responsibility amounts, with the CARC/RARC adjustments explaining the gap between charge and paid. Reported for both EHRs. deductibleAmount, coinsuranceAmount and copayAmount are EzDerm only: the ModMed ERA sync does not write those columns, so they are NULL on every ModMed line even when the remit reported them. Do not derive patient responsibility by summing the three — on ModMed that sum is 0 on a line the patient really owes. Use patientResponsibilityAmount, which is populated for both EHRs. Sync on updatedSince: payer amounts keep moving for 90+ days after service as recoupments, secondary payers and 835 PLB adjustments land.

Notes

Scope	Endpoints	Description
`read:notes`	`GET /v3/notes`	List patient visit notes
	`GET /v3/notes/{id}`	Get a specific note by ID
`read:soap_notes`	`GET /v3/notes?includeSoapNote=true`	Include SOAP note content (requires `read:notes` too)

Tasks

Scope	Endpoints	Description
`read:tasks`	`GET /v3/tasks`	List tasks with filters (status, note, provider, patient, date range)
	`GET /v3/tasks/{id}`	Get a specific task by ID

Emails

Scope	Endpoints	Description
`read:emails`	`GET /v3/emails`	List emails
	`GET /v3/emails/{id}`	Get a specific email by ID

Faxes

Scope	Endpoints	Description
`read:faxes`	`GET /v3/faxes`	List the faxes your app sent, with delivery status
	`GET /v3/faxes/{id}`	Get a specific fax by ID
	`GET /v3/faxes/templates?patientId=`	List the practice’s fax cover-page templates

read:faxes also gates delivery of the fax.status_changed webhook.

GET /v3/faxes/templates opens a live session against the practice’s EHR — unlike the other two reads, which are served from our own records. It is capped at 2,000 template reads per organization per UTC day across all installed apps; over the cap it answers 429 until the budget resets at 00:00 UTC. Cover templates are practice-wide and change rarely, so fetch them once and cache them rather than calling this before every send.

Phone Numbers

Scope	Endpoints	Description
`read:phone_numbers`	`GET /v3/phone-numbers`	List clinic phone numbers

Inventory

Scope	Endpoints	Description
`read:inventory`	`GET /v3/inventory/changes`	List inventory changes
	`GET /v3/inventory/changes/{id}`	Get a specific inventory change
	`GET /v3/inventory/changes/{id}/products`	Get products for an inventory change
	`GET /v3/inventory/stock-levels`	Get current stock levels
	`GET /v3/inventory/stock-levels/detail`	Get stock levels with per-lot breakdown (lot number, expiration date, quantity)
`read:products`	`GET /v3/inventory/products`	List products in the catalog
	`GET /v3/inventory/products/{id}`	Get a specific product

Insurance Policies

Scope	Endpoints	Description
`read:insurance_policies`	`GET /v3/insurance-policies`	List patient insurance policies (ranking, payer, termination, eligibility)
	`GET /v3/insurance-policies/{id}`	Get a specific insurance policy

Prior Authorizations

Scope	Endpoints	Description
`read:prior_authorizations`	`GET /v3/prior-authorizations`	List prior authorizations (visits approved/remaining, validity window, CPT linkage)
	`GET /v3/prior-authorizations/{id}`	Get a specific prior authorization

Eligibility Checks

Scope	Endpoints	Description
`read:eligibility_checks`	`GET /v3/eligibility-checks`	List eligibility check history
	`GET /v3/eligibility-checks/{id}`	Get a specific eligibility check (poll until completed/failed)

Write Scopes

Notes

Scope	Endpoints	Description
`write:notes_images`	`POST /v3/notes/{noteId}/images?providerId=`	Upload an image to a note
	`DELETE /v3/notes/{noteId}/images/{imageId}?providerId=`	Delete an image from a note
`write:soap_notes`	`PATCH /v3/notes/{noteId}?providerId=`	Edit SOAP note fields (with EHR sync)
	`PATCH /v3/notes/{noteId}/impressions/{impressionId}?providerId=`	Edit impression fields (ModMed only)

Tasks

Scope	Endpoints	Description
`write:tasks`	`POST /v3/tasks`	Create a task (synchronous EHR push)
	`PATCH /v3/tasks/{id}`	Update task status (complete/cancel)

Emails

Scope	Endpoints	Description
`write:emails`	`POST /v3/emails/send`	Send an email

Faxes

Scope	Endpoints	Description
`write:faxes`	`POST /v3/faxes/send`	Fax chart documents and/or an uploaded file from a patient’s chart

Faxes are sent through the practice’s own EHR fax subsystem, so anything you attach is filed as a chart document and becomes part of the medical record. A sent fax cannot be recalled — idempotencyKey is required, and repeating a call with the same key returns the original fax instead of sending another.Sending is capped at 200 faxes per organization per UTC day across all installed apps. Over the cap, POST /v3/faxes/send answers 429; the budget resets at 00:00 UTC. Failed sends count, replays do not.A repeat with the same idempotencyKey never dials — it returns the original record, so re-asking after an unknown outcome is safe. While the first send is still in flight you get a 503 rather than the record — repeat the same request shortly, and never mint a new key for it. A 409 means something else: the key was already used for a DIFFERENT fax, and only then should you use a new key. It is scoped to (app, organization) and never expires.

Products

Scope	Endpoints	Description
`write:products`	`POST /v3/inventory/products`	Create a new product
	`PUT /v3/inventory/products/{id}`	Update an existing product

Inventory

Scope	Endpoints	Description
`write:inventory`	`POST /v3/inventory/changes`	Create an inventory change

Eligibility Checks

Scope	Endpoints	Description
`write:eligibility_checks`	`POST /v3/eligibility-checks`	Run an on-demand eligibility check for a policy (409 if the policy was checked in the last 10 minutes; 429 past 200 org checks/24h)

Checking Your Scopes

Use the /v3/marketplace/me endpoint to see which scopes your API key currently has. This endpoint does not require any scope — it is always available.

curl -X GET "https://api.maxcare.ai/v3/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"

The response includes your granted scopes:

{
  "code": "success",
  "data": {
    "app": {
      "id": "app_2b6fe6754b674990bb07fa16ece694c3",
      "slug": "testapi",
      "liveVersionId": "apv_89ba6db5e6644a008849299672992970"
    },
    "organization": {
      "id": "org_7e2c8cfeb7a94deb986de7012589e72b"
    },
    "scopes": [
      "read:patients",
      "read:appointments",
      "read:providers",
      "read:facilities",
      "read:bills",
      "read:claims",
      "read:eras",
      "read:notes",
      "read:soap_notes",
      "read:emails",
      "read:faxes",
      "read:phone_numbers",
      "read:inventory",
      "read:products",
      "read:encounters",
      "write:notes_images",
      "write:emails",
      "write:faxes",
      "write:products",
      "write:inventory"
    ]
  }
}

Insufficient Scope Error

If you call an endpoint without the required scope:

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

To resolve this, update your app’s requested scopes in the Max AI dashboard and have the clinic re-approve the updated permissions.

Overview

Core Concepts

Working with Appointments

Working with Patients

Building Apps

How Scopes Work

Available Scopes

Read Scopes

Patient Data

Appointments

Providers

Facilities

Billing

Claims

Payer Remittances (ERAs)

Notes

Tasks

Emails

Faxes

Phone Numbers

Inventory

Insurance Policies

Prior Authorizations

Eligibility Checks

Write Scopes

Notes

Tasks

Emails

Faxes

Products

Inventory

Eligibility Checks

Checking Your Scopes

Insufficient Scope Error

​How Scopes Work

​Available Scopes

​Read Scopes

​Patient Data

​Appointments

​Providers

​Facilities

​Billing

​Claims

​Payer Remittances (ERAs)

​Notes

​Tasks

​Emails

​Faxes

​Phone Numbers

​Inventory

​Insurance Policies

​Prior Authorizations

​Eligibility Checks

​Write Scopes

​Notes

​Tasks

​Emails

​Faxes

​Products

​Inventory

​Eligibility Checks

​Checking Your Scopes

​Insufficient Scope Error

How Scopes Work

Available Scopes

Read Scopes

Patient Data

Appointments

Providers

Facilities

Billing

Claims

Payer Remittances (ERAs)

Notes

Tasks

Emails

Faxes

Phone Numbers

Inventory

Insurance Policies

Prior Authorizations

Eligibility Checks

Write Scopes

Notes

Tasks

Emails

Faxes

Products

Inventory

Eligibility Checks

Checking Your Scopes

Insufficient Scope Error