# Create a Merchant Document Upload Request

Creates a new merchant document record for a sub-merchant and initializes document transfer to the Resolve document validation service.
The transfer method is determined by request shape:
- If `download_url` is provided, Resolve queues a background download job (`transfer_method=download_url`).
- Otherwise, Resolve returns a presigned S3 upload URL (`transfer_method=presigned_upload`).

The validation profile is endpoint-managed by Resolve and cannot be overridden in the request.
Request validation includes:
- `filename` must include an extension
- `filetype` must be a supported MIME type for the merchant underwriting document profile
- `download_url`, when provided, must use `http` or `https`
- `filename` extension must match `filetype`

For `download_url`, queue dispatch is executed after database commit. A dispatch failure at that stage does not
roll back the merchant document row; instead, the response remains successful and the document is marked failed.

Endpoint: POST /merchants/{merchant_id}/documents
Version: partners-v1
Security: bearerAuth, basicAuth

## Path parameters:

  - `merchant_id` (string, required)
    ID of the sub-merchant under your partner account.

## Request fields (application/json):

  - `document_type` (string, required)
    Merchant document type.
    Enum: "bank_statements", "financial_statements", "credit_references", "personal_guarantee", "other"

  - `filename` (string, required)
    Original filename for the document.
The filename must include an extension. For known MIME types, the extension must match `filetype`.
    Example: bank_statement_2026_01.pdf

  - `filetype` (string, required)
    MIME type for the document.
Known MIME types are validated against the filename extension.
    Example: application/pdf

  - `download_url` (string)
    Optional remote URL for Resolve to fetch directly. When provided, Resolve queues a background download job
and does not return a presigned upload URL. Only `http` and `https` URLs are accepted.
    Example: https://partner-files.example.com/bank_statement_2026_01.pdf

## Response 200 fields (application/json):

  - `id` (string)
    Unique identifier of the merchant document.
    Example: md_1234567890abcdef

  - `document_id` (string)
    Alias of the merchant document identifier.
    Example: md_1234567890abcdef

  - `document_type` (string)
    Enum: "bank_statements", "financial_statements", "credit_references", "personal_guarantee", "other"

  - `status` (string)
    Initial validation lifecycle status for the document.
    Enum: "pending_upload", "failed"

  - `upload_url` (string)
    Presigned S3 URL to upload file content when `transfer_method` is `presigned_upload`.
    Example: https://resolve-document-validation-uploads-dev.s3.amazonaws.com/merchant/mrc_123/document/md_123/bank_statement_2026_01.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...

  - `upload_expires_at` (string)
    Expiration timestamp for `upload_url` when `transfer_method` is `presigned_upload`.
    Example: 2026-02-26T18:35:00.000Z

  - `object_key` (string)
    S3 object key where the document is expected to be stored.
    Example: merchant/mrc_123/document/md_1234567890abcdef/bank_statement_2026_01.pdf

  - `transfer_method` (string)
    How the document is moved into Resolve-managed storage.
    Enum: "presigned_upload", "download_url"

  - `queue_dispatch_status` (string)
    Queue dispatch result when `transfer_method` is `download_url`.
    Enum: "queued", "failed"

  - `validation_profile` (string)
    Resolve-managed document validation profile applied to this request.
    Enum: "merchant_underwriting_document_default"

## 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 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 404 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: [entity] not found

  - `error.type` (string)
    A short string, describing error type
    Enum: "not_found_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"