Collect statements from applicants

A collection is a hosted upload page with its own link. Send the link to an applicant; they upload their statements without an account, and each file is read and delivered to you as a document.

How it works#

1. Create a collection with POST /api/v1/collections, or in the console's Collections page.
2. Send the applicant its url, by email, SMS or inside your own app.
3. They open the page, read your message and upload up to 24 files: PDFs, photos or exports.
4. Each file is read as it lands. You receive document.succeeded or document.failed for each one.
5. They press the button saying they have sent everything. You receive collection.submitted, and they go to your redirectUrl if you set one.

Create one#

curl -X POST https://statementbear.com/api/v1/collections \
  -H "Authorization: Bearer $STATEMENTBEAR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith remortgage",
    "message": "Please upload your last three months of statements for every current account.",
    "redirectUrl": "https://broker.example.com/applications/8841/done",
    "metadata": { "applicationId": "app_8841" },
    "expiresInDays": 14
  }'

{
  "id": "col_3b9e0c7a51d24f88a6c1e290",
  "object": "collection",
  "livemode": true,
  "created": 1785372094,
  "name": "Jane Smith remortgage",
  "message": "Please upload your last three months of statements for every current account.",
  "url": "https://statementbear.com/r/q7Hx2LmN0pRtVb9kZc4WdYe1",
  "status": "open",
  "submittedAt": null,
  "expiresAt": 1786581694,
  "redirectUrl": "https://broker.example.com/applications/8841/done",
  "metadata": { "applicationId": "app_8841" },
  "documents": []
}

name is required: who the statements are for, as you will recognise it in the console. message is shown to the applicant. metadata is copied onto every document uploaded. The link expires after expiresInDays, from 1 to 30, default 14. Every field is on Collections.

What the applicant sees#

• Your account's name, as set in the console, asking for their statements.
• Your message, above an upload box.
• Each file's name and whether it was read. Nothing from inside their statements is shown back.
• A button to say they have sent everything.

No account, no sign-in. The link is their only access, so send it only to them.

Collect the results#

• Webhooks. Each document's events carry collection set to the collection's id and the collection's metadata. See Webhooks.
• Listing. GET /api/v1/documents?collection=col_... returns every document uploaded through it, newest first.
• The collection. GET /api/v1/collections/{id} lists the uploaded document ids in documents.

Original files#

A collection upload keeps its original file, because you never had a copy. Download it with GET /api/v1/documents/{id}/file. It is deleted with the document, when your retention period ends or when you delete the document. See Security and data retention.

Billing#

Each upload is billed per page to your account, like any document. When your account cannot take more pages (no free pages left and no payment method, or the monthly cap reached), the upload is refused and the applicant is told you cannot receive statements right now. Nothing is read or charged.

Passwords#

The hosted page does not take passwords. A password-protected PDF is refused with a message asking the applicant to remove the password and send it again.

Closing and expiry#

• DELETE /api/v1/collections/{id} closes the link. It stops taking uploads at once.
• At expiresAt the link stops working on its own.
• Documents already uploaded stay until your retention period ends, whatever happens to the collection.

Testing#

A collection created with a test key has an id starting col_test_ and a working hosted page. Every upload returns the bank fixture, events go to your test endpoints, and nothing is billed.