Archiving and deleting

Filmo has several ways to take a record out of use, and they are not interchangeable. Some can be undone and some cannot; check this page before you call a destructive operation.

Each operation that removes or retires a record falls into one of five groups. The table below is generated from the spec and also marks which operations the spec calls irreversible or final.

Operation	Method	Note
`DELETE /api/v1/contacts/{contactId}`	DELETE	Not reversible
`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`	DELETE	Not reversible
`DELETE /api/v1/contacts/{contactId}/related-contacts/{relatedContactId}`	DELETE	—
`DELETE /api/v1/items/{itemId}`	DELETE	Not reversible
`PUT /api/v1/projects/{projectId}/archive`	PUT	—
`DELETE /api/v1/spaces/{spaceId}`	DELETE	Not reversible
`DELETE /api/v1/vehicles/{vehicleId}`	DELETE	Not reversible
`DELETE /api/v1/staff/{staffId}`	DELETE	Not reversible
`DELETE /api/v1/tags/{tagId}`	DELETE	Not reversible
`DELETE /api/v1/tags/{tagId}/assignments`	DELETE	—
`DELETE /api/v1/availability/unavailabilities/{unavailabilityId}`	DELETE	Not reversible
`DELETE /api/v1/tasks/{taskId}`	DELETE	Not reversible
`POST /api/v1/orders/{orderId}/cancel`	POST	Not reversible
`PUT /api/v1/orders/{orderId}/archive`	PUT	—
`POST /api/v1/orders/{orderId}/unreserve`	POST	—
`DELETE /api/v1/projects/{projectId}/orders/{orderId}`	DELETE	—
`POST /api/v1/invoices/{invoiceId}/void`	POST	Not reversible
`POST /api/v1/credit-notes/{creditNoteId}/void`	POST	Not reversible
`POST /api/v1/contracts/{contractId}/void`	POST	Not reversible
`POST /api/v1/contracts/{contractId}/cancel`	POST	Not reversible
`POST /api/v1/supplier-invoices/{supplierInvoiceId}/void`	POST	Not reversible

What each action means

Action	What it does	Can it be undone?
Delete	Removes the record and what hangs from it physically. Its GET answers 404 afterwards, and the API keeps no tombstone, so a deleted record leaves no trace in lists.	No for the deletes below. Nothing is kept for you to restore. There is no delete for orders and projects in v1: you cancel, archive or unlink them.
Archive	Takes an order or a project out of the active views. It deletes nothing and touches no stock, lines, documents or team.	Yes, it only changes visibility. An order is restored with `PUT /api/v1/orders/{orderId}/archive` and `archived: false`.
Void	Moves a validated document to `voided`. It keeps its number, so the numbering stays continuous.	The spec describes no way back. The reason you give is kept.
Cancel	Ends an order or a contract's signature path.	No for an order. A cancelled contract can no longer be signed.
Unlink	Removes only a link between two records. It deletes neither of them.	Yes: the link is made again with the matching POST.

Operations the spec calls irreversible or final

These descriptions say so explicitly, or call the result locked or terminal. Treat each as final.

