---
title: "Unlock a password-protected document"
method: POST
path: "/documents/{id}/unlock"
tags: ["Documents"]
---

# Unlock a password-protected document

`POST /documents/{id}/unlock`

## Request

- Base URL: `https://api.bankstatemently.com/v1`
- URL: `https://api.bankstatemently.com/v1/documents/{id}/unlock`
- Auth: API key in header `X-API-Key`

Submit a password to unlock and process a password-protected PDF. The document must have status `password_required`. On success, the document transitions to `processing` status. Rate limit: 20 requests per minute.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `password` string, required: The password to unlock the PDF. Used in memory only for decryption and never stored.

## Response `200`

Password accepted. Document is now processing.

- StatementUploadResponse: Response returned when a PDF is successfully accepted for processing.
  - `id` string, uuid, required: Unique document identifier. Use this to poll status and request exports.
  - `status` 'processing' | 'completed' | 'failed' | 'password_required', required: The processing status of a document.
  - `contentHash` string, required: Content-addressable hash of the uploaded file.
  - `createdAt` string, date-time, required: Timestamp when the document was created.
  - `statements` StatementSummary[], required: Always an empty array on upload; populated once processing completes.
    - `index` integer, required: Zero-based index of this statement within the document.
    - `statementPeriod` StatementPeriod: The date range covered by a single statement within the document.
      - `from` string, date, required: Start date of the statement period (ISO 8601).
      - `to` string, date, required: End date of the statement period (ISO 8601).
    - `transactionCount` integer, nullable: Number of transactions in this statement, or null if not yet counted.
  - `links` object, required
    - `self` string, uri, required: URL to poll for processing status.
    - `unlock` string, uri: URL to submit a password for unlocking. Only present when status is `password_required`.

## Other responses

- `400`: Invalid request (e.g., document is not in `password_required` status).
- `401`: Authentication failed, API key revoked, or API key expired.
- `404`: Document not found.
- `422`: Wrong password.
- `429`: Rate limit exceeded or maximum unlock attempts reached.
- `500`: An unexpected server error occurred.

---

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