*REST API › Guides*

# Scopes

> A key carries scopes; each operation requires exactly one. Grant the fewest you need.

The scopes of the contract. Each one has an anchor, so you can link to it.

| Scope | Allows | Operations | MCP tools |
| --- | --- | --- | --- |
| `account:read` | Read the account that made the request: its name, timezone, currency, country, add-ons, the API key with its scopes, and the usage limits. `GET /api/v1/account` is the first call of any integration, so this scope is the one to grant first. | 1 | 1 |
| `ai:ask` | Ask the Filmo assistant a question about the account's data in natural language. It never writes, but each call spends AI credits of the account, and it can search the web. | 1 | 1 |
| `availability:read` | Check item availability in a date range, and read the unavailabilities of a person, a vehicle or a space. | 2 | 2 |
| `availability:write` | Declare, correct, close and delete unavailabilities of a person, a vehicle or a space. Deleting an unavailability cannot be undone. | 3 | 3 |
| `collections:read` | Read the collections tree that the catalog is organized by. | 1 | 1 |
| `collections:write` | Create and rename collections, and move them within the tree. | 2 | 2 |
| `contacts:read` | Read contacts (customers and suppliers), their addresses and related contacts, and look contacts up by contact number. | 4 | 4 |
| `contacts:write` | Create, change and delete contacts, their addresses, commercial terms and related-contact links. Deleting a contact also deletes its relationships, notes, files, tasks, payment methods and customer portal access, and cannot be undone. Removing an address cannot be undone either. | 10 | 10 |
| `contracts:read` | Read rental contracts with their document and signature status. | 2 | 2 |
| `contracts:write` | Validate, sign, void and cancel rental contracts. Validating a contract numbers it and locks it. Voiding removes its validity. Cancelling a contract is terminal: a cancelled contract can no longer be signed. An already signed contract can only be undone by voiding the document. | 4 | 4 |
| `crm:read` | Read CRM opportunities and the pipelines they move through. | 4 | 4 |
| `crm:write` | Create and change opportunities, move them between stages, close them and link documents to them. | 5 | 5 |
| `custom-fields:read` | Read the definitions of the account's custom fields (identifier, type and accepted values), not the values stored on records. | 1 | 1 |
| `incidents:read` | Read incidents (broken, lost or damaged equipment) and the count of incidents by status. | 3 | 3 |
| `incidents:write` | Open and update incidents, and comment on them. | 3 | 3 |
| `internal-services:read` | Read internal services, the planned assignments that do not hang from an order. | 2 | 2 |
| `internal-services:write` | Create and change internal services. | 2 | 2 |
| `invoices:read` | Read invoices (with their lines), credit notes and proformas (totals and status; their lines are not published). | 7 | 7 |
| `invoices:write` | Validate and void invoices and credit notes, change the commercial status of proformas, and create or update the mirror of an invoice issued by another system. Validating an invoice or a credit note numbers it, signs it and locks it, and neither can be edited afterwards; voiding keeps the number and cannot be undone. Voiding an invoice does not issue a credit note. | 6 | 6 |
| `items:read` | Read catalog items and their serialized units. | 4 | 4 |
| `items:write` | Create, change and delete items, including their pricing, physical properties, accessories, alternatives and variants, and update serialized units. Deleting an item also deletes its serialized units, notes, files and tasks, and cannot be undone. | 9 | 9 |
| `kits:read` | Read kits, the named groups of items that go out together. | 2 | 2 |
| `kits:write` | Create and change kits. | 2 | 2 |
| `notes:read` | Read the notes attached to an entity of the account. | 1 | 1 |
| `notes:write` | Write notes on entities of the account. | 1 | 1 |
| `orders:read` | Read rental orders and their lines. | 3 | 3 |
| `orders:write` | Create and change orders, and run actions on them (reserve, unreserve, cancel, archive, return line items). Cancelling an order cannot be undone through the API. Returning line items puts material back into stock, so a retry without the same `Idempotency-Key` returns it twice. Send your own key. Reserving deducts stock and creates the delivery and return tasks. | 7 | 7 |
| `planner:read` | Read the staff and fleet services of a date window, with who covers them, and the resources that can be assigned. | 2 | 2 |
| `planner:write` | Assign resources to planner services and remove them. | 2 | 2 |
| `projects:read` | Read projects and the catalog of project types. | 3 | 3 |
| `projects:write` | Create, change and archive projects, and link or unlink orders to them. | 5 | 5 |
| `purchase-orders:read` | Read purchase orders to suppliers. | 2 | 2 |
| `purchase-orders:write` | Change, approve and receive purchase orders. Receiving a purchase order registers new inventory, so a retry without the same `Idempotency-Key` duplicates the stock. Send your own key. | 3 | 3 |
| `quotes:read` | Read quotes (active version) and their lines. | 3 | 3 |
| `quotes:write` | Change the commercial status of quotes. Confirming a version of a quote moves every other version of it to `superseded`. | 1 | 1 |
| `repair-tickets:read` | Read repair tickets. | 2 | 2 |
| `repair-tickets:write` | Create and change repair tickets, including their lines. Sending `lines` when updating a ticket replaces the whole set of lines: send all of them or none. | 2 | 2 |
| `schedule:read` | Read the consolidated schedule of a date range: projects, orders, tasks, internal services and order services. | 1 | 1 |
| `services:read` | Read services, the sellable lines that do not come from inventory. | 2 | 2 |
| `services:write` | Create and change services, pricing included. | 2 | 2 |
| `spaces:read` | Read warehouses and rentable spaces. | 2 | 2 |
| `spaces:write` | Change and delete spaces, and replace their amenities and equipment and set their pricing. Deleting a space also deletes its notes, files, tasks, images and declared unavailabilities, and cannot be undone. | 4 | 4 |
| `staff:read` | Read staff members and check staff availability in a date range. | 3 | 3 |
| `staff:write` | Create, change and delete staff members (organizational data only). Deleting a staff member cannot be undone. | 3 | 3 |
| `subrents:read` | Read subrents, the equipment rented from other companies to cover a job. | 2 | 2 |
| `subrents:write` | Change subrents. | 1 | 1 |
| `supplier-invoices:read` | Read invoices received from suppliers. | 2 | 2 |
| `supplier-invoices:write` | Validate and void invoices received from suppliers. Validating a supplier invoice numbers it and locks it, and voiding keeps its number. Both need the purchases add-on. | 2 | 2 |
| `tags:read` | Read the tag vocabulary of the account. | 1 | 1 |
| `tags:write` | Create and delete tags, and assign or remove them on entities. Deleting a tag removes it from every entity that carried it, and cannot be undone. | 4 | 4 |
| `tasks:read` | Read tasks, schedule events and task types. | 3 | 3 |
| `tasks:write` | Create, change and delete tasks. Deleting a task cannot be undone. | 3 | 3 |
| `treasury:read` | Read treasury accounts, payments and payment methods, and the payments of an invoice. | 6 | 6 |
| `treasury:write` | Record, change and link payments. Recording a payment writes to your accounts: a retry without the same `Idempotency-Key` records it twice. Send your own key. | 3 | 3 |
| `users:read` | Read the people with access to the account, with their role and access status. Only administrators can call it. | 1 | 1 |
| `vehicles:read` | Read fleet vehicles and check fleet availability in a date range. | 3 | 3 |
| `vehicles:write` | Create, change and delete vehicles. Deleting a vehicle cannot be undone. | 3 | 3 |
| `workflows:read` | List the workflows of the account and whether each one is active. Definitions are not published. | 1 | 1 |
| `workflows:run` | Start a run of a workflow, as the Run button does in the app. The run executes in the background and does whatever the workflow's steps say, so it can change data in Filmo and may have effects outside Filmo. This is the broadest permission in the contract: a run does whatever the workflow's steps say. Grant it only to integrations that need to start workflows, and send your own `Idempotency-Key`. | 1 | 1 |

