# Get a document

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.

Endpoint: GET /documents/{id}
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    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.
    Enum: "id", "key"

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the document
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `key` (string,null)
    Client-defined key for external reference
    Example: "doc-inv-2025-001"

  - `type` (string, 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
    Enum: "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"

  - `fileName` (string, required)
    Original file name
    Example: "invoice-2025-001.pdf"

  - `extension` (string)
    File extension (without dot)
    Example: "pdf"

  - `contentType` (string, required)
    MIME content type
    Example: "application/pdf"

  - `fileSize` (integer,null)
    File size in bytes
    Example: 102400

  - `status` (string, required)
    Upload status of the document.
- PENDING_UPLOAD: Document record created, file not yet uploaded
- UPLOADED: File has been uploaded to storage
    Enum: "PENDING_UPLOAD", "UPLOADED"

  - `uploadUrl` (string,null)
    Pre-signed URL for uploading the file.
Only present immediately after document creation.
Expires after 15 minutes.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `downloadUrl` (string,null)
    Pre-signed URL for downloading the file.
Present when document status is UPLOADED.
Expires after 1 hour.
    Example: "https://s3.amazonaws.com/bucket/key?signature=..."

  - `tags` (object,null)
    Arbitrary key-value tags for the document
    Example: {"invoiceNumber":"INV-2025-001","customerPO":"PO-12345"}

  - `createdAt` (string, required)
    When the document was created
    Example: "2025-01-15T10:30:00Z"

  - `updatedAt` (string,null)
    When the document was last updated
    Example: "2025-01-15T10:35:00Z"

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message