Skip to main content
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

  1. When you create your app, you declare which scopes it needs
  2. When a clinic installs your app, they review and approve those scopes
  3. When you create an API key, you select which of the approved scopes it should have
  4. 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

ScopeEndpointsDescription
read:patientsGET /v3/patientsList patients with search and pagination
GET /v3/patients/{id}Get a specific patient by ID

​
Appointments

ScopeEndpointsDescription
read:appointmentsGET /v3/appointmentsList appointments with filters
GET /v3/appointments/{id}Get a specific appointment by ID

​
Providers

ScopeEndpointsDescription
read:providersGET /v3/providersList providers
GET /v3/providers/{id}Get a specific provider by ID

​
Facilities

ScopeEndpointsDescription
read:facilitiesGET /v3/facilitiesList facilities
GET /v3/facilities/{id}Get a specific facility by ID

​
Billing

ScopeEndpointsDescription
read:billsGET /v3/billsList bills with pagination
GET /v3/bills/{id}Get detailed bill with line items and coding groups
read:encounters(legacy)Same as read:bills

​
Claims

ScopeEndpointsDescription
read:claimsGET /v3/claimsList claims with pagination
GET /v3/claims/{id}Get detailed claim with insurance info

​
Notes

ScopeEndpointsDescription
read:notesGET /v3/notesList patient visit notes
GET /v3/notes/{id}Get a specific note by ID
read:soap_notesGET /v3/notes?includeSoapNote=trueInclude SOAP note content (requires read:notes too)

​
Tasks

ScopeEndpointsDescription
read:tasksGET /v3/tasksList tasks with filters (status, note, provider, patient, date range)
GET /v3/tasks/{id}Get a specific task by ID

​
Emails

ScopeEndpointsDescription
read:emailsGET /v3/emailsList emails
GET /v3/emails/{id}Get a specific email by ID

​
Phone Numbers

ScopeEndpointsDescription
read:phone_numbersGET /v3/phone-numbersList clinic phone numbers

​
Inventory

ScopeEndpointsDescription
read:inventoryGET /v3/inventory/changesList inventory changes
GET /v3/inventory/changes/{id}Get a specific inventory change
GET /v3/inventory/changes/{id}/productsGet products for an inventory change
GET /v3/inventory/stock-levelsGet current stock levels
read:productsGET /v3/inventory/productsList products in the catalog
GET /v3/inventory/products/{id}Get a specific product

​
Write Scopes

​
Notes

ScopeEndpointsDescription
write:notes_imagesPOST /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_notesPATCH /v3/notes/{noteId}?providerId=Edit SOAP note fields (with EHR sync)
PATCH /v3/notes/{noteId}/impressions/{impressionId}?providerId=Edit impression fields (ModMed only)

​
Tasks

ScopeEndpointsDescription
write:tasksPOST /v3/tasksCreate a task (synchronous EHR push)
PATCH /v3/tasks/{id}Update task status (complete/cancel)

​
Emails

ScopeEndpointsDescription
write:emailsPOST /v3/emails/sendSend an email

​
Products

ScopeEndpointsDescription
write:productsPOST /v3/inventory/productsCreate a new product
PUT /v3/inventory/products/{id}Update an existing product

​
Inventory

ScopeEndpointsDescription
write:inventoryPOST /v3/inventory/changesCreate an inventory change

​
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:notes",
      "read:soap_notes",
      "read:emails",
      "read:phone_numbers",
      "read:inventory",
      "read:products",
      "read:encounters",
      "write:notes_images",
      "write:emails",
      "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.