> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/concepts/scopes.md). # Scopes Every Shortcut API scope, the presets in Settings, and what the complete, send, and trigger scopes do. After this page you can choose the exact scopes an integration needs and explain to an owner what each one allows. A scope is a permission on a token, written `resource:action`. A token can do exactly what its scopes allow, on the REST API and on the MCP server alike. Scopes are chosen when the token is created and never change; to grant more, create a new token. ## Rules * **`write` includes `read`.** A token with `customers:write` can also read customers. You never need both. * **`complete`, `send`, and `trigger` stand alone.** Nothing implies them and they imply nothing. `visits:write` does not let a token complete a visit, and `invoices:send` does not let it read invoices. * **One missing scope, one clear answer.** A request that needs a scope the token lacks gets `403 insufficient_scope` with the scope named in `requiredScope`. See [Errors](/developers/concepts/errors.md#insufficient_scope). * **Some answers need more than one scope.** When part of a response belongs to another resource, the part your token cannot read is left out and listed in `meta.omitted` with the scope that would add it. The request still succeeds. Check what a token holds with `GET /v1/me`; it needs no scope: ```bash curl https://api.shortcutco.com/v1/me \ -H "Authorization: Bearer $SHORTCUT_TOKEN" ``` ```json { "data": { "object": "token", "token": { "id": "0b4e6a2d-91c3-4f57-8e2a-6d1f3b9c7a40", "name": "Reporting", "kind": "api_key", "scopes": ["customers:read", "teams:read", "visits:read"] }, "workspace": { "id": "3f6a8e2b-1c4d-4e7f-8a9b-0c1d2e3f4a5b", "name": "Greenline Lawn Care", "timezone": "America/Denver", "today": "2026-10-16" }, "rateLimit": { "limit": 600, "remaining": 598, "resetSeconds": 41 } } } ``` ## Presets **Settings → API & integrations → Create token** offers three presets over the full scope grid. | Preset | What it grants | Use it for | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Read everything** | Every `read` scope. | AI agents you are trying out, dashboards, reporting, exports. | | **Standard integration** | Every `read` scope; `write` for customers, leads, estimates, jobs, visits, services, products, and tags; and `webhooks:manage`. | A CRM, website, or scheduling integration that keeps records in step. Nothing in it sends estimates or invoices, completes visits, records payments, or starts an automation. | | **Custom** | Exactly the boxes you tick. | Everything else. Start from nothing and add only what the integration calls. | The five opt-in scopes, `estimates:send`, `invoices:send`, `visits:complete`, `payments:write`, and `automations:trigger`, are off in every preset and carry a warning line in the picker. `invoices:write` is off in the presets too, because voiding an invoice is rarely an integration's job. ## Every scope | Scope | Label in Settings | What it allows | Read everything | Standard integration | | --------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------- | | `customers:read` | Read customers | Customers, their properties, tags, custom-field values, and external references. | Yes | Yes | | `customers:write` | Write customers | Create and update customers and their properties, tags, custom-field values, and external references; deactivate and reactivate. | | Yes | | `leads:read` | Read leads | Leads and their external references. | Yes | Yes | | `leads:write` | Write leads | Create and update leads; dismiss and restore them. | | Yes | | `estimates:read` | Read estimates | Estimates and their lines. | Yes | Yes | | `estimates:write` | Write estimates | Create estimates, update drafts, void them, and approve them on the customer's behalf. | | Yes | | `estimates:send` | Send estimates | Send or remind an estimate to the customer. | | | | `jobs:read` | Read jobs | Jobs and their schedules. | Yes | Yes | | `jobs:write` | Write jobs | Create jobs from services, schedule, pause, resume, cancel, and change their crew. | | Yes | | `visits:read` | Read visits | Visits on the schedule. | Yes | Yes | | `visits:write` | Write visits | Reschedule, assign, cancel, and skip visits. | | Yes | | `visits:complete` | Complete visits | Completes visits. As when completing in the app, billing follows five minutes later: it creates the visit's invoice, queues its delivery to the customer, and charges autopay when the customer has it on. Needs `visits:read` as well. | | | | `invoices:read` | Read invoices | Invoices and their lines, including how much has been paid on each and what customers still owe. | Yes | Yes | | `invoices:write` | Write invoices | Void invoices. | | | | `invoices:send` | Send invoices | Send or remind an invoice to the customer. | | | | `payments:read` | Read payments | Payments recorded against invoices. | Yes | Yes | | `payments:write` | Write payments | Record offline payments (cash, check, other) and reverse manual payments. | | | | `services:read` | Read services | The service catalog. | Yes | Yes | | `services:write` | Write services | Create, update, deactivate, and reactivate services. | | Yes | | `products:read` | Read products | The products catalog. | Yes | Yes | | `products:write` | Write products | Create and update products. | | Yes | | `tags:read` | Read tags | Tag definitions. | Yes | Yes | | `tags:write` | Write tags | Create, rename, and delete tags. | | Yes | | `custom_fields:read` | Read custom fields | Custom-field definitions. | Yes | Yes | | `teams:read` | Read crews | Crews and their members. | Yes | Yes | | `users:read` | Read staff | Staff names, email addresses, roles, statuses, and crews. | Yes | Yes | | `webhooks:manage` | Manage webhooks | Create and manage webhook subscriptions. Subscribing to events also needs that resource's read scope. | | Yes | | `automations:trigger` | Trigger automations | Lets records the API creates or changes start your automations, which can email or text customers and leads. Without it, records the API creates or changes, and the visits an approved estimate schedules, start none of your Automations rules or the new-lead welcome automation. Sending an estimate or invoice (`estimates:send`, `invoices:send`) always runs its delivery automation, including any steps you added to it. A job paused until a date resumes on that date like any paused job, and visits it schedules then run your rules. | | | The [OpenAPI description](https://api.shortcutco.com/v1/openapi.json) lists the scope each endpoint needs, in each operation's `security` and `x-required-scopes`. ## The opt-in scopes These five reach past their own resource: they message customers, create invoices, or move money. Grant them deliberately, to a token whose integration you trust with that effect, and keep them away from agents that act without a person watching. ### visits:complete Completing a visit through the API does exactly what **Complete** does in the app. The visit is completed at once, and billing follows after the same five-minute undo window, through the same billing every completion uses: it creates the visit's invoice, queues the invoice's delivery to the customer, and charges the customer's saved card when they have autopay on. `visits:write` covers moving and assigning visits; completion is its own scope because of those effects. The token needs `visits:read` as well. `POST /v1/visits/{id}/complete` (MCP `complete_visit`) returns the completion: `billing` is `pending` until billing runs, with `holdId` and `finalizeAt` (when it runs), and `effects` saying what billing will do: `invoice_on_finalize`, and `autopay_on_finalize` when the customer has autopay on with a usable saved card. An hourly visit is priced by your office from the crew's time, and a workspace or customer that invoices by hand or on a schedule gets its invoice later, so neither is announced. The invoice does not exist yet when the call returns. Read it afterwards from the visit's `invoiceId` (`GET /v1/visits/{id}`), from `GET /v1/invoices`, or from the `invoice.created` webhook event. Completing an already-completed visit writes nothing, lists it in `alreadyCompletedVisitIds`, and reports what billing did: `billing` (`invoiced`, `covered_by_prepay`, `invoice_manual`, `invoice_scheduled`, or `invoice_review`; `not_billed` for a visit completed before completion records existed and on no invoice), `invoiceId`, and `effects` such as `invoice_created`, `notification_queued` or `notification_sent`, `autopay_attempted`, and `covered_by_prepay`. A paid prepayment that covers the visit is never reported as a created invoice. When the visit's work waits to be invoiced by hand or on a schedule, its field add-ons are still billed at once on their own invoice: that is `addOnInvoiceId`, with the `add_on_invoice_created` effect, and the visit's `invoiceId` stays null. Retrying with the same `Idempotency-Key`, or completing the visit again, never creates a second invoice or a second charge. By default only the given visit is completed. With `completeStop=true`, the other open services at the same stop (same customer, date, crew, and address) are completed with it as one batch and billed on one invoice, the way the crew app finishes a visit. `completedVisitIds` lists the visits the request completed and `alreadyCompletedVisitIds` the stop's services that were already completed. Each service is completed in its own transaction, so if one is refused, the services completed before it stay completed, each with its own completion record; retrying completes the rest. API calls for one stop run one at a time: a second call while one is running is refused with [`stop_completion_in_progress`](/developers/concepts/errors.md#stop_completion_in_progress). This does not cover the app: a crew finishing the same stop at the same moment is not held back. A retry adds the remaining services to the stop's billing batch when that batch has not started billing and bills more than 30 seconds later, so the stop is billed on one invoice; otherwise they start a new batch and are billed on a second invoice. A pending chemical record is completed with its planned amounts in the same transaction as its visit, so it is saved only if that visit's completion is; if any service at the stop has no plan, nothing is completed or written. Without `automations:trigger`, the visit is completed and billed with automations off: neither starts your **Automations** rules, the invoice-created or job-completed automation, or a review request. The completion records this, so billing five minutes later honors it too. The invoice's delivery to the customer is part of completing and always runs. Later changes to the invoice, such as its delivery being recorded or a payment, including an autopay charge, start your rules like any invoice's. ### estimates:send and invoices:send Sending or reminding an estimate or an invoice emails or texts the customer through the same delivery the app uses. Reading and writing the estimate or invoice is a separate scope. ### payments:write Records an offline payment (cash, check, or other) against an invoice, or reverses a manual payment. Both change the invoice's balance and your payment records. No scope lets a token charge a card directly. ### automations:trigger With `automations:trigger`, a change made through the API starts the same automations as the same change made in the app. A lead created through the API starts the new-lead welcome automation, as a lead from your website form does; a job scheduled through the API starts the job-scheduled automation; and automation rules your workspace has built in **Automations** react to new and changed customers, tags, custom-field values, leads, jobs, and visits. Without it, records the API creates or changes, and the visits an approved estimate schedules, start none of your Automations rules or the new-lead welcome automation. Sending an estimate or invoice (`estimates:send`, `invoices:send`) always runs its delivery automation, including any steps you added to it. A job paused until a date resumes on that date like any paused job, and visits it schedules then run your rules. The write itself happens as usual: the lead is created and staff are notified, the job's visits are put on the schedule, and webhooks are delivered. A later change made in the app starts automations as usual, even on a record the API created: for example, staff completing a visit of a job the API created starts the rules that react to completed visits. Rules that start on a date, on a schedule, or for every customer who matches a condition check your records on their own timetable, so they include records created through the API. ## Writes that reach a customer Some lead writes change the customer the lead belongs to, so they need `customers:write` as well as `leads:write`, and are refused with `403 insufficient_scope` before anything changes: * creating a lead whose email belongs to an existing customer; * giving an unlinked lead the email of an existing customer; * changing the square footage of a lead linked to a customer's property, or moving such a lead's address. ## Choosing scopes | Integration | Scopes | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Website lead form | `leads:write`, plus `customers:write` so returning customers can ask for more work. Add `automations:trigger` if the new-lead welcome automation should greet them. See [Push website leads](/developers/guides/push-website-leads.md). | | Daily schedule digest | `visits:read`, `teams:read`, `customers:read`. See [Daily schedule bot](/developers/guides/daily-schedule-bot.md). | | AI agent, first week | **Read everything**. See [MCP overview](/developers/mcp/overview.md). | | CRM sync | **Standard integration**, or Custom with the `write` scopes for the resources you sync. |