Documents

Update a document

Changed on

Update shared fileName/key/tags. Type and attachToInvoice target the sole supported attachment. Zero mappings returns DOCUMENT_RELATIONSHIP_NOT_FOUND for relationship fields; multiple mappings returns DOCUMENT_RELATIONSHIP_AMBIGUOUS before any writes. Use /documents/{id}/attachments/{attachmentId} for shared files. Each request resolves the current file and relationship. Use an attachment ID to select a specific mapping.

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

patch/documents/{id}

Request

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

Path parameters

idstring required

Resource ID (UUID) or client key

Query parameters

by'id' | 'key'

Specify lookup type for faster retrieval. If omitted, defaults to looking up by ID first, then falls back to client key if not found. Use by=key when you know you're providing a client key for best performance.

Request body

keystring nullable

Update client-defined key

typestring

Category of the sole supported attachment. Zero mappings returns 404; multiple mappings returns 409 before any writes. Use the attachment route for shared files.

attachToInvoiceboolean nullable

Stored relationship preference. True selects an eligible file by default; false excludes it. Null inherits current invoice/customer defaults. Create omission stores null; PATCH omission leaves it unchanged. Supported only by ORDER, LOAD and SERVICE. True is rejected for ineligible categories or .xlsx/.xls/.doc/.docx/.csv display names. Does not generate, send or modify an existing invoice PDF.

fileNamestring

Update file name

tagsobject nullable

Update or clear tags (null to clear)

Response

Document updated 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

      removed the enum value AIR_CARGO_MANIFEST of the request property

    • breaking

      removed the enum value AIR_CHUTE of the request property

    • breaking

      removed the enum value AIR_FREIGHT_DEPARTURE_CARTAGE_ADVICE_WITH_RECEIPT of the request property

    • breaking

      removed the enum value AUTHORITY of the request property

    • breaking

      removed the enum value AUTHORITY_TO_MAKE_ENTRY of the request property

    • breaking

      removed the enum value BILL_OF_LADING of the request property

    • breaking

      removed the enum value BROKER_CARRIER_AGREEMENT of the request property

    • breaking

      removed the enum value CARRIER_INVOICE of the request property

    • breaking

      removed the enum value CERTIFICATE_OF_INSURANCE of the request property

    • breaking

      removed the enum value COI_AUTO of the request property

    • breaking

      removed the enum value COI_BIPD of the request property

    • breaking

      removed the enum value COI_CARGO of the request property

    • breaking

      removed the enum value COMMERCIAL_DRIVERS_LICENSE of the request property

    • breaking

      removed the enum value COMMERCIAL_INVOICE of the request property

    • breaking

      removed the enum value CUSTOMER_ACCESSORIAL_SCHEDULE of the request property

    • breaking

      removed the enum value CUSTOMER_AGREEMENT of the request property

    • breaking

      removed the enum value CUSTOMER_AWARDED_BIDS of the request property

    • breaking

      removed the enum value CUSTOMER_AWARDED_RATES_LANES of the request property

    • breaking

      removed the enum value CUSTOMER_CREDIT_REPORT of the request property

    • breaking

      removed the enum value DELIVERY_ALERT of the request property

    • breaking

      removed the enum value DELIVERY_ORDER of the request property

    • breaking

      removed the enum value DETENTION of the request property

    • breaking

      removed the enum value FACTOR_NOTICE_OF_ASSIGNMENT of the request property

    • breaking

      removed the enum value FREIGHT_BILL of the request property

    • breaking

      removed the enum value FUEL_RECEIPT of the request property

    • breaking

      removed the enum value GBL of the request property

    • breaking

      removed the enum value HOUSE_AIRWAY_BILL of the request property

    • breaking

      removed the enum value HOUSE_AIRWAY_BILL_LABEL of the request property

    • breaking

      removed the enum value HOUSE_AIRWAY_BILL_LABEL_MULTI of the request property

    • breaking

      removed the enum value IAC_CERTIFICATION of the request property

    • breaking

      removed the enum value INTERNATIONAL_HOUSE_AIRWAY_BILL of the request property

    • breaking

      removed the enum value INTERNATIONAL_MASTER_AIRWAY_BILL of the request property

    • breaking

      removed the enum value INVOICE of the request property

    • breaking

      removed the enum value LOAD_SUMMARY of the request property

    • breaking

      removed the enum value LOAD_TENDER of the request property

    • breaking

      removed the enum value LOG of the request property

    • breaking

      removed the enum value LOGO of the request property

    • breaking

      removed the enum value LOGO_DOC of the request property

    • breaking

      removed the enum value LOGO_RECTANGLE of the request property

    • breaking

      removed the enum value LUMPER_RECEIPT of the request property

    • breaking

      removed the enum value MASTER_AIRWAY_BILL of the request property

    • breaking

      removed the enum value OTHER of the request property

    • breaking

      removed the enum value PACKING_LIST of the request property

    • breaking

      removed the enum value PHOTOGRAPH of the request property

    • breaking

      removed the enum value PROOF_OF_DELIVERY of the request property

    • breaking

      removed the enum value PROOF_OF_PERFORMANCE of the request property

    • breaking

      removed the enum value QUOTE of the request property

    • breaking

      removed the enum value RATE_CON of the request property

    • breaking

      removed the enum value REEFER_KEYPAD of the request property

    • breaking

      removed the enum value ROUTING_ALERT of the request property

    • breaking

      removed the enum value SCALE_RECEIPT of the request property

    • breaking

      removed the enum value SEAL of the request property

    • breaking

      removed the enum value SHIPPING_LABEL of the request property

    • breaking

      removed the enum value SIDE_OF_TRUCK of the request property

    • breaking

      removed the enum value SIGNED_CARRIER_AGREEMENT of the request property

    • breaking

      removed the enum value TRIP_SHEET of the request property

    • breaking

      removed the enum value W9 of the 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 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 the new optional request property

    • 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

    • 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

      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 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

    • 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