---
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' | '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
  - `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' | '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
  - `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/c44e5e7a4256/schema)