The Ultimate Guide to Suparse's Document Extraction API for Developers

import requests
import time
import os
import json
 
API_KEY = os.environ.get("SUPARSE_API_KEY") # Recommended: use environment variables
BASE_URL = "https://api.suparse.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}
FILE_PATH = "path/to/your/bank-statement.pdf"
DOC_TYPE = "bank_statement"
 
def upload_document(file_path, doc_type):
"""Uploads a document and returns its ID."""
print(f"Uploading {file_path}...")
url = f"{BASE_URL}/documents/{doc_type}"
 
    with open(file_path, "rb") as f:
        files = {"file": (os.path.basename(file_path), f)}
        response = requests.post(url, headers=HEADERS, files=files)
 
    if response.status_code == 202:
        data = response.json()
        print(f"Upload successful. Document ID: {data['document_id']}")
        return data['document_id']
    else:
        print(f"Error during upload: {response.status_code} {response.text}")
        return None
 
def poll_for_result(document_id):
"""Polls for the processing result of a document based on HTTP status codes."""
url = f"{BASE_URL}/documents/{document_id}/result"
 
    # Best practice: start polling after an initial delay
    print("Waiting 5 seconds before first poll...")
    time.sleep(5)
 
    max_attempts = 20
    delay = 3 # Subsequent delay
 
    for attempt in range(max_attempts):
        print(f"Polling for result (Attempt {attempt + 1}/{max_attempts})...")
        response = requests.get(url, headers=HEADERS)
 
        if response.status_code == 200:
            print("Processing complete!")
            return response.json()
        elif response.status_code == 202:
            print(f"Status is 'processing', waiting for {delay} seconds...")
            time.sleep(delay)
        else:
            print(f"Polling failed - status {response.status_code}: {response.text}")
            return None
 
    print("Polling timed out after maximum attempts.")
    return None
 
if name == "main":
if not API_KEY:
print("Error: SUPARSE_API_KEY environment variable not set.")
else:
doc_id = upload_document(FILE_PATH, DOC_TYPE)
if doc_id:
result = poll_for_result(doc_id)
if result:
print("\n--- Extracted Data ---")
print(json.dumps(result, indent=2))

const axios = require("axios");
const fs = require("fs");
const FormData = require("form-data");
const path = require("path");
 
const API_KEY = process.env.SUPARSE_API_KEY; // Set your key as an env var
const BASE_URL = "https://api.suparse.com/api/v1";
const FILE_PATH = "path/to/your/invoice.pdf";
const DOC_TYPE = "invoice";
 
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
const pollForResult = async (documentId) => {
  const url = `${BASE_URL}/documents/${documentId}/result`;
  const headers = { "X-API-Key": API_KEY };
 
  const maxAttempts = 20;
 
  // Start with a 5-second delay, then switch to 3-second intervals
  await sleep(5000);
 
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    console.log(
      `Polling for result (Attempt ${attempt + 1}/${maxAttempts})...`
    );
    try {
      // We expect a 200 on success. Axios will throw an error for other statuses.
      const response = await axios.get(url, { headers });
      console.log("Processing complete!");
      console.log(JSON.stringify(response.data, null, 2));
      return; // Exit loop on success
    } catch (error) {
      // Check if the error is due to a 202 "still processing" status
      if (error.response && error.response.status === 202) {
        console.log("Status is 'processing', waiting for 3 seconds...");
        await sleep(3000);
      } else {
        // Handle all other errors (404, 500, etc.)
        const status = error.response ? error.response.status : "Unknown";
        const errorData = error.response ? error.response.data : error.message;
        console.error(`Polling failed with status ${status}:`, errorData);
        return; // Exit loop on failure
      }
    }
  }
  console.error("Polling timed out after maximum attempts.");
};
 
const processDocument = async () => {
  if (!API_KEY) {
    console.error("Error: SUPARSE_API_KEY environment variable not set.");
    return;
  }
 
  const form = new FormData();
  form.append("file", fs.createReadStream(FILE_PATH));
 
  try {
    const url = `${BASE_URL}/documents/${DOC_TYPE}`;
    const response = await axios.post(url, form, {
      headers: {
        ...form.getHeaders(),
        "X-API-Key": API_KEY,
      },
    });
 
    const { document_id } = response.data;
    console.log(`Document uploaded successfully. ID: ${document_id}`);
    await pollForResult(document_id);
  } catch (error) {
    const status = error.response ? error.response.status : "Unknown";
    const errorData = error.response ? error.response.data : error.message;
    console.error(`Error uploading file with status ${status}:`, errorData);
  }
};
 
processDocument();

{
  "document_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "extraction_data": {
    "docType": "Invoice",
    "general": {
      "InvoiceNumber": "INV-2023-001",
      "TotalGrossPrice": 120.5,
      "Currency": "USD"
    },
    "lineItems": [
      {
        "ProductName": "Product A",
        "ProductQuantity": 1,
        "ProductUnitPrice": 100.0
      }
    ]
  },
  "validation": {
    "passed": true,
    "details": {
      "calculation_logic": "sum(lineItems.ProductPrice) vs general.TotalNetPrice"
    }
  },
  "credits_used": 1,
  "passed_validation": true
}