# Authentication Source: https://docs.ledgerize.ai/authentication Authenticate every request with your Ledgerize API key via the `X-Api-Key` header. ```http theme={null} X-Api-Key: ``` Your key is available in your Ledgerize account under Settings → API Access. Do not expose this key in client-side code. # Code Examples Source: https://docs.ledgerize.ai/code-examples ## Node.js (fetch + FormData) ```ts theme={null} import fs from 'fs/promises'; const key = process.env.LEDGERIZE_API_KEY!; const base = 'https://ledgerize.ai'; // 1) Upload const fd = new FormData(); fd.append('file', new Blob([await fs.readFile('statement.pdf')], { type: 'application/pdf' }), 'statement.pdf'); const up = await fetch(base + '/api/v1/files', { method: 'POST', headers: { 'X-Api-Key': key }, body: fd }).then(r => r.json()); console.log('uuid:', up.uuid); // 2) Convert const job = await fetch(base + '/api/v1/convert', { method: 'POST', headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' }, body: JSON.stringify({ ids: [up.uuid], format: 'JSON' }) }).then(r => r.json()); console.log('jobId:', job.jobId); // 3) Poll let status; do { status = await fetch(`${base}/api/v1/jobs/${job.jobId}`, { headers: { 'X-Api-Key': key } }).then(r => r.json()); } while (status.status !== 'completed'); // 4) Result (JSON) const result = await fetch(`${base}/api/v1/jobs/${job.jobId}/result`, { headers: { 'X-Api-Key': key } }).then(r => r.json()); console.log(result.normalised.slice(0, 3)); // CSV result (download) const buf = await fetch(`${base}/api/v1/jobs/${job.jobId}/result`, { headers: { 'X-Api-Key': key } }).then(r => r.arrayBuffer()); await fs.writeFile('statement.csv', Buffer.from(buf)); console.log('Saved statement.csv'); ``` ## cURL ```bash theme={null} # Upload curl -s -X POST \ -H "X-Api-Key: $LEDGERIZE_API_KEY" \ -F file=@statement.pdf \ https://ledgerize.ai/api/v1/files # Convert (JSON) curl -s -X POST \ -H "X-Api-Key: $LEDGERIZE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ids":[""],"format":"JSON"}' \ https://ledgerize.ai/api/v1/convert # Poll curl -s -H "X-Api-Key: $LEDGERIZE_API_KEY" https://ledgerize.ai/api/v1/jobs/ # Result curl -s -H "X-Api-Key: $LEDGERIZE_API_KEY" https://ledgerize.ai/api/v1/jobs//result ``` # Convert Source: https://docs.ledgerize.ai/endpoints/convert `POST /api/v1/convert` Start a conversion for one or more uploaded UUIDs. Supported formats: `JSON`, `CSV`, `XLS`. ```bash theme={null} curl -s -X POST \ -H "X-Api-Key: $LEDGERIZE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ids":[""],"format":"JSON"}' \ https://ledgerize.ai/api/v1/convert ``` Response ```json theme={null} { "jobId": "job_123", "accepted": [""] } ``` # Jobs Source: https://docs.ledgerize.ai/endpoints/jobs ## Status `GET /api/v1/jobs/{jobId}` Returns job status and progress. ## Result `GET /api/v1/jobs/{jobId}/result` Returns the converted data. For `JSON`, the response is JSON; for `CSV`/`XLS`, a file download. ### Notes * If you request the result before the job completes, you'll get a `409 NOT_READY`. * Jobs are ephemeral; fetch results soon after completion (job status and result may not be retained indefinitely). ```json theme={null} { "normalised": [ { "date": "2025-03-13", "description": "Start balance" } ] } ``` # Upload Source: https://docs.ledgerize.ai/endpoints/upload `POST /api/v1/files` (multipart/form-data) Send a PDF and receive a UUID for conversion. ```bash theme={null} curl -s -X POST \ -H "X-Api-Key: $LEDGERIZE_API_KEY" \ -F file=@statement.pdf \ https://ledgerize.ai/api/v1/files ``` Response ```json theme={null} { "uuid": "2d09c956-854d-434d-a1bb-872d0a2cf44f", "pages": 3 } ``` # Errors Source: https://docs.ledgerize.ai/errors Errors are returned in a normalized JSON envelope: ```json theme={null} { "error": { "code": "RATE_LIMITED", "message": "Too many requests" } } ``` Common codes: * `AUTH_INVALID_KEY` (401): Invalid or missing API key * `AUTH_NOT_CONFIGURED` (503): API auth is not configured on the server * `AUTH_UNAVAILABLE` (503): Temporary issue validating API keys * `RATE_LIMITED` (429): Per-key rate limit exceeded * `FILE_REQUIRED` (400): Missing multipart `file` field * `INVALID_IDS` (400): Missing or empty `ids[]` in a convert request * `PASSWORD_REQUIRED` (400): Missing `password` in body * `NOT_FOUND` (404): Job not found (expired or invalid `jobId`) * `NOT_READY` (409): Job exists but is not completed yet * `UPLOAD_UNEXPECTED` (502): Upload succeeded upstream, but the response could not be parsed * `UPLOAD_FAILED`, `CONVERT_FAILED`, `SET_PASSWORD_FAILED` (502): Processing or upstream error (check `error.details.reason`) # Ledgerize API Source: https://docs.ledgerize.ai/index Convert bank statement PDFs into structured data ## Overview Ledgerize lets you convert bank statement PDFs into clean, structured data via simple HTTP endpoints. Authenticate with an API key in the `X-Api-Key` header, upload a PDF, start a conversion, poll a job, and fetch the result. Follow our three step quickstart guide. ## Quick links Start with cURL and Node.js examples. Use the X-Api-Key header. Upload a PDF and get a UUID. Convert, poll, and fetch results. ## Resources Download the collection. # Quickstart Source: https://docs.ledgerize.ai/quickstart Convert a PDF with the Ledgerize API in minutes ## Steps ### 1) Upload a PDF ```bash theme={null} curl -s -X POST -H "X-Api-Key: $LEDGERIZE_API_KEY" -F file=@statement.pdf https://ledgerize.ai/api/v1/files ``` ### 2) Convert to JSON ```bash theme={null} curl -s -X POST -H "X-Api-Key: $LEDGERIZE_API_KEY" -H "Content-Type: application/json" -d '{"ids":[""],"format":"JSON"}' https://ledgerize.ai/api/v1/convert ``` ### 3) Poll job & fetch result ```bash theme={null} curl -s -H "X-Api-Key: $LEDGERIZE_API_KEY" https://ledgerize.ai/api/v1/jobs/ curl -s -H "X-Api-Key: $LEDGERIZE_API_KEY" https://ledgerize.ai/api/v1/jobs//result ``` Use `format: CSV` or `XLS` to download a file. See the Endpoints section for details.