---
title: "Create a document"
method: POST
path: "/documents"
tags: ["Documents"]
---

# Create a document

`POST /documents`

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

## Request body

- DocumentInput
  - `key` string — Optional client-defined key for external reference
  - `type` 'INVOICE' | 'BILL_OF_LADING' | 'RATE_CON' | 'PROOF_OF_DELIVERY' | 'CERTIFICATE_OF_INSURANCE' | 'W9' | 'CARRIER_INVOICE' | 'LUMPER_RECEIPT' | 'DETENTION' | 'DELIVERY_ORDER' | 'LOAD_TENDER' | 'HOUSE_AIRWAY_BILL' | 'MASTER_AIRWAY_BILL' | 'QUOTE' | 'AIR_CARGO_MANIFEST' | 'AIR_CHUTE' | 'AIR_FREIGHT_DEPARTURE_CARTAGE_ADVICE_WITH_RECEIPT' | 'AUTHORITY' | 'AUTHORITY_TO_MAKE_ENTRY' | 'BROKER_CARRIER_AGREEMENT' | 'COI_AUTO' | 'COI_BIPD' | 'COI_CARGO' | 'COMMERCIAL_DRIVERS_LICENSE' | 'COMMERCIAL_INVOICE' | 'CUSTOMER_ACCESSORIAL_SCHEDULE' | 'CUSTOMER_AGREEMENT' | 'CUSTOMER_AWARDED_BIDS' | 'CUSTOMER_AWARDED_RATES_LANES' | 'CUSTOMER_CREDIT_REPORT' | 'DELIVERY_ALERT' | 'FACTOR_NOTICE_OF_ASSIGNMENT' | 'FREIGHT_BILL' | 'FUEL_RECEIPT' | 'GBL' | 'HOUSE_AIRWAY_BILL_LABEL' | 'HOUSE_AIRWAY_BILL_LABEL_MULTI' | 'IAC_CERTIFICATION' | 'INTERNATIONAL_HOUSE_AIRWAY_BILL' | 'INTERNATIONAL_MASTER_AIRWAY_BILL' | 'LOAD_SUMMARY' | 'LOG' | 'LOGO' | 'LOGO_DOC' | 'LOGO_RECTANGLE' | 'PACKING_LIST' | 'PHOTOGRAPH' | 'PROOF_OF_PERFORMANCE' | 'REEFER_KEYPAD' | 'ROUTING_ALERT' | 'SCALE_RECEIPT' | 'SEAL' | 'SHIPPING_LABEL' | 'SIDE_OF_TRUCK' | 'SIGNED_CARRIER_AGREEMENT' | 'TRIP_SHEET' | 'OTHER', required — Type of document. Common types: - `INVOICE`: Customer invoice - `BILL_OF_LADING`: Bill of lading document - `RATE_CON`: Rate confirmation - `PROOF_OF_DELIVERY`: Proof of delivery (POD) - `CERTIFICATE_OF_INSURANCE`: Certificate of insurance (COI) - `W9`: W-9 tax form - `CARRIER_INVOICE`: Carrier invoice/bill - `LUMPER_RECEIPT`: Lumper receipt - `DETENTION`: Detention documentation - `DELIVERY_ORDER`: Delivery order - `LOAD_TENDER`: Load tender - `HOUSE_AIRWAY_BILL`: House airway bill (HAWB) - `MASTER_AIRWAY_BILL`: Master airway bill (MAWB) - `QUOTE`: Quote document - `OTHER`: Other document type The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets). Values outside this list are rejected with 400. Documents created internally with other types are returned as `OTHER`.
  - `fileName` string, required — File name (including extension)
  - `contentType` string, required — MIME content type of the file
  - `fileSize` integer — File size in bytes (optional, for validation)
  - `tags` object — Optional key-value tags

## Response `201`

Document created successfully

