---
title: "Upload business documents"
method: POST
path: "/business/{business_token}/documents"
tags: ["Business"]
---

# Upload business documents

`POST /business/{business_token}/documents`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/business/{business_token}/documents`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/masspay/apis/masspay-api/docs/business/:business_token/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

This **POST** endpoint is used to upload documents for a business created with `POST /business`: a KYB report, articles of incorporation, a proof of address, and so on. <br> You must specify the `business_token` in the URL path. The caller must be the account that created the business, or the business itself using its own API key. <br> In the request body, include an array of `documents`. Each document requires a `document_type`, the original `file_name` (with its extension) and its Base64-encoded `file_content`; an optional `description` adds context, for `other` in particular. <br> Every document is validated and virus-scanned before any is stored, so a rejected document rejects the whole request and nothing is written. <br> A document may be at most 4,500,000 bytes once decoded and a request may carry at most 10 documents; the whole request must also stay under the 6 MB API limit (Base64 adds a third to each file), so larger sets go in several requests to `POST /business/{business_token}/documents`. <br> The response lists the documents stored, in request order, each with its `document_token`. A document that could not be stored is left out: compare the response with what you sent and resend what is missing. Uploads only add documents; nothing already on file is replaced.

## Request body

- object
  - `documents` BusinessDocument[], required: The documents to add to the business.
    - `document_type` 'kyb_report' | 'articles_of_incorporation' | 'certificate_of_incorporation' | 'certificate_of_good_standing' | 'business_license' | 'operating_agreement' | 'bylaws' | 'ownership_structure' | 'proof_of_address' | 'bank_statement' | 'tax_document' | 'financial_statement' | 'other', required: What the document is. Use `other` for anything not listed and say what it is in `description`.
    - `file_name` string, required: Original file name including its extension; any directory part is dropped. Supported extensions: pdf, jpg, jpeg, png, gif, bmp, tif, tiff, webp, heic, heif, doc, docx. The extension decides how the file is stored and served.
    - `file_content` string, required: Base64-encoded file content; a `data:...;base64,` prefix is accepted. At most 4,500,000 bytes once decoded.
    - `description` string: Optional note for our underwriting team, such as what an `other` document is or which period a statement covers.

## Response `200`

OK

- BusinessDocumentsResp
  - `business_token` string, required: The business the documents belong to.
  - `documents` BusinessDocumentResp[], required: The documents, in request order for an upload and oldest first for a listing.
    - `document_token` string, required: Token identifying the stored document.
    - `document_type` 'kyb_report' | 'articles_of_incorporation' | 'certificate_of_incorporation' | 'certificate_of_good_standing' | 'business_license' | 'operating_agreement' | 'bylaws' | 'ownership_structure' | 'proof_of_address' | 'bank_statement' | 'tax_document' | 'financial_statement' | 'other', required: The `document_type` it was submitted with.
    - `file_name` string, required: The file name it was submitted with, without any directory part.
    - `size_bytes` integer, required: Size of the decoded file in bytes.
    - `description` string: The `description` it was submitted with; absent when none was given.
    - `time_uploaded` string, date-time, required: When the document was stored, ISO 8601, UTC.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: You do not have necessary permissions for the resource
- `404`: Business not found: the token is unknown, or the business was neither created by your account nor is your own
- `500`: Internal Server Error
- `504`: Gateway Timeout

## Changes

- **2026-11-03** `f9fa41b7c45c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/business/:business_token/documents/post.md)

---

[API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)