Documents

Create a document

Changed on

Create a new document record and receive a pre-signed URL for uploading the file.

Workflow

  1. Supply fileName, contentType and 1–100 validated attachments. There is no standalone-file create or top-level type.
  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; a normal TMS refresh then shows the attachments.

Exclusive CARRIER/CUSTOMER/VENDOR/LOCATION/PAYMENT/BILL_PAYMENT uploads require exactly one mapping. ORDER/LOAD/SERVICE mappings may share a file only within one shipment. Profiles mixed with shipment owners, two exclusive owners, and different shipments return DOCUMENT_ATTACHMENT_COMBINATION_INVALID before any writes. SHIPMENT and QUOTE are not upload owners. Duplicate resolved targets are rejected. A load selector is a carrier assignment UUID; omitting it requires exactly one eligible assignment.

201 means the file and every mapping persisted, not that bytes arrived. Download URL is null while pending. Manual load/service rate-cons get their own UPLOAD signing request, recorded SIGNED at creation as in a TMS upload. Reuse the same Idempotency-Key and complete request for retries within 14 days, including partial failures. Keep the request unchanged when retrying. Individual writes use the standard mutation idempotency rules. Requests without a key cannot promise safe automatic retries after an unknown result.

Upload Instructions

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

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 5 minutes; GET the file again to refresh an expired URL
  • Use the exact contentType specified in the request
  • Maximum file size: 100MB
post/documents

Request

  • Base URL: https://api.mvmnt.io/v1
  • URL: https://api.mvmnt.io/v1/documents
  • Auth: HTTP bearer

Request body

keystring

Optional client-defined key for external reference

fileNamestring required

File name (including extension)

contentTypestring required

MIME content type of the file

fileSizeinteger

File size in bytes (optional, for validation)

tagsobject

Optional key-value tags

Example request

{
  "key": "doc-inv-2025-001",
  "fileName": "invoice-2025-001.pdf",
  "contentType": "application/pdf",
  "fileSize": 102400,
  "tags": {
    "invoiceNumber": "INV-2025-001"
  }
}

Response

Document created successfully

idstring uuid required

Unique identifier for the document

keystring nullable

Client-defined key for external reference

fileNamestring required

Original file name

extensionstring

File extension (without dot)

contentTypestring required

MIME content type

fileSizeinteger 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
uploadUrlstring uri nullable

Pre-signed URL for uploading the file. Present while status is PENDING_UPLOAD. Read the file again to refresh an expired URL. Expires after 5 minutes.

downloadUrlstring uri nullable

Pre-signed URL for downloading the file. Present when document status is UPLOADED. Expires after 1 hour.

tagsobject nullable

Arbitrary key-value tags for the document

createdAtstring date-time required

When the document was created

updatedAtstring date-time nullable

When the document was last updated

type'INVOICE' | 'BILL_OF_LADING' | 'RATE_CON' | 'PROOF_OF_DELIVERY' | 'CERTIFICATE_OF_INSURANCE' | 'W9' | 'CARRIER_INVOICE' | 'CHECK' | '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' | 'REMITTANCE_ADVICE' | '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.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "doc-inv-2025-001",
  "fileName": "invoice-2025-001.pdf",
  "extension": "pdf",
  "contentType": "application/pdf",
  "fileSize": 102400,
  "uploadUrl": "https://s3.amazonaws.com/bucket/key?signature=...",
  "downloadUrl": "https://s3.amazonaws.com/bucket/key?signature=...",
  "tags": {
    "invoiceNumber": "INV-2025-001",
    "customerPO": "PO-12345"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:35:00Z"
}

Changes

  • ddd3bbf81731Revision changes
    • breaking

      added the new required request property

    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added subschema #2 to the response body allOf list for the response status

    • info

      added the non-success response with the status

  • 2cd6ecfbeb82Revision changes
    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • info

      added subschema #2 to the response body allOf list for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      media type application/json was changed to a more specific media type application/problem+json for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status