# Request a shipment document upload

Creates a pending proof-of-delivery document before creating a self-fulfilled shipment.
Upload the file with every returned `upload_headers` entry, including
`Content-Type` (the requested `filetype`), poll `/shipments/documents/{file_id}` until
validation succeeds, then supply `file_id` to `/shipments`.

Endpoint: POST /shipments/documents
Version: V5
Security: bearerAuth, basicAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer JWT

  - `basicAuth` (unknown)
    http basic

## Request body:

  - `application/json` (unknown)
    Request body for obtaining a signed URL for file upload.

## Request fields (application/json):

  - `filename` (string, required)
    Original filename for the file to be uploaded.
    Example: proof_of_delivery.pdf

  - `filetype` (string, required)
    MIME type of the file.
    Example: application/pdf

## Response 200:

  - `200` (unknown)
    Pending shipment document upload request.

## Response 200 fields (application/json):

  - `id` (string, required)

  - `file_id` (string, required)
    Use when creating a self-fulfilled shipment after validation succeeds.

  - `url` (string, required)
    Stable storage URL for the staged document.
    Example: https://bucket.s3.amazonaws.com/1234567890-proof_of_delivery.pdf

  - `upload_url` (string, required)
    Presigned S3 URL for uploading the file. Use this URL to PUT the file content.
    Example: https://bucket.s3.amazonaws.com/1234567890-proof_of_delivery.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...

  - `upload_expires_at` (string, required)

  - `object_key` (string, required)

  - `transfer_method` (string, required)
    Enum: "presigned_upload"

  - `upload_headers` (object, required)

  - `validation_profile` (string, required)
    Enum: "merchant_invoice_shipment_document_default"

## Response 400:

  - `400` (unknown)
    Bad request error

## Response 400 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Validation error

  - `error.type` (string)
    A short string, describing error type
    Enum: "validation_error"

  - `error.details` (array)

  - `error.details.path` (string)
    Path to the field failed validation
    Example: path.to.field

  - `error.details.message` (string)
    Detailed description of the error
    Example: `[field]` is required

## Response 401:

  - `401` (unknown)
    Unauthorized error

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Invalid merchant credentials

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 429:

  - `429` (unknown)
    Rate limit error

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Too many requests

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"