- Document
  - `id` string, uuid, required — Unique identifier for the document
  - `key` string, nullable — Client-defined key for external reference
  - `type` 'INVOICE' | 'BILL_OF_LADING' | 'RATE_CON' | 'PROOF_OF_DELIVERY' | 'CERTIFICATE_OF_INSURANCE' | 'W9' | 'CARRIER_INVOICE' | 'LUMPER_RECEIPT' | 'DETENTION' | 'DELIVERY_ORDER' | 'LOAD_TENDER' | 'HOUSE_AIRWAY_BILL' | 'MASTER_AIRWAY_BILL' | 'QUOTE' | 'AIR_CARGO_MANIFEST' | 'AIR_CHUTE' | 'AIR_FREIGHT_DEPARTURE_CARTAGE_ADVICE_WITH_RECEIPT' | 'AUTHORITY' | 'AUTHORITY_TO_MAKE_ENTRY' | 'BROKER_CARRIER_AGREEMENT' | 'COI_AUTO' | 'COI_BIPD' | 'COI_CARGO' | 'COMMERCIAL_DRIVERS_LICENSE' | 'COMMERCIAL_INVOICE' | 'CUSTOMER_ACCESSORIAL_SCHEDULE' | 'CUSTOMER_AGREEMENT' | 'CUSTOMER_AWARDED_BIDS' | 'CUSTOMER_AWARDED_RATES_LANES' | 'CUSTOMER_CREDIT_REPORT' | 'DELIVERY_ALERT' | 'FACTOR_NOTICE_OF_ASSIGNMENT' | 'FREIGHT_BILL' | 'FUEL_RECEIPT' | 'GBL' | 'HOUSE_AIRWAY_BILL_LABEL' | 'HOUSE_AIRWAY_BILL_LABEL_MULTI' | 'IAC_CERTIFICATION' | 'INTERNATIONAL_HOUSE_AIRWAY_BILL' | 'INTERNATIONAL_MASTER_AIRWAY_BILL' | 'LOAD_SUMMARY' | 'LOG' | 'LOGO' | 'LOGO_DOC' | 'LOGO_RECTANGLE' | 'PACKING_LIST' | 'PHOTOGRAPH' | 'PROOF_OF_PERFORMANCE' | 'REEFER_KEYPAD' | 'ROUTING_ALERT' | 'SCALE_RECEIPT' | 'SEAL' | 'SHIPPING_LABEL' | 'SIDE_OF_TRUCK' | 'SIGNED_CARRIER_AGREEMENT' | 'TRIP_SHEET' | 'OTHER', required — Type of document. Common types: - `INVOICE`: Customer invoice - `BILL_OF_LADING`: Bill of lading document - `RATE_CON`: Rate confirmation - `PROOF_OF_DELIVERY`: Proof of delivery (POD) - `CERTIFICATE_OF_INSURANCE`: Certificate of insurance (COI) - `W9`: W-9 tax form - `CARRIER_INVOICE`: Carrier invoice/bill - `LUMPER_RECEIPT`: Lumper receipt - `DETENTION`: Detention documentation - `DELIVERY_ORDER`: Delivery order - `LOAD_TENDER`: Load tender - `HOUSE_AIRWAY_BILL`: House airway bill (HAWB) - `MASTER_AIRWAY_BILL`: Master airway bill (MAWB) - `QUOTE`: Quote document - `OTHER`: Other document type The remaining values mirror the document types available in the MVMNT TMS UI (carrier compliance, air freight, customer agreements, receipts, alerts, and branding assets). Values outside this list are rejected with 400. Documents created internally with other types are returned as `OTHER`.
  - `fileName` string, required — Original file name
  - `extension` string — File extension (without dot)
  - `contentType` string, required — MIME content type
  - `fileSize` integer, nullable — File size in bytes
  - `status` 'PENDING_UPLOAD' | 'UPLOADED', required — Upload status of the document. - `PENDING_UPLOAD`: Document record created, file not yet uploaded - `UPLOADED`: File has been uploaded to storage
  - `uploadUrl` string, uri, nullable — Pre-signed URL for uploading the file. Only present immediately after document creation. Expires after 15 minutes.
  - `downloadUrl` string, uri, nullable — Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.
  - `tags` object, nullable — Arbitrary key-value tags for the document
  - `createdAt` string, date-time, required — When the document was created
  - `updatedAt` string, date-time, nullable — When the document was last updated

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `422` — Validation error - invalid field values

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/revisions/53b310bb74a0/schema)