Developer reference / REST API

Build with statement data.

Upload, read a review revision, save corrections, approve and export. Request examples for the workflow in your own application.

OpenAPI JSON Plan an integration

Overview

Use the same review-to-export workflow as the web app, from your own systems. A draft result is not an approved export: check the rows and approve the exact revision before conversion.

Start with the current contract. The generated OpenAPI document contains the complete request schemas. The examples here are a reading path through the core operations.

Authentication and security

Use a one-time-visible flk_ key. Every key stays bound to the workspace where you created it, with a limit of 60 requests per minute per key.

Send your workspace key as a Bearer token on every request. Keep it secure and make requests from your server.

authorization header

Authorization: Bearer flk_example

Set FULLA_ORIGIN to your Fulla Ledger origin, FULLA_API_KEY to your key and STATEMENT_ID to the ID returned by upload. The shell examples below use those variables.

From upload to approved export.

Six core operations. Your application may poll status or submit more than one review.

View OpenAPI JSON

Request 01

Upload a statement

Send one to ten PDFs using the files form field. Maximum 50 MiB each and 100 MiB total. All accepted: 202. Mixed per-file outcomes: 207.

POST/api/v1/statements

curl -X POST "$FULLA_ORIGIN/api/v1/statements" \
  -H "Authorization: Bearer $FULLA_API_KEY" \
  -H "Idempotency-Key: upload-2026-08-30" \
  -F "files=@statement.pdf;type=application/pdf"

Request 02

Check processing status

Use the returned statement ID. The response includes statement.job, statement.expiresAt and statement.currentRevision.

GET/api/v1/statements/{id}

curl "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID" \
  -H "Authorization: Bearer $FULLA_API_KEY"

Request 03

Get the draft result

Returns the latest saved review revision. This endpoint does not establish approval. Check the rows and approve the current revision before conversion.

GET/api/v1/statements/{id}/result

curl "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID/result" \
  -H "Authorization: Bearer $FULLA_API_KEY"

Request 04

Save your review

Example: correct one description. Replace the example UUID and base_revision with your transaction ID and current revision. Operations run in order.

PATCH/api/v1/statements/{id}/review

curl -X PATCH "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID/review" \
  -H "Authorization: Bearer $FULLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base_revision":1,"idempotency_key":"review-example-01","operations":[{"type":"set_field","transaction_id":"00000000-0000-4000-8000-000000000001","field":"description","value":"Corrected description"}]}'

Request 05

Approve the current revision

After you check the rows against the source, approve the exact current revision. Replace 2 with the revision returned by your review. A stale revision returns 409.

POST/api/v1/statements/{id}/approve

curl -X POST "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID/approve" \
  -H "Authorization: Bearer $FULLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision":2}'

Request 06

Export approved rows

Replace the example UUID with your statement ID. Set format to json, csv, xlsx or ofx. JSON returns inline (200); CSV, XLSX and OFX create an export (202) with status_url and download_url. OFX is an OFX 1.0.2 file for one account: several statements combine only when they show the same account last four digits, statement type and currency, otherwise the request returns 422 with ofx_mixed_accounts. Multiple statements require an active paid entitlement.

POST/api/v1/statements/convert?format=csv

curl -X POST "$FULLA_ORIGIN/api/v1/statements/convert?format=csv" \
  -H "Authorization: Bearer $FULLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["00000000-0000-4000-8000-000000000002"],"idempotencyKey":"export-example-01"}'

Review supports set_field, insert_row, delete_row, split_row and merge_rows. Use the generated OpenAPI schemas for every operation's complete body contract.

The statement lifecycle

01 · Upload: Send your PDFs. Accepted files enter processing.
02 · Extraction: Track progress with the status endpoint. Retrieve the latest saved review revision when the result is available.
03 · Your review: Check the rows against their source and save corrections with the current base revision.
04 · Your approval: Approve the exact revision you reviewed. Resolve a revision conflict before trying again.
05 · Export: Convert approved persisted revisions to JSON, CSV, XLSX or OFX. Download your files before the upload-based expiry.

Rate limits

60 requests per minute per API key. Respect the Retry-After header when a rate limit returns 429.

Data expiry

Financial content expires 24 hours after upload. Review, approval and export do not restart the clock.

Page allowance

Inspect your allowance, stored credits and usage with GET /api/v1/account.

Handle the other steps.

Unlock a password-protected PDF

Send the PDF password as JSON with the required Idempotency-Key header. Successful unlock resumes processing and returns 202.

unlock request

curl -X POST "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID/password" \
  -H "Authorization: Bearer $FULLA_API_KEY" \
  -H "Idempotency-Key: unlock-example-01" \
  -H "Content-Type: application/json" \
  -d '{"password":"your-pdf-password"}'

Delete a statement

DELETE starts fenced deletion and returns 202 with a pending deletion record.

delete request

curl -X DELETE "$FULLA_ORIGIN/api/v1/statements/$STATEMENT_ID" \
  -H "Authorization: Bearer $FULLA_API_KEY"

Handle errors and revision conflicts

Responses use a JSON error.code. Check for invalid requests (400), invalid keys (401), revision or state conflicts (409), expired documents (410), statements that cannot share one OFX account (422) and rate or page-quota limits (429). Review and approval conflicts include the latest state; inspect it before submitting a new revision.

Connect the next piece.

Set up your key in the workspace, or read through the integration workflow first.

Open my workspace Integration overview Contact support