> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Upload a document > Uploads a document to fulfill an account or beneficial owner requirement. ## OpenAPI ````yaml apis/fx-account/openapi.yml POST /v1/accounts/{accountId}/documents openapi: 3.1.1 info: title: FX Account API version: 1.0.0 description: API for managing multi-currency accounts on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Accounts description: Create, list, and manage multi-currency accounts. - name: Beneficial owners description: Manage beneficial owners (UBOs) for company-owned accounts. - name: Funding instructions description: Retrieve funding instructions for depositing into an account. - name: Balances description: Retrieve fiat and crypto balances for an account. paths: /v1/accounts/{accountId}/documents: post: tags: - Accounts summary: Upload a document description: > Uploads a document to fulfill a requirement on the account identified by the path `accountId`. The same endpoint serves account-level and UBO-level documents — set `holder.type` to `ACCOUNT` with the account ID, or to `UBO` with the beneficial owner ID, in the JSON `body` part. The holder must belong to the path account: an `ACCOUNT` holder must match `accountId`, and a `UBO` holder must belong to that account. A mismatch returns `404`. operationId: uploadDocument parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/TraceVersion' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: multipart/form-data: schema: type: object properties: body: $ref: '#/components/schemas/UploadDocumentRequest' file: type: string format: binary description: Document file content. required: - body - file encoding: body: contentType: application/json examples: accountDocument: summary: Account-level document (e.g., articles of association) value: body: documentType: ARTICLES_OF_ASSOCIATION holder: type: ACCOUNT referenceId: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c uboIdentity: summary: UBO identity document with sub-type and metadata value: body: documentType: ID_CARD documentSubType: FRONT_SIDE holder: type: UBO referenceId: a1b2c3d4-e5f6-7890-1234-567890abcdef metadata: country: BR responses: '204': description: Document uploaded. headers: X-Request-Id: $ref: '#/components/headers/RequestId' '400': description: Invalid request or missing multipart fields. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: emptyFile: summary: Uploaded file is empty value: code: EMPTY_FILE message: 'File must not be empty: fieldName=file' details: fieldName: file missingMultipartField: summary: Required multipart field is missing value: code: MISSING_MULTIPART_FIELD message: 'Missing required multipart field: fieldName=body' details: fieldName: body fileTooLarge: summary: Uploaded file exceeds the maximum allowed size value: code: FILE_TOO_LARGE message: File size exceeds the maximum allowed details: fileSizeBytes: 12000000 maxSizeBytes: 10000000 unsupportedFileType: summary: Uploaded file type is not allowed value: code: UNSUPPORTED_FILE_TYPE message: Unsupported file type details: detected: EXECUTABLE invalidReferenceId: summary: holder.referenceId is not a valid UUID value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_UUID message: '''not-a-uuid'' cannot be converted to UUID' field: body:holder.referenceId params: {} '401': $ref: '#/components/responses/UnauthorizedError' '404': description: > Account or beneficial owner not found, or the holder does not belong to the path account. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: accountNotFound: $ref: '#/components/examples/AccountNotFound' uboNotFound: $ref: '#/components/examples/UboNotFound' components: parameters: AccountId: name: accountId in: path required: true description: UUID of the account. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid schemas: UploadDocumentRequest: type: object description: > JSON payload accompanying the document file in the multipart request. Sent as the `body` part with `Content-Type: application/json`. properties: documentType: allOf: - $ref: '#/components/schemas/DocumentType' description: > The type of document being uploaded. Must match a `documentType` listed in the account's `requirements.currentlyDue` array (or, for grouped requirements, appear in `options`). documentSubType: oneOf: - $ref: '#/components/schemas/DocumentSubType' - type: 'null' description: > Sub-classification of the document. Required for document types that have sides (e.g., `ID_CARD`, `DRIVER_LICENSE`). holder: $ref: '#/components/schemas/HolderRequest' metadata: type: - object - 'null' additionalProperties: type: string description: > Additional metadata required by the document type. Keys must match the `requiredMetadata` listed on the requirement (e.g., `country`, `number`). example: country: BR required: - documentType - holder ErrorResponse: type: object description: >- Standard error envelope. The HTTP response also carries an `X-Request-Id` header — reference it when contacting Trace Finance support. See [Errors](/guides/principles/errors). properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message DocumentType: type: string description: Type of document. enum: - PASSPORT - ARTICLES_OF_ASSOCIATION - OTHER - AGREEMENT - DIRECTORS_REGISTRY - INCORPORATION_ARTICLES - INCORPORATION_CERT - PROOF_OF_ADDRESS - SHAREHOLDER_REGISTRY - POWER_OF_ATTORNEY - STATE_REGISTRY - EVIDENCE_OF_SOURCE_OF_FUNDS - EVIDENCE_OF_SOURCE_OF_WEALTH - PROOF_OF_REGULATORY_LICENSE - PROOF_OF_BUSINESS_ACTIVITY - FUND_FLOW_EXPLANATION - AML_POLICY - FINANCIAL_STATEMENT - ORGANIZATIONAL_CHART - SHAREHOLDER_OWNERSHIP - WOLFSBERG_QUESTIONNAIRE - ID_CARD - DRIVER_LICENSE - RESIDENCE_PERMIT - SELFIE - UTILITY_BILL - KYC_FORM - BAAS_ADHESION_FORM - PJ_PARTNER_DOCUMENTS - PJ_PARTNER_FINANCIAL_STATEMENT - SIGNING_AUTHORITY_PROOF - KYC_MONITORING_EVIDENCE example: ARTICLES_OF_ASSOCIATION DocumentSubType: type: string description: Sub-classification for documents that have multiple sides. enum: - FRONT_SIDE - BACK_SIDE example: FRONT_SIDE HolderRequest: type: object description: > Identifies who the document belongs to. Use `ACCOUNT` with the account ID for account-level documents, or `UBO` with the UBO ID for documents belonging to a specific beneficial owner. properties: type: type: string enum: - ACCOUNT - UBO example: ACCOUNT referenceId: type: string format: uuid description: Account ID when `type=ACCOUNT`; UBO ID when `type=UBO`. example: a1b2c3d4-5e6f-7890-abcd-ef1234567890 required: - type - referenceId headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: AccountNotFound: summary: Account does not exist for the authenticated customer value: code: RESOURCE_NOT_FOUND message: >- Account with given parameters [Account.id:5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c, Customer.id:c1a2b3c4-d5e6-7890-abcd-ef1234567890] not found details: resource: Account parameters: Account.id: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c Customer.id: c1a2b3c4-d5e6-7890-abcd-ef1234567890 UboNotFound: summary: Beneficial owner does not exist on the account value: code: RESOURCE_NOT_FOUND message: >- UBO with given parameters [UBO.id:a1b2c3d4-e5f6-7890-1234-567890abcdef] not found details: resource: UBO parameters: UBO.id: a1b2c3d4-e5f6-7890-1234-567890abcdef InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````