Operation	What the spec says
`DELETE /api/v1/contacts/{contactId}`	Described as not reversible. Also deletes its relationships, notes, files, tasks and payment methods. Archive a contact with `status: archived` instead.
`DELETE /api/v1/contacts/{contactId}/addresses/{addressId}`	Described as not reversible. Refused with `address_in_use` while an order uses the address.
`DELETE /api/v1/items/{itemId}`	Described as not reversible.
`DELETE /api/v1/spaces/{spaceId}`	Described as not reversible.
`DELETE /api/v1/vehicles/{vehicleId}`	Described as not reversible.
`DELETE /api/v1/staff/{staffId}`	Described as not reversible.
`DELETE /api/v1/tags/{tagId}`	Described as not reversible. Removes the tag from every record that carried it.
`DELETE /api/v1/availability/unavailabilities/{unavailabilityId}`	Described as not reversible.
`DELETE /api/v1/tasks/{taskId}`	Described as not reversible. Removes its staff assignments and its mirror on the external calendar.
`POST /api/v1/orders/{orderId}/cancel`	Described as not reversible from the API. To have the order back you duplicate it; cancelling also frees the stock and cancels the logistics tasks.
`POST /api/v1/invoices/{invoiceId}/validate`	Locks the invoice as immutable. A validated invoice is voided, not edited.
`POST /api/v1/credit-notes/{creditNoteId}/validate`	Locks the credit note as immutable.
`POST /api/v1/contracts/{contractId}/validate`	Locks the contract as immutable.
`POST /api/v1/supplier-invoices/{supplierInvoiceId}/validate`	Locks the received invoice as immutable.
`POST /api/v1/contracts/{contractId}/cancel`	The spec calls `cancelled` terminal. A signed contract cannot be cancelled: void it instead.

POST /api/v1/orders/{orderId}/unreserve is not on this list. It returns the order to draft and the order can be reserved again, but it deletes the delivery and return tasks the reservation created, and those are not recreated by hand.

Before you call any of these from an agent or a script, read the operation's page and consider sending your own idempotency key and, on the operations that accept If-Match (all of the above except DELETE /api/v1/tags/{tagId} and DELETE /api/v1/availability/unavailabilities/{unavailabilityId}), the ETag you read, so a stale view cannot trigger the action.

Archived is not deleted

PUT /api/v1/orders/{orderId}/archive archives or restores an order: the body is { "archived": true } or { "archived": false }. It is a PUT that sets a value, there is no toggle, and it responds 204 with no body. The spec says that repeating the call does nothing new, but do not rely on updatedAt staying still: a repeat can still refresh it, so the order can show up again in an incremental read.

Only a draft or cancelled order can be archived. Any other status responds 409 conflict, naming the status.
An archived order is no longer visible to the API: its GET responds 404, exactly as for an order that does not exist, it is left out of lists, and there is no includeArchived option.
To restore an order, call PUT /api/v1/orders/{orderId}/archive with archived: false and the id you kept: while the order is archived you cannot list or read it. After the 204 it is read again with its GET.
OrderDto.status lists archived as a possible value, but Filmo never produces it: archiving does not change the status.

Projects behave differently. PUT /api/v1/projects/{projectId}/archive also accepts only a draft or cancelled project, but an archived project is only hidden from the list: archived set to true lists only the archived ones, and its GET keeps answering with archived: true.

A 404 does not mean deleted

During a sync, a 404 on an order can mean it was deleted or that it was archived. Do not delete the record on your side on a 404 alone. Follow the reconciliation steps in syncing data.

Deleting a record that is in use

Some deletes refuse to run when something still uses the record. contact_in_use and address_in_use return 409 and delete nothing; errors[] has one entry per type of record that uses it, with a count. Move or remove those records first, or archive the contact instead.

Guides
Syncing data
Filmo v1 does not send webhooks, so you keep another system in step by polling: read what changed in half-open time windows, and run a separate sweep to find what was deleted. Do not follow the pagination cursor to decide what changed or what disappeared.
Further reading
Capabilities and limits of v1
The API covers most day-to-day work on orders, contacts, items, invoices and the schedule, and leaves a short list of things to the app. Check it here before you design an integration around a feature.
Guides
Idempotency and safe retries
Send an Idempotency-Key header with every write and reuse the same value when you retry that operation: Filmo returns the stored result of the first attempt instead of writing twice.
Guides
Concurrency and optimistic locking
Every detail read returns an ETag. Send it back in the If-Match header of a write and Filmo rejects the write with 412 if the record changed since you read it, so two integrations cannot silently overwrite each other.

Was this page helpful?

What each action means

Operations the spec calls irreversible or final

Archived is not deleted

Deleting a record that is in use

Related pages

Syncing data

Capabilities and limits of v1

Idempotency and safe retries

Concurrency and optimistic locking