Scopes

A scope is one thing a key or a connected app is allowed to do. An admin picks a key's scopes when they create it; a connected app asks for scopes when someone connects it.

A call needs the scope its endpoint names, and the user the credential acts as still needs a role that allows the action in the app. A missing scope is refused with ERR_SCOPE_MISSING.

Connected apps that sign in through OAuth, including MCP clients, can be granted only the scopes marked so below, and meta:read is always included. These are for API keys only: leads:write, schema:read, usage:read and webhooks:manage.

All scopes

Scope	Allows	Connected apps
`meta:read`	Statuses, departments, custom fields, forms, folders, the team list and other lookups.	Always granted
`leads:write`	Create leads. Kept for keys from the first release; jobs:write includes it.	API keys only
`schema:read`	The first release's name for meta:read.	API keys only
`jobs:read`	Read jobs, leads and opportunities.	Can be granted
`jobs:write`	Create and update jobs and leads, change status, convert and mark lost.	Can be granted
`contacts:read`	Read contacts.	Can be granted
`contacts:write`	Add contacts to jobs and update them.	Can be granted
`tasks:read`	Read tasks.	Can be granted
`tasks:write`	Create, update, complete and reopen tasks.	Can be granted
`notes:read`	Read job notes.	Can be granted
`notes:write`	Add job notes.	Can be granted
`calendar:read`	Read calendar events.	Can be granted
`calendar:write`	Create, change and delete calendar events.	Can be granted
`estimates:read`	Read estimates with their sections and lines.	Can be granted
`estimates:write`	Draft and edit estimates, and send them by email.	Can be granted
`invoices:read`	Read invoices and their payments.	Can be granted
`invoices:write`	Draft and edit invoices, and send them by email.	Can be granted
`files:read`	List job files and get download links.	Can be granted
`files:write`	Upload job files through signed upload links.	Can be granted
`comms:send`	Email a job's contacts from the acting user's connected mailbox.	Can be granted
`work_orders:read`	Read work orders.	Can be granted
`work_orders:write`	Create work orders and change their status.	Can be granted
`materials:read`	Read materials, stock items and job materials.	Can be granted
`materials:write`	Change stock items and job materials.	Can be granted
`purchasing:read`	Read vendors and purchase orders.	Can be granted
`purchasing:write`	Create vendors and purchase orders, add lines and receive stock.	Can be granted
`products:read`	Read products.	Can be granted
`products:write`	Create and update products.	Can be granted
`time:read`	Read time entries.	Can be granted
`usage:read`	This account's call usage and limits.	API keys only
`webhooks:manage`	Create and manage webhook endpoints and see deliveries.	API keys only

Endpoints by scope

`meta:read`

Statuses, departments, custom fields, forms, folders, the team list and other lookups.

Endpoint	What it does
`GET /v1/account`	Check your credentials
`GET /v1/custom-fields`	List the account's job fields
`GET /v1/job-forms`	List the account's job forms
`GET /v1/job-forms/{form_id}`	Get one job form
`GET /v1/meta/custom-fields`	List the account's job fields
`GET /v1/meta/departments`	List departments
`GET /v1/meta/estimate-statuses`	List estimate statuses
`GET /v1/meta/invoice-statuses`	List invoice statuses
`GET /v1/meta/job-forms`	List the account's job forms
`GET /v1/meta/job-statuses`	List job statuses
`GET /v1/meta/material-types`	List material types
`GET /v1/meta/product-categories`	List product categories
`GET /v1/meta/task-statuses`	List task statuses
`GET /v1/meta/units`	List units of measure
`GET /v1/meta/users`	List the account's users
`GET /v1/meta/work-order-types`	List work order types and their statuses
`GET /v1/webhook-event-types`	List webhook event types

`leads:write`

Create leads. Kept for keys from the first release; jobs:write includes it.

Endpoint	What it does
`POST /v1/leads/create`	Create a lead

`schema:read`

The first release's name for meta:read.

No endpoint names this scope directly.

`jobs:read`

Read jobs, leads and opportunities.

Endpoint	What it does
`GET /v1/jobs`	List jobs
`GET /v1/jobs/{job_id}`	Get a job

