API Integration Guide: Automating Statement Processing

Integrate StatementConverter's powerful API to automate bank statement processing in your applications. This guide covers everything from authentication to webhook handling.

Getting Started

API Endpoints

Base URL: https://api.statementconverter.xyz/v1

Authentication

All API requests require authentication using API keys:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.statementconverter.xyz/v1/process

Rate Limits

• Free tier: 10 requests per minute
• Pro tier: 100 requests per minute
• Business tier: 1000 requests per minute

Core Endpoints

1. Process Statement

Upload and process a bank statement:

POST /v1/process

Parameters:

• file: PDF file (multipart/form-data)
• bank: Optional bank identifier
• webhook_url: Optional webhook for completion notification

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@statement.pdf" \
  -F "webhook_url=https://yourapp.com/webhook" \
  https://api.statementconverter.xyz/v1/process

Response:

{
  "job_id": "job_abc123",
  "status": "processing",
  "estimated_completion": "2024-01-15T10:30:00Z"
}

2. Check Job Status

Monitor processing progress:

GET /v1/status/{job_id}

Response:

{
  "job_id": "job_abc123",
  "status": "completed",
  "progress": 100,
  "result": {
    "transaction_count": 45,
    "date_range": {
      "start": "2023-12-01",
      "end": "2023-12-31"
    }
  }
}

3. Download Results

Retrieve processed data:

GET /v1/download/{job_id}?format=json

Formats:

• json: Structured JSON data
• csv: Comma-separated values
• xlsx: Excel spreadsheet

Integration Examples

JavaScript/Node.js

const StatementConverter = require('statementconverter-api');

const client = new StatementConverter({
  apiKey: 'your-api-key'
});

async function processStatement() {
  try {
    // Upload file
    const job = await client.process({
      file: './statement.pdf',
      webhookUrl: 'https://yourapp.com/webhook'
    });
    
    console.log('Job started:', job.job_id);
    
    // Poll for completion
    const result = await client.waitForCompletion(job.job_id);
    
    // Download results
    const data = await client.download(job.job_id, 'json');
    console.log('Transactions:', data.transactions);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

Python

import statementconverter
import time

client = statementconverter.Client(api_key='your-api-key')

# Process statement
with open('statement.pdf', 'rb') as f:
    job = client.process(
        file=f,
        webhook_url='https://yourapp.com/webhook'
    )

print(f"Job started: {job['job_id']}")

# Wait for completion
while True:
    status = client.get_status(job['job_id'])
    if status['status'] == 'completed':
        break
    elif status['status'] == 'failed':
        raise Exception(f"Processing failed: {status['error']}")
    time.sleep(5)

# Download results
data = client.download(job['job_id'], format='json')
print(f"Found {len(data['transactions'])} transactions")

PHP

<?php

use StatementConverter\Client;

$client = new Client(['api_key' => 'your-api-key']);

// Process statement
$job = $client->process([
    'file' => new CURLFile('statement.pdf'),
    'webhook_url' => 'https://yourapp.com/webhook'
]);

echo "Job started: " . $job['job_id'] . "\n";

// Wait for completion
do {
    $status = $client->getStatus($job['job_id']);
    sleep(5);
} while ($status['status'] === 'processing');

if ($status['status'] === 'completed') {
    $data = $client->download($job['job_id'], 'json');
    echo "Found " . count($data['transactions']) . " transactions\n";
}

Webhook Integration

Receive real-time notifications when processing completes:

Webhook Payload

{
  "job_id": "job_abc123",
  "status": "completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "result": {
    "transaction_count": 45,
    "processing_time": "2.3s"
  },
  "download_url": "https://api.statementconverter.xyz/v1/download/job_abc123"
}

Webhook Security

Verify webhook authenticity using HMAC signatures:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// Express.js webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-statementconverter-signature'];
  
  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Unauthorized');
  }
  
  const { job_id, status } = req.body;
  
  if (status === 'completed') {
    // Process completion
    console.log(`Job ${job_id} completed`);
  }
  
  res.status(200).send('OK');
});

Error Handling

Common Error Codes

• 400: Bad request (invalid parameters)
• 401: Unauthorized (invalid API key)
• 429: Rate limit exceeded
• 500: Internal server error

Error Response Format

{
  "error": {
    "code": "INVALID_FILE_FORMAT",
    "message": "File must be a PDF document",
    "details": {
      "file_type": "image/jpeg",
      "allowed_types": ["application/pdf"]
    }
  }
}

Retry Logic

Implement exponential backoff for failed requests:

async function apiRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error; // Don't retry client errors
    }
  }
  throw new Error('Max retries exceeded');
}

Best Practices

Performance Optimization

1. Batch Processing: Group multiple statements
2. Async Operations: Use webhooks instead of polling
3. Caching: Cache results for duplicate requests
4. Compression: Use gzip for large payloads

Security

1. API Key Management: Rotate keys regularly
2. HTTPS Only: Never use HTTP for API calls
3. Webhook Verification: Always verify webhook signatures
4. Input Validation: Validate all user inputs

Monitoring

1. Request Logging: Log all API interactions
2. Error Tracking: Monitor error rates and types
3. Performance Metrics: Track response times
4. Usage Analytics: Monitor API usage patterns

SDKs and Libraries

Official SDKs available for:

• JavaScript/Node.js: npm install statementconverter-js
• Python: pip install statementconverter-python
• PHP: composer require statementconverter/php-sdk
• Ruby: gem install statementconverter

Support

Need help with integration?

• Documentation: https://docs.statementconverter.xyz
• API Reference: https://api.statementconverter.xyz/docs
• Support: support@statementconverter.xyz
• Status Page: https://status.statementconverter.xyz

Start building with our API today and automate your financial data processing workflows!