---
title: "Create a Merchant Document Upload Request"
method: POST
path: "/merchants/{merchant_id}/documents"
tags: ["Merchants"]
---

# Create a Merchant Document Upload Request

`POST /merchants/{merchant_id}/documents`

## Request

- Base URL: `https://app-sandbox.resolvepay.com/api`
- URL: `https://app-sandbox.resolvepay.com/api/merchants/{merchant_id}/documents`
- Auth: one of:
  - HTTP bearer
  - HTTP basic
- TypeScript: <https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/docs/merchants/:merchant_id/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `merchant_id` string, required

## Request body

- CreateMerchantDocumentRequest
  - `document_type` 'bank_statements' | 'financial_statements' | 'credit_references' | 'personal_guarantee' | 'other', required: Merchant document type.
  - `filename` string, required: Original filename for the document. The filename must include an extension. For known MIME types, the extension must match `filetype`.
  - `filetype` string, required: MIME type for the document. Known MIME types are validated against the filename extension.
  - `download_url` string, uri: 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.

## Response `200`

Successful response with merchant document upload/download initiation details.

- MerchantDocumentUploadRequestObject
  - `id` string: Unique identifier of the merchant document.
  - `document_id` string: Alias of the merchant document identifier.
  - `document_type` 'bank_statements' | 'financial_statements' | 'credit_references' | 'personal_guarantee' | 'other'
  - `status` 'pending_upload' | 'failed': Initial validation lifecycle status for the document.
  - `upload_url` string, uri, nullable: Presigned S3 URL to upload file content when `transfer_method` is `presigned_upload`.
  - `upload_expires_at` string, date-time, nullable: Expiration timestamp for `upload_url` when `transfer_method` is `presigned_upload`.
  - `object_key` string: S3 object key where the document is expected to be stored.
  - `transfer_method` 'presigned_upload' | 'download_url': How the document is moved into Resolve-managed storage.
  - `queue_dispatch_status` 'queued' | 'failed', nullable: Queue dispatch result when `transfer_method` is `download_url`.
  - `upload_headers` object, nullable: Required headers to include on the presigned upload PUT request. Always includes: - `x-amz-meta-validation_profile` May include callback routing headers when configured by Resolve: - `x-amz-meta-callback_domain` - `x-amz-meta-callback_url`
  - `validation_profile` 'merchant_underwriting_document_default': Resolve-managed document validation profile applied to this request.

## Other responses

- `400`: Bad request error
- `401`: Unauthorized error
- `404`: Not found error
- `429`: Rate limit error

---

[API](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference.md) - [All operations](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/revisions/5a1c75b8b404?raw)