# Documents

Document management operations.
Documents are files (PDFs, images) that can be attached to orders, loads, or services.


## Filter documents

 - [POST /documents/filter](https://docs.mvmnt.io/apis/openapi/documents/filterdocuments.md): Search for documents using filter criteria.

## Usage

Documents are typically associated with other entities (orders, loads, services).
Use filters to find documents by type, status, or date range.

## Example Filters

- Find all invoices: { "filter": { "type": { "equalTo": "INVOICE" } } }
- Find uploaded documents: { "filter": { "status": { "equalTo": "UPLOADED" } } }
- Find documents created today: { "filter": { "createdAt": { "greaterThanOrEqualTo": "2025-01-15T00:00:00Z" } } }

## Create a document

 - [POST /documents](https://docs.mvmnt.io/apis/openapi/documents/createdocument.md): Create a new document record and receive a pre-signed URL for uploading the file.

## Workflow

1. Call this endpoint with document metadata (type, fileName, contentType)
2. Receive the created document with an uploadUrl
3. Upload the file directly to S3 using the uploadUrl (PUT request)
4. Document status changes from PENDING_UPLOAD to UPLOADED automatically

## Upload Instructions

The uploadUrl is a pre-signed S3 URL. Upload your file with:

bash
curl -X PUT -H "Content-Type: application/pdf" \
  --data-binary @your-file.pdf \
  "https://s3.amazonaws.com/bucket/key?signature=..."


Important:
- The uploadUrl expires after 15 minutes
- Use the exact contentType specified in the request
- Maximum file size: 100MB

## Get a document

 - [GET /documents/{id}](https://docs.mvmnt.io/apis/openapi/documents/getdocument.md): Retrieve a document by ID or key.

Returns the document metadata including a fresh downloadUrl if the file is uploaded.

Note: The downloadUrl is a pre-signed S3 URL that expires after 1 hour.
Each GET request generates a fresh URL.

## Update a document

 - [PATCH /documents/{id}](https://docs.mvmnt.io/apis/openapi/documents/updatedocument.md): Update document metadata.

Note: File content cannot be changed after upload.
To replace a file, create a new document.

## Delete a document

 - [DELETE /documents/{id}](https://docs.mvmnt.io/apis/openapi/documents/deletedocument.md): Soft delete a document.

The document record is marked as deleted but not permanently removed.
Associated files in S3 may be cleaned up asynchronously.