Scopes - Max AI Developer Docs

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`

Some opt-in parameters need a second scope, because they return another resource’s data:

Expansion	Also requires	Returns
`GET /bills/{id}?include=payments`	`read:eras`	Dated payment history (patient payments, ERA remittances, manual payer checks) — carries check dates and numbers
`GET /v4/bills?include=identity`, `GET /v4/bills/{id}?include=identity`, `GET /v4/appointments?include=identity`, `GET /v4/appointments/{id}?include=identity`	`read:patients`	`masterPatientId` / `duplicatePatientIds` on the nested patient
`GET /v4/payers?patientId=`	`read:patients`	Payers in that patient’s EHR instance (`?instanceId=` needs only `read:payers`)

Without the extra scope the request is a 403, not a silently narrower response.

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.

ERA Payments (v4)

Scope	Endpoints	Description
`read:era_payments`	`GET /v4/era-payments`	Check-level payer remittances: check or EFT trace number, check total, payment method, check and deposit dates, payer, reconciliation status and linked bank deposit ids

A separate scope from read:eras: it exposes the practice’s payment ledger (check totals and trace numbers), not per-procedure remittance lines. Filter by checkNumber, bankTransactionId or a check/deposit date range; the list is offset-paged.

Bank Deposits (v4)

Scope	Endpoints	Description
`read:bank_transactions`	`GET /v4/bank-accounts`	The organization’s connected bank accounts: institution, account name, last 4 digits, type, status and last sync time
	`GET /v4/bank-transactions`	Deposits (credits only) into those accounts, as a change feed on `updatedSince`

Each deposit carries the bank’s description as printed (description), which can name a patient. Account and routing numbers and the Plaid connection are never shared. A deposit’s status tells you whether it is still the row to use: follow supersededBy when a pending deposit is replaced by its posted twin. Facility-limited API keys are refused on these endpoints.

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
	`GET /v4/tasks/capabilities`	Per EHR instance: whether tasks can be anchored to a patient and assigned to staff groups
	`GET /v4/tasks/assignee-groups`	The EHR’s active staff groups (e.g. Billing), read live, for `assigneeGroupIds` (ModMed)

Intramail (v4, ModMed)

Always one user’s own ModMed mail, read from Max’s copy, never anyone else’s:

The logged-in user when your app forwards their App Bridge token (maxcare.appToken()) in the X-Session-Token header. It is verified for your app and the organization (401 authorizer_unverified otherwise), as for e-prescribing sends. Send it on every request a user makes in an app several people use.
The API key’s creator when there is no X-Session-Token, for your own background jobs on your own mail. Never use this path to serve another user.

Each of that user’s personal ModMed logins in the organization is a mailbox: GET /v4/intramail/status lists them and says whose mail it is (actingFor); pass a mailbox’s id (imb_…) as mailboxId to act on it, otherwise the one marked isDefault is used. Sync is off until that user turns it on in their Max settings (My Settings); it then runs every 5 minutes through their personal ModMed login and reads the newest 100 messages of each folder. While it is off, every intramail route except GET /v4/intramail/status answers 403 intramail_unavailable; Max keeps the stored copy, and turning sync back on serves it again. A facility-limited key sees staff-only mail and mail linked to a patient or note at its facilities; mail with a patient as author or recipient but no patient or note link is hidden from it, since its facility cannot be told. So a facility-limited key must link any message it sends with a patient recipient to a patient (patientId, or noteId; a reply keeps the original’s patient link, or its visit’s patient), or it gets 400.

Scope	Endpoints	Description
`read:intramail`	`GET /v4/intramail/status`	Whether sync is on, and the acting user’s mailboxes (one per ModMed login) with when each last synced
	`GET /v4/intramail/messages`	One folder (`inbox`, `archived`, `sent`, `draft`), newest first
	`GET /v4/intramail/messages/{id}`	One message
	`GET /v4/intramail/recipients`	Staff, staff groups and, with `includePatients=true` (also needs `read:patients`), patients to address

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. Each call draws from your app’s share of the practice’s EHR rate; over it the call fails with ehr_unavailable and can be retried with backoff. Cover templates are practice-wide and change rarely, so fetch them once and cache them rather than calling this before every send.

Pharmacies and Prescriptions (v4, ModMed)

Scope	Endpoints	Description
`read:pharmacies`	`GET /v4/pharmacies/search?patientId=`	Search the Surescripts pharmacy directory by name, ZIP, city, state or NCPDP id
	`GET /v4/patients/{patientId}/pharmacies`	The pharmacies linked to a patient’s chart, with their e-prescribing capabilities
`read:prescriptions`	`GET /v4/patients/{patientId}/prescriptions`	A patient’s prescriptions with their e-prescribing status
	`GET /v4/prescriptions/{id}`	One prescription, read live
	`GET /v4/prescriptions`	The organization’s stored prescriptions across patients, as a change feed — see E-Prescribing
	`GET /v4/prescribers?patientId=`	Visible, unexpired prescribers, by name prefix

These reads open a live session against the practice’s EHR on every call, except GET /v4/prescriptions, which serves the platform’s stored copy (see E-Prescribing). Prescription and patient-pharmacy endpoints are ModMed only and answer 400 capability_unsupported on other EHRs. Directory search works on EZDerm too, but requires zip there and cannot look up an NCPDP id.

Patient Tracking (v4)

Scope	Endpoints	Description
`read:patient_tracking`	`GET /v4/patient-tracking/sources`	Tracking sources (EHR connections) with availability and capabilities
	`GET /v4/patient-tracking/facilities?sourceId=`	A source’s facilities
	`GET /v4/patient-tracking/providers?sourceId=`	A source’s selectable providers
	`GET /v4/patient-tracking/snapshot?sourceId=`	The live tracking board: rows, counts, freshness and completeness

Snapshot expansions need more scopes, all of them: include=patient needs read:patients; contact needs read:patients and read:patient_pii; visitDetails needs read:appointments; insurance needs read:patients and read:insurance_policies. A requested expansion without them is a 403 include_not_permitted. See Patient Tracking.

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

Payer Directory

Scope	Endpoints	Description
`read:payers`	`GET /v4/payers`	Search active payer records with an EHR payer id, owned by the requesting practice
	`GET /v4/payers/{id}`	Resolve a saved source payer UUID, including inactive records
	`GET /v4/payers/capabilities`	Per EHR instance: whether exact-payer insurance writes and `policyType` are supported
	`GET /v4/payers/directory?q=`	Search the EHR’s national payer directory, linked to the practice’s own payers (ModMed; read live from the EHR)

These endpoints are available on v1–v4. Existing installations and API keys must grant read:payers before using the directory. Adding payer identity fields to already-authorized policies, claims, or ERA lines does not require this additional scope. See Payer identities.

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)

Organization Members

Scope	Endpoints	Description
`read:members`	`GET /v4/marketplace/members`	The installing organization’s complete staff roster: name, email, image, role, app access, and the Max AI user id an App Bridge token’s `sub` carries

Staff email addresses are personal data, so this is a scope of its own rather than part of any other. Declare it in optional_scopes so each organization opts in; an organization that has not granted it gets 403 from the endpoint. (Declared as a required scope instead, it is in effect for every installation of that version, like any required scope.) Available on v1–v4.

Write Scopes

Patients

Scope	Endpoints	Description
`write:patients`	`POST /v4/patients`	Create a patient chart in the EHR
`write:patient_merge`	`POST /v4/ehr/patients/{id}/merge`, `GET /v4/ehr/patients/{id}/merge-preview`, `GET /v4/ehr/patient-merges/{id}`	Merge a duplicate chart into another in the EHR (ModMed). Irreversible: the merged chart is archived
	`PATCH /v4/patients/{id}`	Update a patient’s demographics
	`POST /v4/patients/{id}/insurance`	Attach insurance, resolving the payer by name
	`POST /v4/patients/{id}/insurance:exact`	Attach insurance with the exact practice payer from `GET /payers` (`payerId`); never searches by name
	`POST /v4/patients/{id}/insurance/cards`	Attach an insurance card image
	`PUT /v4/patients/{id}/referring-provider`	Add a referring provider by NPI (EZDerm: the default referring physician), adding it to the practice’s directory when missing (`Idempotency-Key` supported)

An exact insurance write needs no extra scope, but an app picks the payerId from GET /payers, which requires read:payers. A payerId outside the patient’s EHR instance, inactive, or without an EHR id is refused with 422 payer_not_writable before anything is written.

Patient Documents

Scope	Endpoints	Description
`write:patient_documents`	`POST /v4/patients/{id}/documents`	File a PDF or image (e.g. a referral fax) on the patient’s chart in the EHR (`Idempotency-Key` supported)

Payers

Scope	Endpoints	Description
`write:payers`	`POST /v4/payers`	Add a payer from `GET /payers/directory` to the practice’s payer list, non-contracted (ModMed). Returns the existing payer instead of a duplicate (`Idempotency-Key` supported)

An added payer goes straight into the practice’s EHR payer list with default billing settings (non-contracted, accepts assignment, electronic claims when the payer takes them) and is usable for claims at once — tell the practice’s billing team so they can review it. There is no daily limit on added payers, so guard against loops in your app.

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) on a note (`noteId`) or, where supported, on a patient’s chart with no note (`patientId`, optionally assigned to staff groups). `Idempotency-Key` supported
	`PATCH /v3/tasks/{id}`	Update task status (complete/cancel)

Intramail (v4, ModMed)

Sent through the acting user’s personal ModMed login (the X-Session-Token user, else the API key’s creator). Idempotency-Key supported on sends.

Scope	Endpoints	Description
`write:intramail`	`POST /v4/intramail/messages`	Send a message, or save a draft; optionally linked to a patient or note
	`POST /v4/intramail/messages/{id}/reply`	Reply, reply all or forward (a new message quoting the original, as EMA builds it), adding recipients
	`PATCH /v4/intramail/messages/{id}`	Mark read or unread, flag, archive or unarchive a received message
	`DELETE /v4/intramail/messages/{id}`	Delete a draft

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.There is no daily limit on sends: each send draws from your app’s share of the practice’s EHR rate, and over it POST /v3/faxes/send fails with ehr_unavailable; retry with the same idempotencyKey. Every send is a real fax, so guard against loops in your app.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.

Prescriptions and E-Prescribing (v4, ModMed)

Scope	Endpoints	Description
`write:prescriptions`	`POST /v4/prescriptions`	Create a PENDING draft copied from an existing prescription, with an explicit prescriber (`Idempotency-Key` required)
	`POST /v4/prescriptions/{id}/void`	Void a PENDING draft (not yet supported: answers `400 capability_unsupported`)
`write:prescription_sends`	`POST /v4/prescriptions/{id}/send`	E-prescribe a pending prescription to a pharmacy — see E-Prescribing

write:prescription_sends is its own consent group, separate from write:prescriptions: approving drafts never approves transmitting them. Sending is the prescriber’s signature in the EHR, it transmits over Surescripts, and it cannot be recalled through Max AI. Controlled substances are always refused.A draft copied from a prescription that carries a diagnosis is refused with 400 capability_unsupported for now, and so is voiding a draft.

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; each check is a paid eligibility request, so there is no daily limit to rely on)

Deposit Matches (v4)

Scope	Endpoints	Description
`write:deposit_matches`	`POST /v4/deposit-matches`	Record which bank deposit paid one of your app’s own remittances (`Idempotency-Key` required)
	`DELETE /v4/deposit-matches/{id}`	Revoke one of your app’s own matches

A match is your app’s record only: it never changes Max AI’s ERA reconciliation. A deposit already held by a confirmed ERA link, a card payout or another app is refused with 409 deposit_already_allocated, and allocations above the deposit amount with 409 over_allocated. Reading deposits needs read:bank_transactions as well.

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.

​How Scopes Work

​Available Scopes

​Read Scopes

​Patient Data

​Appointments

​Providers

​Facilities

​Billing

​Claims

​Payer Remittances (ERAs)

​ERA Payments (v4)

​Bank Deposits (v4)

​Notes

​Tasks

​Intramail (v4, ModMed)

​Emails

​Faxes

​Pharmacies and Prescriptions (v4, ModMed)

​Patient Tracking (v4)

​Phone Numbers

​Inventory

​Payer Directory

​Insurance Policies

​Prior Authorizations

​Eligibility Checks

​Organization Members

​Write Scopes

​Patients

​Patient Documents

​Payers

​Notes

​Tasks

​Intramail (v4, ModMed)

​Emails

​Faxes

​Prescriptions and E-Prescribing (v4, ModMed)

​Products

​Inventory

​Eligibility Checks

​Deposit Matches (v4)

​Checking Your Scopes

​Insufficient Scope Error

How Scopes Work

Available Scopes

Read Scopes

Patient Data

Appointments

Providers

Facilities

Billing

Claims

Payer Remittances (ERAs)

ERA Payments (v4)

Bank Deposits (v4)

Notes

Tasks

Intramail (v4, ModMed)

Emails

Faxes

Pharmacies and Prescriptions (v4, ModMed)

Patient Tracking (v4)

Phone Numbers

Inventory

Payer Directory

Insurance Policies

Prior Authorizations

Eligibility Checks

Organization Members

Write Scopes

Patients

Patient Documents

Payers

Notes

Tasks

Intramail (v4, ModMed)

Emails

Faxes

Prescriptions and E-Prescribing (v4, ModMed)

Products

Inventory

Eligibility Checks

Deposit Matches (v4)

Checking Your Scopes

Insufficient Scope Error