API Integration

Upload documents and retrieve extracted data programmatically.

Requirements

• Workflow with API import method enabled
• Generated upload token from the workflow Import tab
• Growth or Scale plan

Authentication

Authenticate every request with your workflow token:

• Authorization: Bearer <token> header, or
• X-API-Token: <token> header

The token is tied to one workflow. All uploads through that token use that workflow's model, review rules, and export settings.

Generate a token

1. Go to Workflows, open the workflow menu, click Edit, and open the Import tab.
2. Click Generate API token.
3. Copy and store the token immediately - it is shown only once.
4. To rotate, click Regenerate API token and update all clients with the new value.

Endpoints

Production base URL: https://api.foxello.com

Upload example

curl -X POST "https://api.foxello.com/api/v1/file/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf"

The upload endpoint returns HTTP 202 when the file is accepted and queued.

Maximum file size is 5MB per upload.

Status response

The status endpoint returns:

• File ID and name
• Current status (pending, running, processed, approved, exported, failed, and others)
• Page count and file size
• Progress percentage
• Confidence score
• Download URL path

Poll status until the file reaches a downloadable state.

Example upload response

{
  "id": "6a1f2763e4b82c58360f9700",
  "name": "9a57b067-9f4b-4eab-83ec-df1ae71192ee.pdf",
  "originalName": "invoice-1042.pdf",
  "status": "pending",
  "createdAt": "2026-06-02T18:56:35.574Z",
  "updatedAt": "2026-06-02T18:56:35.574Z",
  "pageCount": 0,
  "filesize": 0.42,
  "progress": 0,
  "confidenceScore": 0,
  "downloadUrl": "/api/v1/file/download/6a1f2763e4b82c58360f9700",
  "message": "File uploaded successfully and queued for processing."
}

Example status response

{
  "id": "6a1f2763e4b82c58360f9700",
  "name": "9a57b067-9f4b-4eab-83ec-df1ae71192ee.pdf",
  "originalName": "invoice-1042.pdf",
  "status": "processed",
  "createdAt": "2026-06-02T18:56:35.574Z",
  "updatedAt": "2026-06-02T18:57:11.328Z",
  "pageCount": 2,
  "filesize": 0.42,
  "progress": 100,
  "confidenceScore": 0.94,
  "downloadUrl": "/api/v1/file/download/6a1f2763e4b82c58360f9700"
}

Download

Download is available when status is processed, approved, or exported.

The response format matches the workflow export settings:

• JSON - structured response body
• CSV, Excel, PDF - file download with appropriate content type

No format query parameter is needed - the workflow configuration determines the output.

Example JSON download response

For JSON export, the download endpoint returns the same payload shape used by API webhook export. It includes status fields, workflow metadata, and one extracted document under fields:

{
  "id": "6a1f2763e4b82c58360f9700",
  "name": "9a57b067-9f4b-4eab-83ec-df1ae71192ee.pdf",
  "originalName": "invoice-1042.pdf",
  "status": "processed",
  "createdAt": "2026-06-02T18:56:35.574Z",
  "updatedAt": "2026-06-02T18:57:11.328Z",
  "pageCount": 2,
  "filesize": 0.42,
  "progress": 100,
  "confidenceScore": 0.94,
  "downloadUrl": "/api/v1/file/download/6a1f2763e4b82c58360f9700",
  "fileId": "6a1f2763e4b82c58360f9700",
  "workflowId": "65f15b4ab5a16c0012b7a901",
  "workflowName": "Invoice Processing",
  "extractedAt": "2026-06-02T18:57:11.328Z",
  "fields": {
    "docType": "invoice",
    "fields": [
      {
        "text": "INV114883_2500001",
        "attribute": "InvoiceId",
        "type": "string",
        "confidence": 0.973,
        "zone": {
          "x": 518,
          "y": 455,
          "w": 344,
          "h": 47
        },
        "words": [
          {
            "id": 0,
            "text": "INV114883_2500001",
            "zone": {
              "x": 518,
              "y": 455,
              "w": 344,
              "h": 47
            },
            "confidence": 0.994,
            "offset": 20,
            "length": 17,
            "pageNumber": 1
          }
        ],
        "fields": []
      },
      {
        "text": "252,00 EUR",
        "attribute": "InvoiceTotal",
        "type": "currency",
        "confidence": 0.958,
        "zone": {
          "x": 1650,
          "y": 2876,
          "w": 214,
          "h": 44
        },
        "words": [],
        "fields": []
      }
    ]
  }
}

Typical integration flow

1. POST https://api.foxello.com/api/v1/file/upload with the document file.
2. Poll GET https://api.foxello.com/api/v1/file/status/{fileId} until status is processed, approved, or exported.
3. GET https://api.foxello.com/api/v1/file/download/{fileId} to retrieve the result.
4. Optionally handle webhook notifications from workflow notification settings for faster completion detection.

Allowed file types

Configure accepted attachment types on the workflow Import tab. Uploads outside the allowed types are rejected.

Error handling

JavaScript example

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const token = process.env.FOXELLO_API_TOKEN;
const form = new FormData();

form.append('file', fs.createReadStream('document.pdf'), 'document.pdf');

const upload = await axios.post(
  'https://api.foxello.com/api/v1/file/upload',
  form,
  {
    headers: {
      Authorization: `Bearer ${token}`,
      ...form.getHeaders(),
    },
  },
);

console.log(upload.data.id, upload.data.status);

Python example

import os
import requests

token = os.environ["FOXELLO_API_TOKEN"]

with open("document.pdf", "rb") as document:
    response = requests.post(
        "https://api.foxello.com/api/v1/file/upload",
        headers={"Authorization": f"Bearer {token}"},
        files={"file": document},
        timeout=60,
    )

response.raise_for_status()
print(response.json())

Security

• Store tokens in environment variables or a secrets manager, not in source code.
• Regenerate the token if it is exposed.
• Use HTTPS for all API calls.

See Automation for webhook-based delivery and Export Destinations for push export configuration.