`jobs:write`

Create and update jobs and leads, change status, convert and mark lost.

Endpoint	What it does
`POST /v1/jobs`	Create a job
`PATCH /v1/jobs/{job_id}`	Update a job
`POST /v1/jobs/{job_id}/convert-to-project`	Convert an opportunity into a job
`POST /v1/jobs/{job_id}/move-to-lost`	Mark a lead or opportunity lost
`POST /v1/jobs/{job_id}/status`	Move a job to a status

`contacts:read`

Read contacts.

Endpoint	What it does
`GET /v1/contacts`	List contacts
`GET /v1/contacts/{contact_id}`	Get a contact

`contacts:write`

Add contacts to jobs and update them.

Endpoint	What it does
`PATCH /v1/contacts/{contact_id}`	Update a contact
`POST /v1/jobs/{job_id}/contacts`	Add a contact to a job

`tasks:read`

Read tasks.

Endpoint	What it does
`GET /v1/jobs/{job_id}/tasks`	List a job's tasks
`GET /v1/tasks/{task_id}`	Get a task

`tasks:write`

Create, update, complete and reopen tasks.

Endpoint	What it does
`POST /v1/jobs/{job_id}/tasks`	Add a task to a job
`PATCH /v1/tasks/{task_id}`	Update a task
`POST /v1/tasks/{task_id}/complete`	Complete a task
`POST /v1/tasks/{task_id}/reopen`	Reopen a task

`notes:read`

Read job notes.

Endpoint	What it does
`GET /v1/jobs/{job_id}/notes`	List a job's notes
`GET /v1/jobs/{job_id}/threads`	List a job's threads

`notes:write`

Add job notes.

Endpoint	What it does
`POST /v1/jobs/{job_id}/notes`	Add a note to a job

`calendar:read`

Read calendar events.

Endpoint	What it does
`GET /v1/calendar/events`	List events in a date range
`GET /v1/calendar/events/{event_id}`	Get an event

`calendar:write`

Create, change and delete calendar events.

Endpoint	What it does
`POST /v1/calendar/events`	Create an event
`DELETE /v1/calendar/events/{event_id}`	Delete an event
`PATCH /v1/calendar/events/{event_id}`	Update an event

`estimates:read`

Read estimates with their sections and lines.

Endpoint	What it does
`GET /v1/estimates`	List estimates
`GET /v1/estimates/{estimate_id}`	Get an estimate

`estimates:write`

Draft and edit estimates, and send them by email.

Endpoint	What it does
`POST /v1/estimates`	Create a draft estimate
`PATCH /v1/estimates/{estimate_id}`	Update a draft estimate
`PATCH /v1/estimates/{estimate_id}/lines/{line_id}`	Update a line
`POST /v1/estimates/{estimate_id}/sections`	Add a section
`POST /v1/estimates/{estimate_id}/sections/{section_id}/lines`	Add a line
`POST /v1/estimates/{estimate_id}/send`	Email an estimate to contacts

`invoices:read`

Read invoices and their payments.

Endpoint	What it does
`GET /v1/invoices`	List invoices
`GET /v1/invoices/{invoice_id}`	Get an invoice
`GET /v1/invoices/{invoice_id}/payments`	List an invoice's payments
`GET /v1/payments`	List payments

`invoices:write`

Draft and edit invoices, and send them by email.

Endpoint	What it does
`POST /v1/invoices`	Create a blank invoice
`POST /v1/invoices/from-estimate/{estimate_id}`	Invoice an estimate
`PATCH /v1/invoices/{invoice_id}`	Update a draft invoice
`PATCH /v1/invoices/{invoice_id}/lines/{line_id}`	Update an invoice line
`POST /v1/invoices/{invoice_id}/sections`	Add a section to an invoice
`POST /v1/invoices/{invoice_id}/sections/{section_id}/lines`	Add a line to an invoice
`POST /v1/invoices/{invoice_id}/send`	Email an invoice to contacts

`files:read`

List job files and get download links.

Endpoint	What it does
`GET /v1/files/{file_id}`	Get a file
`GET /v1/jobs/{job_id}/files`	List a job's files

