Skip to content

Your privacy choices

Google Analytics and Meta measurement run only if you accept. Cookie details

Accounter Agent API

Bank statement PDF extraction API docs

Connect your own tools or AI assistants to Accounter: sign up and pay, get an API key, upload bank statement PDFs, check progress, and download the results as CSV.

OpenAPI JSONHermes YAML

Base URL

https://accounter.co.za

Extraction endpoints use Authorization: Bearer <api_key>. Keys are created from Account API Keys or returned once after paid agent onboarding.

Getting an API key

Option A

Self-serve signup

POST /api/agent/v1/onboarding with your name, email, phone, and a planKey (PROFESSIONAL, BUSINESS, PRACTICE, or ENTERPRISE). Complete the returned hosted Paystack checkoutUrl, then poll statusUrl — the raw key is returned once, the first time status is PAID.

Option B

Existing account

Sign in and open Account > API Keys. The raw key is shown once at creation time — store it immediately.

Email verification: paid sign-up (Option A) verifies your email automatically when payment confirms. For an existing account (Option B), click the verification link emailed when you signed up. Creating a key does not require verification, but extraction requests from an unverified account can return 403 EMAIL_NOT_VERIFIED.

Quickstart

Upload a PDF, poll until it completes, then read the result or download CSV.

1. Queue the extraction

curl -s -X POST https://accounter.co.za/api/agent/v1/bank-statement-extractions \
  -H "Authorization: Bearer $ACCOUNTER_AGENT_API_KEY" \
  -F "[email protected]" \
  -F "bankSlug=fnb"

2. Poll until COMPLETED or FAILED

curl -s https://accounter.co.za/api/agent/v1/bank-statement-extractions/{jobId} \
  -H "Authorization: Bearer $ACCOUNTER_AGENT_API_KEY"

Once status is COMPLETED, the response gains statement (masked account number only) and transactions. There is no webhook — polling every 2-3 seconds is the completion signal.

3. Or download CSV directly

curl -s https://accounter.co.za/api/agent/v1/bank-statement-extractions/{jobId}/csv \
  -H "Authorization: Bearer $ACCOUNTER_AGENT_API_KEY" \
  -o statement.csv

Rate limits & credits

  • Concurrency: 1 active extraction at a time per account on every plan. A second upload while one is in flight returns 429 CONCURRENT_LIMIT.
  • Credits: 1 credit per page. Monthly allowance depends on plan (Pro 500, Business 1,500, Practice 3,000, Enterprise 5,000). Exhausted credits return 429 CREDIT_LIMIT.
  • Attempt caps: no hourly or daily attempt cap on paid plans; usage is bounded by your credit allowance and the one-active-extraction concurrency limit. Daily success limits apply to free and anonymous web traffic.
  • File size: 20MB per PDF, the same limit as the Accounter website. Larger files return 403 FILE_SIZE_LIMIT; anything over 50MB is rejected earlier with 413 FILE_TOO_LARGE.
  • Active plan required: uploads need an active paid plan. Without one the API returns 403 NO_ACTIVE_PLAN, even though a key can still be created. Subscribe from your account first.

Error codes

Errors are always JSON: { "error": "...", "errorCode": "..." }. No stack traces, storage paths, or provider internals are ever returned.

Auth (any protected route)

401INVALID_AGENT_API_KEYMissing, malformed, unknown, revoked key, or inactive user

Upload validation

400INVALID_FORM_DATABody was not multipart/form-data
400MISSING_FILENo file field
400UNSUPPORTED_FILE_TYPEfile is not application/pdf
413FILE_TOO_LARGEOver 50MB (hard cap)
422CORRUPT_PDFPDF is malformed or unreadable
422PDF_PASSWORD_REQUIREDPDF is encrypted — retry with pdfPassword
422PDF_PASSWORD_INCORRECTWrong pdfPassword
422UNREADABLE_PDFCould not be parsed reliably
500BACKGROUND_QUEUE_UNAVAILABLEJob queueing failed — safe to retry

Access & usage limits

403EMAIL_NOT_VERIFIEDAccount email is not verified
403NO_ACTIVE_PLANNo active paid subscription — subscribe before uploading
403FILE_SIZE_LIMITOver the 20MB per-file limit
403PAGE_LIMITOver the plan's per-statement page cap
429CONCURRENT_LIMITAnother extraction is already in flight
429CREDIT_LIMITNot enough credits for this page count
500SECURITY_UNAVAILABLEUsage-control check failed — safe to retry

Job lookup & CSV

404JOB_NOT_FOUNDUnknown or foreign jobId
404RESULT_NOT_FOUNDCompleted job missing its document
409EXTRACTION_NOT_COMPLETECSV requested before the job finished

A completed status check can also report a terminal job failure via its own errorCode (e.g. PROVIDER_TIMEOUT, NO_TRANSACTIONS_EXTRACTED, VALIDATION_FAILED) — re-upload rather than re-polling a failed job.

Endpoint reference

Generated from the live OpenAPI document below.

post/api/agent/v1/onboarding

Start agent signup and payment

Create an Accounter account for an agent and return a hosted Paystack checkout URL.

Request

Auth
No API key required
Content type
application/json

Responses

201Checkout created.
400Invalid onboarding input.
409Account already exists.
get/api/agent/v1/onboarding/{token}

Get agent signup/payment status

Poll onboarding status. After hosted checkout succeeds, this returns the raw API key once.

Request

Auth
No API key required
Parameters
token in path

Responses

200Onboarding status.
404Onboarding session not found.
post/api/agent/v1/bank-statement-extractions

Queue bank statement extraction

Upload a bank statement PDF and queue extraction.

Request

Auth
Bearer API key required
Content type
multipart/form-data

Responses

202Extraction queued.
400Invalid upload.
401Invalid agent API key.
413File too large.
422Unreadable PDF.
get/api/agent/v1/bank-statement-extractions/{jobId}

Get extraction status

Poll extraction status and return structured result when completed.

Request

Auth
Bearer API key required
Parameters
jobId in path

Responses

200Job status or completed result.
401Invalid agent API key.
404Job not found.
get/api/agent/v1/bank-statement-extractions/{jobId}/csv

Download extraction CSV

Download CSV for a completed extraction.

Request

Auth
Bearer API key required
Parameters
jobId in path

Responses

200CSV file.
401Invalid agent API key.
404Job or result not found.
409Extraction is not complete.