## Every scope

### account:read

Read the account that made the request: its name, timezone, currency, country, add-ons, the API key with its scopes, and the usage limits. [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account) is the first call of any integration, so this scope is the one to grant first.

- [`GET /api/v1/account`](https://docs.filmo.io/rest-api/endpoint-reference/account/get-the-account) — Get the account

### ai:ask

Ask the Filmo assistant a question about the account's data in natural language. It never writes, but each call spends AI credits of the account, and it can search the web.

- [`POST /api/v1/ai/ask`](https://docs.filmo.io/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data) — Ask the AI about your data

### availability:read

Check item availability in a date range, and read the unavailabilities of a person, a vehicle or a space.

- [`POST /api/v1/availability/check`](https://docs.filmo.io/rest-api/endpoint-reference/availability/check-item-availability) — Check item availability
- [`GET /api/v1/availability/unavailabilities`](https://docs.filmo.io/rest-api/endpoint-reference/availability/list-the-unavailabilities-of-a-resource) — List the unavailabilities of a resource

### availability:write

Declare, correct, close and delete unavailabilities of a person, a vehicle or a space. Deleting an unavailability cannot be undone.

- [`POST /api/v1/availability/unavailabilities`](https://docs.filmo.io/rest-api/endpoint-reference/availability/declare-an-unavailability) — Declare an unavailability
- [`PATCH /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/rest-api/endpoint-reference/availability/correct-or-close-an-unavailability) — Correct or close an unavailability
- [`DELETE /api/v1/availability/unavailabilities/{unavailabilityId}`](https://docs.filmo.io/rest-api/endpoint-reference/availability/delete-an-unavailability) — Delete an unavailability

### collections:read

Read the collections tree that the catalog is organized by.

- [`GET /api/v1/collections`](https://docs.filmo.io/rest-api/endpoint-reference/collections/list-collections) — List collections

### collections:write

Create and rename collections, and move them within the tree.

- [`POST /api/v1/collections`](https://docs.filmo.io/rest-api/endpoint-reference/collections/create-a-collection) — Create a collection
- [`PATCH /api/v1/collections/{collectionId}`](https://docs.filmo.io/rest-api/endpoint-reference/collections/update-a-collection) — Update a collection

### contacts:read

Read contacts (customers and suppliers), their addresses and related contacts, and look contacts up by contact number.

- [`GET /api/v1/contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/list-contacts) — List contacts
- [`GET /api/v1/contacts/{contactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/get-a-contact) — Get a contact
- [`GET /api/v1/contacts/{contactId}/related-contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/list-the-contacts-related-to-a-contact) — List the contacts related to a contact
- [`POST /api/v1/contacts/lookup`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/look-up-contacts-by-external-reference) — Look up contacts by external reference

### contacts:write

Create, change and delete contacts, their addresses, commercial terms and related-contact links. Deleting a contact also deletes its relationships, notes, files, tasks, payment methods and customer portal access, and cannot be undone. Removing an address cannot be undone either.

- [`POST /api/v1/contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/create-a-contact) — Create a contact
- [`PATCH /api/v1/contacts/{contactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-a-contact) — Update a contact
- [`DELETE /api/v1/contacts/{contactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/delete-a-contact) — Delete a contact
- [`PATCH /api/v1/contacts/{contactId}/preferences`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-the-commercial-terms-of-a-contact) — Update the commercial terms of a contact
- [`POST /api/v1/contacts/{contactId}/addresses`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/add-an-address-to-a-contact) — Add an address to a contact
- [`PATCH /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/update-an-address-of-a-contact) — Update an address of a contact
- [`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/remove-an-address-from-a-contact) — Remove an address from a contact
- [`POST /api/v1/contacts/{contactId}/related-contacts`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/relate-two-contacts) — Relate two contacts
- [`PATCH /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/change-the-role-of-a-relationship) — Change the role of a relationship
- [`DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`](https://docs.filmo.io/rest-api/endpoint-reference/contacts/unrelate-two-contacts) — Unrelate two contacts

### contracts:read

Read rental contracts with their document and signature status.

- [`GET /api/v1/contracts`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/list-contracts) — List contracts
- [`GET /api/v1/contracts/{contractId}`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/get-a-contract) — Get a contract

### contracts:write

Validate, sign, void and cancel rental contracts. Validating a contract numbers it and locks it. Voiding removes its validity. Cancelling a contract is terminal: a cancelled contract can no longer be signed. An already signed contract can only be undone by voiding the document.

- [`POST /api/v1/contracts/{contractId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/validate-a-contract) — Validate a contract
- [`POST /api/v1/contracts/{contractId}/sign`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/record-the-signature-of-a-contract) — Record the signature of a contract
- [`POST /api/v1/contracts/{contractId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/void-a-contract) — Void a contract
- [`POST /api/v1/contracts/{contractId}/cancel`](https://docs.filmo.io/rest-api/endpoint-reference/contracts/cancel-a-contract-operatively) — Cancel a contract operatively

### crm:read

Read CRM opportunities and the pipelines they move through.

- [`GET /api/v1/crm/opportunities`](https://docs.filmo.io/rest-api/endpoint-reference/crm/list-opportunities) — List opportunities
- [`GET /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/get-an-opportunity) — Get an opportunity
- [`GET /api/v1/crm/pipelines`](https://docs.filmo.io/rest-api/endpoint-reference/crm/list-pipelines) — List pipelines
- [`GET /api/v1/crm/pipelines/{pipelineId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/get-a-pipeline) — Get a pipeline

### crm:write

Create and change opportunities, move them between stages, close them and link documents to them.

- [`POST /api/v1/crm/opportunities`](https://docs.filmo.io/rest-api/endpoint-reference/crm/create-an-opportunity) — Create an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}`](https://docs.filmo.io/rest-api/endpoint-reference/crm/update-an-opportunity) — Update an opportunity
- [`PATCH /api/v1/crm/opportunities/{opportunityId}/stage`](https://docs.filmo.io/rest-api/endpoint-reference/crm/move-an-opportunity-to-another-stage) — Move an opportunity to another stage
- [`POST /api/v1/crm/opportunities/{opportunityId}/close`](https://docs.filmo.io/rest-api/endpoint-reference/crm/close-an-opportunity) — Close an opportunity
- [`POST /api/v1/crm/opportunities/{opportunityId}/links`](https://docs.filmo.io/rest-api/endpoint-reference/crm/link-a-document-to-an-opportunity) — Link a document to an opportunity

### custom-fields:read

Read the definitions of the account's custom fields (identifier, type and accepted values), not the values stored on records.

- [`GET /api/v1/custom-fields`](https://docs.filmo.io/rest-api/endpoint-reference/custom-fields/list-custom-field-definitions) — List custom field definitions

### incidents:read

Read incidents (broken, lost or damaged equipment) and the count of incidents by status.

- [`GET /api/v1/incidents`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/list-incidents) — List incidents
- [`GET /api/v1/incidents/{incidentId}`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/get-an-incident) — Get an incident
- [`GET /api/v1/incidents/status-counts`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/count-incidents-by-status) — Count incidents by status

### incidents:write

Open and update incidents, and comment on them.

- [`POST /api/v1/incidents`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/open-an-incident) — Open an incident
- [`PATCH /api/v1/incidents/{incidentId}`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/update-an-incident) — Update an incident
- [`POST /api/v1/incidents/{incidentId}/comments`](https://docs.filmo.io/rest-api/endpoint-reference/incidents/comment-on-an-incident) — Comment on an incident

### internal-services:read

Read internal services, the planned assignments that do not hang from an order.

- [`GET /api/v1/internal-services`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/list-internal-services) — List internal services
- [`GET /api/v1/internal-services/{internalServiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/get-an-internal-service) — Get an internal service

### internal-services:write

Create and change internal services.

- [`POST /api/v1/internal-services`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/create-an-internal-service) — Create an internal service
- [`PATCH /api/v1/internal-services/{internalServiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/internal-services/update-an-internal-service) — Update an internal service

### invoices:read

Read invoices (with their lines), credit notes and proformas (totals and status; their lines are not published).

- [`GET /api/v1/invoices`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/list-invoices) — List invoices
- [`GET /api/v1/invoices/{invoiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/get-an-invoice) — Get an invoice
- [`GET /api/v1/invoices/{invoiceId}/lines`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/list-the-lines-of-an-invoice) — List the lines of an invoice
- [`GET /api/v1/credit-notes`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/list-credit-notes) — List credit notes
- [`GET /api/v1/credit-notes/{creditNoteId}`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/get-a-credit-note) — Get a credit note
- [`GET /api/v1/proformas`](https://docs.filmo.io/rest-api/endpoint-reference/proformas/list-proformas) — List proformas
- [`GET /api/v1/proformas/{proformaId}`](https://docs.filmo.io/rest-api/endpoint-reference/proformas/get-a-proforma) — Get a proforma

### invoices:write

Validate and void invoices and credit notes, change the commercial status of proformas, and create or update the mirror of an invoice issued by another system. Validating an invoice or a credit note numbers it, signs it and locks it, and neither can be edited afterwards; voiding keeps the number and cannot be undone. Voiding an invoice does not issue a credit note.

- [`POST /api/v1/invoices/{invoiceId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/validate-an-invoice) — Validate an invoice
- [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/void-an-invoice) — Void an invoice
- [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice) — Create or update the mirror of an externally issued invoice
- [`POST /api/v1/credit-notes/{creditNoteId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/validate-a-credit-note) — Validate a credit note
- [`POST /api/v1/credit-notes/{creditNoteId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/credit-notes/void-a-credit-note) — Void a credit note
- [`PATCH /api/v1/proformas/{proformaId}/status`](https://docs.filmo.io/rest-api/endpoint-reference/proformas/change-the-commercial-status-of-a-proforma) — Change the commercial status of a proforma

### items:read

Read catalog items and their serialized units.

- [`GET /api/v1/items`](https://docs.filmo.io/rest-api/endpoint-reference/items/list-items) — List items
- [`GET /api/v1/items/{itemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/get-an-item) — Get an item
- [`GET /api/v1/serialized-items`](https://docs.filmo.io/rest-api/endpoint-reference/items/list-serialized-items) — List serialized items
- [`GET /api/v1/serialized-items/{serializedItemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/get-a-serialized-item) — Get a serialized item

### items:write

Create, change and delete items, including their pricing, physical properties, accessories, alternatives and variants, and update serialized units. Deleting an item also deletes its serialized units, notes, files and tasks, and cannot be undone.

- [`POST /api/v1/items`](https://docs.filmo.io/rest-api/endpoint-reference/items/create-an-item) — Create an item
- [`PATCH /api/v1/items/{itemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-an-item) — Update an item
- [`DELETE /api/v1/items/{itemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/delete-an-item) — Delete an item
- [`PATCH /api/v1/items/{itemId}/physical-properties`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-weight-and-dimensions) — Update weight and dimensions
- [`PATCH /api/v1/items/{itemId}/pricing`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-pricing-of-an-item) — Update the pricing of an item
- [`PATCH /api/v1/serialized-items/{serializedItemId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-a-serialized-item) — Update a serialized item
- [`PUT /api/v1/items/{itemId}/accessories`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-accessories-of-an-item) — Update the accessories of an item
- [`PUT /api/v1/items/{itemId}/alternatives`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-the-alternatives-of-an-item) — Update the alternatives of an item
- [`PATCH /api/v1/items/{itemId}/variants/{variantId}`](https://docs.filmo.io/rest-api/endpoint-reference/items/update-a-variant-of-an-item) — Update a variant of an item

### kits:read

Read kits, the named groups of items that go out together.

- [`GET /api/v1/kits`](https://docs.filmo.io/rest-api/endpoint-reference/kits/list-kits) — List kits
- [`GET /api/v1/kits/{kitId}`](https://docs.filmo.io/rest-api/endpoint-reference/kits/get-a-kit) — Get a kit

### kits:write

Create and change kits.

- [`POST /api/v1/kits`](https://docs.filmo.io/rest-api/endpoint-reference/kits/create-a-kit) — Create a kit
- [`PATCH /api/v1/kits/{kitId}`](https://docs.filmo.io/rest-api/endpoint-reference/kits/update-a-kit) — Update a kit

### notes:read

Read the notes attached to an entity of the account.

- [`GET /api/v1/notes`](https://docs.filmo.io/rest-api/endpoint-reference/notes/list-the-notes-of-an-entity) — List the notes of an entity

### notes:write

Write notes on entities of the account.

- [`POST /api/v1/notes`](https://docs.filmo.io/rest-api/endpoint-reference/notes/write-a-note-on-an-entity) — Write a note on an entity

### orders:read

Read rental orders and their lines.

- [`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders) — List orders
- [`GET /api/v1/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/orders/get-an-order) — Get an order
- [`GET /api/v1/orders/{orderId}/lines`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-the-lines-of-an-order) — List the lines of an order

### orders:write

Create and change orders, and run actions on them (reserve, unreserve, cancel, archive, return line items). Cancelling an order cannot be undone through the API. Returning line items puts material back into stock, so a retry without the same `Idempotency-Key` returns it twice. Send your own key. Reserving deducts stock and creates the delivery and return tasks.

- [`POST /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/create-an-order) — Create an order
- [`PATCH /api/v1/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/orders/update-the-header-of-an-order) — Update the header of an order
- [`POST /api/v1/orders/{orderId}/cancel`](https://docs.filmo.io/rest-api/endpoint-reference/orders/cancel-an-order) — Cancel an order
- [`PUT /api/v1/orders/{orderId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/orders/archive-or-restore-an-order) — Archive or restore an order
- [`POST /api/v1/orders/line-items/returns`](https://docs.filmo.io/rest-api/endpoint-reference/orders/return-order-lines) — Return order lines
- [`POST /api/v1/orders/{orderId}/reserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/reserve-an-order) — Reserve an order
- [`POST /api/v1/orders/{orderId}/unreserve`](https://docs.filmo.io/rest-api/endpoint-reference/orders/unreserve-an-order) — Unreserve an order

### planner:read

Read the staff and fleet services of a date window, with who covers them, and the resources that can be assigned.

- [`GET /api/v1/planner/services`](https://docs.filmo.io/rest-api/endpoint-reference/planner/list-the-services-to-cover) — List the services to cover
- [`GET /api/v1/planner/resources`](https://docs.filmo.io/rest-api/endpoint-reference/planner/list-the-assignable-resources) — List the assignable resources

### planner:write

Assign resources to planner services and remove them.

- [`POST /api/v1/planner/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/planner/assign-a-resource-to-a-service) — Assign a resource to a service
- [`POST /api/v1/planner/assignments/remove`](https://docs.filmo.io/rest-api/endpoint-reference/planner/remove-a-resource-from-a-service) — Remove a resource from a service

### projects:read

Read projects and the catalog of project types.

- [`GET /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/list-projects) — List projects
- [`GET /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/get-a-project) — Get a project
- [`GET /api/v1/project-types`](https://docs.filmo.io/rest-api/endpoint-reference/projects/list-project-types) — List project types

### projects:write

Create, change and archive projects, and link or unlink orders to them.

- [`POST /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/create-a-project) — Create a project
- [`PUT /api/v1/projects/{projectId}/archive`](https://docs.filmo.io/rest-api/endpoint-reference/projects/archive-or-restore-a-project) — Archive or restore a project
- [`PATCH /api/v1/projects/{projectId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/update-a-project) — Update a project
- [`POST /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/link-an-order-to-a-project) — Link an order to a project
- [`DELETE /api/v1/projects/{projectId}/orders/{orderId}`](https://docs.filmo.io/rest-api/endpoint-reference/projects/unlink-an-order-from-a-project) — Unlink an order from a project

### purchase-orders:read

Read purchase orders to suppliers.

- [`GET /api/v1/purchase-orders`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/list-purchase-orders) — List purchase orders
- [`GET /api/v1/purchase-orders/{purchaseOrderId}`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/get-a-purchase-order) — Get a purchase order

### purchase-orders:write

Change, approve and receive purchase orders. Receiving a purchase order registers new inventory, so a retry without the same `Idempotency-Key` duplicates the stock. Send your own key.

- [`PATCH /api/v1/purchase-orders/{purchaseOrderId}`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/update-a-purchase-order) — Update a purchase order
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/approve`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/approve-a-purchase-order) — Approve a purchase order
- [`POST /api/v1/purchase-orders/{purchaseOrderId}/receive`](https://docs.filmo.io/rest-api/endpoint-reference/purchase-orders/receive-material-from-a-purchase-order) — Receive material from a purchase order

### quotes:read

Read quotes (active version) and their lines.

- [`GET /api/v1/quotes`](https://docs.filmo.io/rest-api/endpoint-reference/quotes/list-quotes) — List quotes
- [`GET /api/v1/quotes/{quoteId}`](https://docs.filmo.io/rest-api/endpoint-reference/quotes/get-a-quote) — Get a quote
- [`GET /api/v1/quotes/{quoteId}/lines`](https://docs.filmo.io/rest-api/endpoint-reference/quotes/list-the-lines-of-a-quote) — List the lines of a quote

### quotes:write

Change the commercial status of quotes. Confirming a version of a quote moves every other version of it to `superseded`.

- [`PATCH /api/v1/quotes/{quoteId}/status`](https://docs.filmo.io/rest-api/endpoint-reference/quotes/change-the-commercial-status-of-a-quote) — Change the commercial status of a quote

### repair-tickets:read

Read repair tickets.

- [`GET /api/v1/repair-tickets`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/list-repair-tickets) — List repair tickets
- [`GET /api/v1/repair-tickets/{ticketId}`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/get-a-repair-ticket) — Get a repair ticket

### repair-tickets:write

Create and change repair tickets, including their lines. Sending `lines` when updating a ticket replaces the whole set of lines: send all of them or none.

- [`POST /api/v1/repair-tickets`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/create-a-repair-ticket) — Create a repair ticket
- [`PATCH /api/v1/repair-tickets/{ticketId}`](https://docs.filmo.io/rest-api/endpoint-reference/repair-tickets/update-a-repair-ticket) — Update a repair ticket

### schedule:read

Read the consolidated schedule of a date range: projects, orders, tasks, internal services and order services.

- [`GET /api/v1/schedule`](https://docs.filmo.io/rest-api/endpoint-reference/schedule/get-the-schedule-for-a-range) — Get the schedule for a range

### services:read

Read services, the sellable lines that do not come from inventory.

- [`GET /api/v1/services`](https://docs.filmo.io/rest-api/endpoint-reference/services/list-services) — List services
- [`GET /api/v1/services/{serviceId}`](https://docs.filmo.io/rest-api/endpoint-reference/services/get-a-service) — Get a service

### services:write

Create and change services, pricing included.

- [`POST /api/v1/services`](https://docs.filmo.io/rest-api/endpoint-reference/services/create-a-service) — Create a service
- [`PATCH /api/v1/services/{serviceId}`](https://docs.filmo.io/rest-api/endpoint-reference/services/update-a-service) — Update a service

### spaces:read

Read warehouses and rentable spaces.

- [`GET /api/v1/spaces`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/list-warehouses-and-spaces) — List warehouses and spaces
- [`GET /api/v1/spaces/{spaceId}`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/get-a-warehouse-or-space) — Get a warehouse or space

### spaces:write

Change and delete spaces, and replace their amenities and equipment and set their pricing. Deleting a space also deletes its notes, files, tasks, images and declared unavailabilities, and cannot be undone.

- [`PATCH /api/v1/spaces/{spaceId}`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/update-a-warehouse-or-space) — Update a warehouse or space
- [`DELETE /api/v1/spaces/{spaceId}`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/delete-a-space) — Delete a space
- [`PUT /api/v1/spaces/{spaceId}/amenities`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/replace-the-amenities-and-equipment) — Replace the amenities and equipment
- [`PATCH /api/v1/spaces/{spaceId}/pricing`](https://docs.filmo.io/rest-api/endpoint-reference/spaces/update-the-pricing-of-a-space) — Update the pricing of a space

### staff:read

Read staff members and check staff availability in a date range.

- [`GET /api/v1/staff`](https://docs.filmo.io/rest-api/endpoint-reference/staff/list-staff) — List staff
- [`GET /api/v1/staff/{staffId}`](https://docs.filmo.io/rest-api/endpoint-reference/staff/get-a-staff-member) — Get a staff member
- [`POST /api/v1/staff/availability`](https://docs.filmo.io/rest-api/endpoint-reference/staff/check-staff-availability) — Check staff availability

### staff:write

Create, change and delete staff members (organizational data only). Deleting a staff member cannot be undone.

- [`POST /api/v1/staff`](https://docs.filmo.io/rest-api/endpoint-reference/staff/create-a-staff-member) — Create a staff member
- [`PATCH /api/v1/staff/{staffId}`](https://docs.filmo.io/rest-api/endpoint-reference/staff/update-a-staff-member) — Update a staff member
- [`DELETE /api/v1/staff/{staffId}`](https://docs.filmo.io/rest-api/endpoint-reference/staff/delete-a-staff-member) — Delete a staff member

### subrents:read

Read subrents, the equipment rented from other companies to cover a job.

- [`GET /api/v1/subrents`](https://docs.filmo.io/rest-api/endpoint-reference/subrents/list-subrents) — List subrents
- [`GET /api/v1/subrents/{subrentId}`](https://docs.filmo.io/rest-api/endpoint-reference/subrents/get-a-subrent) — Get a subrent

### subrents:write

Change subrents.

- [`PATCH /api/v1/subrents/{subrentId}`](https://docs.filmo.io/rest-api/endpoint-reference/subrents/update-a-subrent) — Update a subrent

### supplier-invoices:read

Read invoices received from suppliers.

- [`GET /api/v1/supplier-invoices`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/list-supplier-invoices) — List supplier invoices
- [`GET /api/v1/supplier-invoices/{supplierInvoiceId}`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/get-a-supplier-invoice) — Get a supplier invoice

### supplier-invoices:write

Validate and void invoices received from suppliers. Validating a supplier invoice numbers it and locks it, and voiding keeps its number. Both need the purchases add-on.

- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/validate`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/validate-a-supplier-invoice) — Validate a supplier invoice
- [`POST /api/v1/supplier-invoices/{supplierInvoiceId}/void`](https://docs.filmo.io/rest-api/endpoint-reference/supplier-invoices/void-a-supplier-invoice) — Void a supplier invoice

### tags:read

Read the tag vocabulary of the account.

- [`GET /api/v1/tags`](https://docs.filmo.io/rest-api/endpoint-reference/tags/list-tags) — List tags

### tags:write

Create and delete tags, and assign or remove them on entities. Deleting a tag removes it from every entity that carried it, and cannot be undone.

- [`POST /api/v1/tags`](https://docs.filmo.io/rest-api/endpoint-reference/tags/create-a-tag) — Create a tag
- [`DELETE /api/v1/tags/{tagId}`](https://docs.filmo.io/rest-api/endpoint-reference/tags/delete-a-tag) — Delete a tag
- [`POST /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/tags/assign-a-tag-to-an-entity) — Assign a tag to an entity
- [`DELETE /api/v1/tags/{tagId}/assignments`](https://docs.filmo.io/rest-api/endpoint-reference/tags/remove-a-tag-from-an-entity) — Remove a tag from an entity

### tasks:read

Read tasks, schedule events and task types.

- [`GET /api/v1/tasks`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/list-tasks) — List tasks
- [`GET /api/v1/tasks/{taskId}`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/get-a-task) — Get a task
- [`GET /api/v1/task-types`](https://docs.filmo.io/rest-api/endpoint-reference/task-types/list-task-types) — List task types

### tasks:write

Create, change and delete tasks. Deleting a task cannot be undone.

- [`POST /api/v1/tasks`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/create-a-task) — Create a task
- [`PATCH /api/v1/tasks/{taskId}`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/update-a-task) — Update a task
- [`DELETE /api/v1/tasks/{taskId}`](https://docs.filmo.io/rest-api/endpoint-reference/tasks/delete-a-task) — Delete a task

### treasury:read

Read treasury accounts, payments and payment methods, and the payments of an invoice.

- [`GET /api/v1/invoices/{invoiceId}/payments`](https://docs.filmo.io/rest-api/endpoint-reference/invoices/list-the-payments-of-an-invoice) — List the payments of an invoice
- [`GET /api/v1/treasury/accounts`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/list-treasury-accounts) — List treasury accounts
- [`GET /api/v1/treasury/accounts/{accountId}`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/get-a-treasury-account) — Get a treasury account
- [`GET /api/v1/treasury/payments`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/list-treasury-payments) — List treasury payments
- [`GET /api/v1/treasury/payments/{paymentId}`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/get-a-payment) — Get a payment
- [`GET /api/v1/payment-methods`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/list-payment-methods) — List payment methods

### treasury:write

Record, change and link payments. Recording a payment writes to your accounts: a retry without the same `Idempotency-Key` records it twice. Send your own key.

- [`POST /api/v1/treasury/payments`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/record-an-incoming-or-outgoing-payment) — Record an incoming or outgoing payment
- [`PATCH /api/v1/treasury/payments/{paymentId}`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/update-a-payment) — Update a payment
- [`POST /api/v1/treasury/payments/{paymentId}/links`](https://docs.filmo.io/rest-api/endpoint-reference/treasury/link-a-payment-to-a-document) — Link a payment to a document

### users:read

Read the people with access to the account, with their role and access status. Only administrators can call it.

- [`GET /api/v1/users`](https://docs.filmo.io/rest-api/endpoint-reference/users/list-users) — List users

### vehicles:read

Read fleet vehicles and check fleet availability in a date range.

- [`GET /api/v1/vehicles`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/list-vehicles) — List vehicles
- [`GET /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/get-a-vehicle) — Get a vehicle
- [`POST /api/v1/vehicles/availability`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/check-fleet-availability) — Check fleet availability

### vehicles:write

Create, change and delete vehicles. Deleting a vehicle cannot be undone.

- [`POST /api/v1/vehicles`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/create-a-vehicle) — Create a vehicle
- [`PATCH /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/update-a-vehicle) — Update a vehicle
- [`DELETE /api/v1/vehicles/{vehicleId}`](https://docs.filmo.io/rest-api/endpoint-reference/vehicles/delete-a-vehicle) — Delete a vehicle

### workflows:read

List the workflows of the account and whether each one is active. Definitions are not published.

- [`GET /api/v1/workflows`](https://docs.filmo.io/rest-api/endpoint-reference/workflows/list-workflows) — List workflows

### workflows:run

Start a run of a workflow, as the Run button does in the app. The run executes in the background and does whatever the workflow's steps say, so it can change data in Filmo and may have effects outside Filmo. This is the broadest permission in the contract: a run does whatever the workflow's steps say. Grant it only to integrations that need to start workflows, and send your own `Idempotency-Key`.

- [`POST /api/v1/workflows/{workflowId}/runs`](https://docs.filmo.io/rest-api/endpoint-reference/workflows/run-a-workflow) — Run a workflow

---

Canonical URL: https://docs.filmo.io/rest-api/guides/scopes  
Last updated: 2026-10-25