Endpoints to manage your accounts, their settings, bank movements, and on-demand scrapes.

Accounts

Use these endpoints to manage the bank accounts you have enrolled in Reconbanker, change their settings, inspect their movements, and trigger scrapes on demand. All endpoints require Authorization: Bearer <jwt>.

List accounts

Use this endpoint to list every account you have enrolled.

GET /accounts

Response 200 OK:

[
  {
    "id": "uuid",
    "bank": "itau",
    "name": "Operating account",
    "status": "active",
    "scrapeBlockedAt": null,
    "scrapeBlockedReason": null
  }
]

scrapeBlockedAt and scrapeBlockedReason are non-null when Reconbanker has stopped scraping the account because of a fatal failure (bad credentials, the bank reporting a lockout). Clear the block by fixing the cause and calling Restart scraping. See Sessions → Skip-on-fatal protection.

Operation mode is not part of the account response — it is read from GET /me and applies to every account you own.

Create an account

Use this endpoint to enroll a new bank account.

POST /accounts
Content-Type: application/json

Request body:

{
  "bankId": "uuid",
  "name": "Operating account"
}

bankId - required.
name - required.

Responses:

201 Created - returns the new account.
400 Bad Request - { "error": "bankId and name are required" }

Get one account

Use this endpoint to fetch a single account by id.

GET /accounts/:accountId

Response 200 OK:

{
  "id": "uuid",
  "bank": "itau",
  "name": "Operating account",
  "status": "active"
}

404 Not Found when the account does not exist.

Delete an account

Use this endpoint to remove an account. You must repeat the account's current name in the request body. This is a safety check so you do not delete the wrong one by mistake.

DELETE /accounts/:accountId
Content-Type: application/json

Request body:

{ "confirmation_name": "Operating account" }

Responses:

204 No Content - deleted.
400 Bad Request - { "error": "confirmation_name is required" }

Get account settings

Use this endpoint to read every setting on an account.

GET /accounts/:accountId/config

Response 200 OK:

{
  "id": "uuid",
  "account_id": "uuid",
  "pending_orders_endpoint": "https://customer.example/pending",
  "webhook_url": "https://customer.example/webhook",
  "retry_limit": 3,
  "polling_method": "GET",
  "polling_body": null,
  "auth_type": "bearer",
  "auth_token": "<token>",
  "webhook_auth_type": "bearer",
  "webhook_auth_token": "<token>",
  "notification_endpoint_url": "https://your-service.example/reconbanker/notify",
  "notification_auth_type": "bearer",
  "notification_auth_token": "<token>",
  "notification_events": ["assistance_required"],
  "notify_on_expired": false,
  "webhook_extra_fields": null,
  "silent_ingestion": false,
  "session_type": "one-shot",
  "login_mode": "simple",
  "bank_username": "user@bank"
}

Returns null when no settings have been saved yet. The notification_* fields configure the operational notification webhook, which is separate from the result webhook_url.

Update account settings

Use this endpoint to save or update every setting on an account in one call. The request body replaces the current settings.

PUT /accounts/:accountId/config
Content-Type: application/json

Request body:

{
  "pending_orders_endpoint": "https://customer.example/pending",
  "webhook_url": "https://customer.example/webhook",
  "webhook_auth_type": "bearer",
  "webhook_auth_token": "<token>",
  "notification_endpoint_url": "https://your-service.example/reconbanker/notify",
  "notification_auth_type": "bearer",
  "notification_auth_token": "<token>",
  "notification_events": ["assistance_required"],
  "retry_limit": 3,
  "polling_method": "GET",
  "polling_body": null,
  "auth_type": "bearer",
  "auth_token": "<token>",
  "bank_username": "user@bank",
  "bank_password": "<password>",
  "notify_on_expired": false,
  "webhook_extra_fields": { "tenant": "acme" },
  "session_type": "one-shot",
  "login_mode": "simple",
  "silent_ingestion": false
}

Field notes:

