Sortpay

API Integration

Developer Feature

Programmatically access your invoice data with our comprehensive REST API (Developer plan required)

REST API
Complete CRUD operations
Webhooks
Real-time notifications
Secure Access
API key authentication

API Endpoints

Upload Invoice
POST
POST /api/invoices/upload

Upload an invoice file for AI processing and data extraction.

  • Supports PDF, PNG, JPEG formats (max 50MB)
  • Multipart/form-data with file parameter
  • Returns invoice ID for status tracking
Get Invoice Details
GET
GET /api/invoices/{invoiceId}

Retrieve complete invoice data including all extracted fields and line items.

  • Full JSON response with all extracted data
  • Processing status and confidence scores
  • Line items and BANVR verification (Pro features)
List Invoices
GET
GET /api/invoices?page=1&limit=20

Get paginated list of all invoices with filtering and sorting options.

  • Pagination with configurable page size
  • Filter by date range, status, vendor
  • Sort by date, amount, processing status
Export Data
GET
GET /api/invoices/{invoiceId}/export/{format}

Export invoice data in various formats (CSV, JSON, Excel).

  • Multiple format support: csv, json, xlsx
  • Batch export for multiple invoices
  • Proper file headers and content-type

Authentication

API Key Setup

  1. 1Upgrade to Developer plan
  2. 2Go to Dashboard → Settings → API Keys
  3. 3Click "Generate New API Key"
  4. 4Copy and securely store your API key

Usage Example

curl -X GET \
  https://api.sortpay.io/api/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Important: Keep your API key secure and never expose it in client-side code

Rate Limits

Endpoint TypeRate LimitWindowDescription
Upload10 requests1 minuteFile upload endpoints
General API100 requests1 minuteMost API endpoints
Export30 requests1 minuteData export endpoints
Processing20 requests1 minuteInvoice processing endpoints

Rate Limit Headers: All responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers

Webhooks

Webhook Events
  • invoice.uploaded:Invoice successfully uploaded and queued
  • invoice.processing.started:AI extraction has begun
  • invoice.processing.completed:Extraction completed successfully
  • invoice.processing.failed:Extraction failed with error details
Webhook Security
Signature Verification:

All webhook requests include an X-Sortpay-Signature header with HMAC-SHA256 signature

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return signature === expected;
}

Response Data Format

Invoice Data Structure
{
  "id": 123,
  "status": "completed",
  "filename": "invoice_001.pdf",
  "uploadedAt": "2024-01-15T10:30:00Z",
  "processedAt": "2024-01-15T10:31:15Z",
  "extractedData": {
    "vendorName": "Acme Corp Ltd",
    "vendorAddress": "123 Business St, Cape Town, 8001",
    "vendorTaxId": "4123456789",
    "invoiceNumber": "INV-2024-001",
    "invoiceDate": "2024-01-15",
    "dueDate": "2024-02-14",
    "currency": "ZAR",
    "subtotal": 100000,    // 1000.00 ZAR in cents
    "taxAmount": 15000,    // 150.00 ZAR in cents
    "totalAmount": 115000, // 1150.00 ZAR in cents
    "bankAccountHolder": "Acme Corp Ltd",
    "bankName": "First National Bank",
    "bankAccountNumber": "62123456789",
    "bankBranchCode": "250655"
  },
  "lineItems": [
    {
      "description": "Web Development Services",
      "quantity": 10,
      "unitPrice": 10000,   // 100.00 ZAR in cents
      "amount": 100000,     // 1000.00 ZAR in cents
      "position": 1
    }
  ],
  "banvrVerification": {
    "status": "verified",
    "message": "Account verified successfully"
  },
  "confidence": 0.95
}

Code Examples

Node.js Example
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.sortpay.io/api';

// Upload invoice
async function uploadInvoice(filePath) {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  
  const response = await axios.post(`${BASE_URL}/invoices/upload`, form, {
    headers: {
      ...form.getHeaders(),
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  return response.data;
}

// Get invoice details
async function getInvoice(invoiceId) {
  const response = await axios.get(`${BASE_URL}/invoices/${invoiceId}`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  
  return response.data;
}
Python Example
import requests

API_KEY = 'your_api_key_here'
BASE_URL = 'https://api.sortpay.io/api'

def upload_invoice(file_path):
    with open(file_path, 'rb') as f:
        files = {'file': f}
        headers = {'Authorization': f'Bearer {API_KEY}'}
        
        response = requests.post(
            f'{BASE_URL}/invoices/upload',
            files=files,
            headers=headers
        )
        
    return response.json()

def get_invoice(invoice_id):
    headers = {'Authorization': f'Bearer {API_KEY}'}
    
    response = requests.get(
        f'{BASE_URL}/invoices/{invoice_id}',
        headers=headers
    )
    
    return response.json()

Ready to Integrate with Our API?

Upgrade to Developer plan to unlock full API access with webhooks and programmatic invoice processing.

Related Articles

API Quick Start

Get started with the Sortpay API in minutes

Authentication

API keys and security best practices

Webhooks

Real-time notifications for your app

Sortpay - Zero Manual Data Entry