`files:write`

Upload job files through signed upload links.

Endpoint	What it does
`POST /v1/files/complete`	Finish an upload
`POST /v1/jobs/{job_id}/files/upload-url`	Start an upload

`comms:send`

Email a job's contacts from the acting user's connected mailbox.

Endpoint	What it does
`POST /v1/jobs/{job_id}/emails`	Email a job's contacts

`work_orders:read`

Read work orders.

Endpoint	What it does
`GET /v1/work-orders`	List work orders
`GET /v1/work-orders/{work_order_id}`	Get a work order

`work_orders:write`

Create work orders and change their status.

Endpoint	What it does
`POST /v1/work-orders`	Create a work order
`PATCH /v1/work-orders/{work_order_id}`	Update a work order
`POST /v1/work-orders/{work_order_id}/status`	Move a work order to a step

`materials:read`

Read materials, stock items and job materials.

Endpoint	What it does
`GET /v1/jobs/{job_id}/bom`	Get a job's bill of materials
`GET /v1/materials`	List materials
`GET /v1/materials/{material_id}`	Get a material
`GET /v1/stock-items/{item_id}`	Get a stock item

`materials:write`

Change stock items and job materials.

Endpoint	What it does
`POST /v1/jobs/{job_id}/bom/lines`	Add a bill of materials line
`DELETE /v1/jobs/{job_id}/bom/lines/{line_id}`	Remove a bill of materials line
`PATCH /v1/jobs/{job_id}/bom/lines/{line_id}`	Update a bill of materials line

`purchasing:read`

Read vendors and purchase orders.

Endpoint	What it does
`GET /v1/purchase-orders`	List purchase orders
`GET /v1/purchase-orders/{po_id}`	Get a purchase order
`GET /v1/vendors`	List suppliers
`GET /v1/vendors/{vendor_id}`	Get a supplier

`purchasing:write`

Create vendors and purchase orders, add lines and receive stock.

Endpoint	What it does
`POST /v1/purchase-orders`	Create a purchase order
`PATCH /v1/purchase-orders/{po_id}`	Update a purchase order
`POST /v1/purchase-orders/{po_id}/lines`	Add a purchase order line
`PATCH /v1/purchase-orders/{po_id}/lines/{line_id}`	Update a purchase order line
`POST /v1/purchase-orders/{po_id}/receive`	Record a delivery
`POST /v1/vendors`	Create a supplier
`PATCH /v1/vendors/{vendor_id}`	Update a supplier

`products:read`

Read products.

Endpoint	What it does
`GET /v1/products`	List products
`GET /v1/products/{product_id}`	Get a product

`products:write`

Create and update products.

Endpoint	What it does
`POST /v1/products`	Create a product
`PATCH /v1/products/{product_id}`	Update a product

`time:read`

Read time entries.

Endpoint	What it does
`GET /v1/time-entries`	List time entries

`usage:read`

This account's call usage and limits.

Endpoint	What it does
`GET /v1/account/usage`	See this account's API usage Needs an admin.

`webhooks:manage`

Create and manage webhook endpoints and see deliveries.

Endpoint	What it does
`GET /v1/webhook-deliveries/{delivery_id}`	Get a delivery Needs an admin.
`POST /v1/webhook-deliveries/{delivery_id}/retry`	Retry a failed delivery Needs an admin.
`GET /v1/webhooks`	List webhook endpoints Needs an admin.
`POST /v1/webhooks`	Add a webhook endpoint Needs an admin.
`DELETE /v1/webhooks/{endpoint_id}`	Delete a webhook endpoint Needs an admin.
`GET /v1/webhooks/{endpoint_id}`	Get a webhook endpoint Needs an admin.
`PATCH /v1/webhooks/{endpoint_id}`	Change a webhook endpoint Needs an admin.
`GET /v1/webhooks/{endpoint_id}/deliveries`	List an endpoint's deliveries Needs an admin.
`POST /v1/webhooks/{endpoint_id}/rotate-secret`	Rotate a webhook signing secret Needs an admin.
`POST /v1/webhooks/{endpoint_id}/test`	Send a test event Needs an admin.