pending_orders_endpoint - required when your user's operation mode is "reconcile". Ignored in passthrough.
webhook_url - always required.
webhook_auth_type / webhook_auth_token - credentials Reconbanker uses to call your webhook.
notification_endpoint_url - endpoint for the operational notification webhook (OTP requests, login and scrape failures). Separate from webhook_url. Leave empty to disable.
notification_auth_type / notification_auth_token - credentials for the notification endpoint. bearer or api_key.
notification_events - which notifications to send: any of assistance_required, login_failed, scrape_failed.
retry_limit - how many times Reconbanker re-attempts a match before giving up. Default 3.
polling_method - "GET" (default) or "POST".
polling_body - sent as the JSON body when polling_method is "POST". Ignored otherwise.
auth_type / auth_token - credentials Reconbanker uses to call your pending orders endpoint. Also act as fallback for the webhook auth.
bank_username / bank_password - your online banking credentials. Stored encrypted. Leave both off to keep existing credentials unchanged.
notify_on_expired - when true, fires a webhook with status: "expired" for stale requests.
webhook_extra_fields - JSON object merged into every webhook payload. These keys are reserved and cannot be overridden: external_id, status, amount, currency, name, id, received_at.
session_type - "one-shot" (default, periodic open→scrape→close) or "persistent" (long-lived monitor). See Sessions.
login_mode - "simple" (default, unattended) or "assisted" (Reconbanker pauses for a human to complete 2FA).
silent_ingestion - passthrough only. When true, Reconbanker marks transactions as notified but does not actually call the webhook (useful for backfills).

Operation mode is not an account setting. Read it from GET /me and change it with PUT /me/operation-mode; the value applies to every account you own.

Responses:

200 OK - returns the same shape as the read endpoint.
400 Bad Request - one of the validation messages (webhook_url is required, pending_orders_endpoint is required when operation mode is reconcile, etc.).

List account movements

Use this endpoint to list bank transactions Reconbanker has read for an account.

GET /accounts/:accountId/movements?limit=100&offset=0

Query parameters:

limit - defaults to 100, maximum 500.
offset - defaults to 0.

Response 200 OK:

[
  {
    "id": "uuid",
    "external_id": "string",
    "amount": "1500.00",
    "currency": "UYU",
    "sender_name": "ACME SA",
    "received_at": "2026-05-13T10:15:00Z",
    "notified_at": null,
    "excluded_at": null
  }
]

Newest movements first.

Resend a movement webhook

Use this endpoint to replay a passthrough webhook for a specific bank transaction (for example, when your receiver was down).

POST /accounts/:accountId/movements/:movementId/notify

Responses:

202 Accepted - { "queued": true }
404 Not Found - { "error": "Movement not found for this account" }

Trigger a bank scrape

Use this endpoint to make Reconbanker log in to your bank right now instead of waiting for the next scheduled run.

POST /accounts/:accountId/scrape

Response 202 Accepted:

{ "jobId": "string" }

Restart scraping

Use this endpoint to clear a fatal scrape block (set when scrapeBlockedAt is non-null on the list response) and immediately re-enqueue a scrape. Use it after you fix the underlying cause — for example, after updating bad credentials or once the bank has lifted a lockout. Works for both one-shot and persistent accounts.

POST /accounts/:accountId/restart

Response 202 Accepted:

{ "jobId": "string" }

If the cause of the block is still present, Reconbanker may re-block the account immediately after this clear. Fix the root cause first.

Get pending OTP assistance

Use this endpoint to read the one-time code request an assisted login is currently waiting on. This is the dashboard's view of assisted login; the dashboard calls it to recover the prompt after a refresh.

GET /accounts/:accountId/otp

Response 200 OK:

{
  "id": "req-1",
  "type": "otp",
  "descriptor": { "length": 6, "type": "numeric", "purpose": "login" },
  "attempts": 2
}

Returns null when nothing is pending. There is at most one pending request per account.

Submit an OTP code

Use this endpoint to deliver a one-time code to a waiting login as the dashboard user. This is the human path; a machine integration uses the API-key equivalent POST /v1/accounts/:accountId/otp (see External API).

POST /accounts/:accountId/otp
Content-Type: application/json

Request body:

{ "code": "123456" }

code - required. 1 to 32 characters.

Response 202 Accepted:

{ "submitted": true }

A 202 means the code was forwarded to the in-progress login, not that the bank has confirmed it. This endpoint is rate-limited.

See Conciliation for the matching endpoints, Banks for the bank catalog, and User for the user-level operation mode. For the assisted-login flow end to end, see Assisted login and OTP.

Accounts

On this page