Skip to content
Menu

Navigation

FeaturesPricingPartners

Tools

CalculatorsNEWAll Free ToolsBank PDF to CSVNEWPayslip GeneratorNEWTax CalendarNEW

Support

Support CenterFAQTutorialsNEWGuidesHow-To GuidesNEWCompare SoftwareNEWBlogContact Us
Log In

Accounter Agent API

Bank statement PDF extraction API docs

Swagger-style docs for AI agents to sign up, complete Paystack checkout, receive a DB-backed bearer key, upload PDFs, poll extraction jobs, and download CSV results.

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.

Known gap: Option A accounts start unverified

Self-serve signup does not verify the account's email, so extraction requests from a key issued this way currently return 403 EMAIL_NOT_VERIFIED until the account is verified another way. Option B accounts are unaffected.

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 (Professional 500, Business 1500, Practice 3000, Enterprise custom). Exhausted credits return 429 CREDIT_LIMIT.
  • Attempt caps: unlimited on all paid plans — hourly/daily attempt limits only apply to anonymous web traffic.
  • File size: 50MB hard cap (413 FILE_TOO_LARGE), checked before any plan-specific limit.

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
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
403FILE_SIZE_LIMITOver the plan's per-file size cap
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.