API Documentation

curl -X POST https://extraly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "document=@bank_statement.pdf" \
  -F "detection_type=bank_statement"

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-API-Key: xtr_live_a1b2c3d4e5f6...

{
  "event": "document.completed",
  "document_id": "doc_8f3a1b2c4d5e",
  "status": "completed",
  "results": {
    "bank_name": "PrivatBank",
    "transaction_count": 47,
    "opening_balance": 15230.50,
    "closing_balance": 18445.75
  },
  "metadata": {},
  "timestamp": "2026-03-21T10:31:15Z"
}

{
  "event": "document.failed",
  "document_id": "doc_8f3a1b2c4d5e",
  "status": "failed",
  "error": {
    "code": "PROCESSING_ERROR",
    "message": "Unable to extract data from the provided document. The file may be corrupted or in an unsupported layout."
  },
  "metadata": {},
  "timestamp": "2026-03-21T10:31:15Z"
}

X-Extraly-Signature: sha256=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

# Verification pseudocode:
expected = HMAC-SHA256(request_body, your_api_key)
is_valid = secure_compare(expected, signature_from_header)

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 984
X-RateLimit-Reset: 1711015200

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The document field is required.",
    "details": {
      "document": ["The document field is required."]
    }
  }
}

# Submit a document
curl -X POST https://extraly.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "detection_type=invoice" \
  -F "webhook_url=https://yourapp.com/webhook"

# Get document status and results
curl https://extraly.ai/api/v1/documents/doc_8f3a1b2c4d5e \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

# List all documents
curl "https://extraly.ai/api/v1/documents?page=1&per_page=20&status=completed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

# Export results as CSV
curl -OJ https://extraly.ai/api/v1/documents/doc_8f3a1b2c4d5e/export/csv \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

# Delete a document
curl -X DELETE https://extraly.ai/api/v1/documents/doc_8f3a1b2c4d5e \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-API-Key: YOUR_API_KEY"

import requests
import time

BASE_URL = "https://extraly.ai/api/v1"
HEADERS = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "X-API-Key": "YOUR_API_KEY",
}

# Submit a document
with open("bank_statement.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/documents",
        headers=HEADERS,
        files={"document": f},
        data={
            "detection_type": "bank_statement",
            "webhook_url": "https://yourapp.com/webhook",
        },
    )

doc = response.json()["data"]
doc_id = doc["id"]
print(f"Document submitted: {doc_id} (status: {doc['status']})")

# Poll for results
while True:
    result = requests.get(
        f"{BASE_URL}/documents/{doc_id}",
        headers=HEADERS,
    ).json()["data"]

    if result["status"] in ("completed", "failed"):
        break

    time.sleep(2)

if result["status"] == "completed":
    print(f"Transactions found: {result['results']['transaction_count']}")

    # Export as XLSX
    export = requests.get(
        f"{BASE_URL}/documents/{doc_id}/export/xlsx",
        headers=HEADERS,
    )
    with open("results.xlsx", "wb") as f:
        f.write(export.content)
else:
    print(f"Processing failed: {result['error']}")

const fs = require("fs");
const FormData = require("form-data");

const BASE_URL = "https://extraly.ai/api/v1";
const headers = {
  Authorization: "Bearer YOUR_ACCESS_TOKEN",
  "X-API-Key": "YOUR_API_KEY",
};

async function processDocument(filePath) {
  // Submit document
  const form = new FormData();
  form.append("document", fs.createReadStream(filePath));
  form.append("detection_type", "bank_statement");

  const submitRes = await fetch(`${BASE_URL}/documents`, {
    method: "POST",
    headers: { ...headers, ...form.getHeaders() },
    body: form,
  });
  const { data: doc } = await submitRes.json();
  console.log(`Submitted: ${doc.id}`);

  // Poll for results
  let result;
  while (true) {
    const res = await fetch(`${BASE_URL}/documents/${doc.id}`, { headers });
    result = (await res.json()).data;

    if (result.status === "completed" || result.status === "failed") break;
    await new Promise((r) => setTimeout(r, 2000));
  }

  if (result.status === "completed") {
    console.log(`Transactions: ${result.results.transaction_count}`);

    // Export as JSON
    const exportRes = await fetch(
      `${BASE_URL}/documents/${doc.id}/export/json`,
      { headers }
    );
    const exportData = await exportRes.json();
    console.log(exportData);
  }
}

processDocument("./bank_statement.pdf");

<?php

$baseUrl = 'https://extraly.ai/api/v1';
$headers = [
    'Authorization: Bearer YOUR_ACCESS_TOKEN',
    'X-API-Key: YOUR_API_KEY',
];

// Submit a document
$ch = curl_init("$baseUrl/documents");
$postFields = [
    'document' => new CURLFile('bank_statement.pdf', 'application/pdf'),
    'detection_type' => 'bank_statement',
    'webhook_url' => 'https://yourapp.com/webhook',
];
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postFields,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$docId = $response['data']['id'];
echo "Submitted: $docId\n";

// Poll for results
while (true) {
    $ch = curl_init("$baseUrl/documents/$docId");
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $result = json_decode(curl_exec($ch), true)['data'];
    curl_close($ch);

    if (in_array($result['status'], ['completed', 'failed'])) {
        break;
    }
    sleep(2);
}

if ($result['status'] === 'completed') {
    echo "Transactions: " . $result['results']['transaction_count'] . "\n";

    // Export as CSV
    $ch = curl_init("$baseUrl/documents/$docId/export/csv");
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
    ]);
    $csv = curl_exec($ch);
    curl_close($ch);
    file_put_contents('results.csv', $csv);
} else {
    echo "Failed: " . $result['error']['message'] . "\n";
}

<?php

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EXTRALY_SIGNATURE'] ?? '';
$apiKey = 'YOUR_API_KEY';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $apiKey);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload, true);

if ($event['event'] === 'document.completed') {
    // Process the completed document
    $docId = $event['document_id'];
    $results = $event['results'];
    // ... your logic here
}

http_response_code(200);
echo 'OK';

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
API_KEY = "YOUR_API_KEY"

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Extraly-Signature", "")
    expected = "sha256=" + hmac.new(
        API_KEY.encode(), request.data, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)

    event = request.json

    if event["event"] == "document.completed":
        doc_id = event["document_id"]
        results = event["results"]
        # ... your logic here

    return "OK", 200