API Export

API export lets systems receive extracted data automatically or pull it from the Foxello API after processing. It is available on Growth and Scale plans.

When to use it

• Your backend should receive completed extraction results automatically
• Your system should poll file status and download results when ready
• Your system expects specific field names through mapping

Configure after creation

The Add Workflow wizard only selects API Export. You can configure push delivery after the workflow is created:

1. Go to Workflows.
2. Find the workflow.
3. Open the Actions menu (three dots).
4. Click Edit.
5. Open the Export tab.
6. Confirm Export Destination is API.
7. Set Export Trigger.
8. Enter the Webhook URL if you want Foxello to push exports to your system.
9. Click Generate webhook secret and store the secret in your endpoint configuration.
10. Click Save Changes.

If you prefer pull-based export, generate an API import token on the Import tab and use the production endpoints below to check status and download results.

Export trigger

Use After Review when human validation matters.

Webhook URL

Enter the HTTPS endpoint that should receive the export. Your endpoint should accept POST requests and return a 2xx response when the payload is received.

This URL belongs to your system. It is not a Foxello API URL.

Webhook signing secret

Generate a Webhook signing secret on the Export tab (same flow as the API import token). Foxello shows the secret once - save it in your system. Each delivery is signed with HMAC-SHA256 so you can verify the payload before trusting it.

When a secret is configured, deliveries include:

Verify on your endpoint

1. Read the raw request body as a string (do not re-serialize JSON).
2. Join the X-Timestamp header value, a dot, and the raw body: <X-Timestamp>.<raw body>.
3. Compute HMAC-SHA256 of that string with your webhook secret.
4. Compare the result to X-Signature using a timing-safe comparison.
5. Reject requests where X-Timestamp is older than about 5 minutes. Because the timestamp is signed, it cannot be changed to replay an old delivery.
6. Store processed X-Event-Id values and reject duplicates.

Example (Node.js):

const crypto = require('crypto');

function verifySignature(payload, timestamp, signature, secret) {
  const expected = Buffer.from(
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${payload}`)
      .digest('hex')
  );
  const received = Buffer.from(signature ?? '');

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}

Regenerating the secret in workflow settings invalidates the previous one. Update your endpoint configuration when you regenerate.

Production endpoints

Use these endpoints when your system pulls exported data from Foxello:

Use the upload endpoint when the workflow also uses API import. Use the status and download endpoints to retrieve the exported result when the file reaches processed, approved, or exported status.

JSON download and API webhook export use the same response shape.

Endpoint examples

Upload response

The upload endpoint returns file metadata and a download URL path.

{
  "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."
}

Status response

Poll the status endpoint until the file is ready to download.

{
  "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"
}

JSON download response

The download endpoint returns the same payload shape as API webhook export. It includes the 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": []
      }
    ]
  }
}

Export format

API export always uses JSON, so there is no format to choose. To get the results as a CSV or Excel file, download them from Files, or use Export Results File in Zapier.

Webhook payload

When using push delivery, Foxello sends the same payload shape to your webhook URL:

{
  "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": []
      }
    ]
  }
}

The fields object contains the single extracted document. Foxello processes one document per uploaded file.

Your endpoint should return a 2xx response when it receives the payload. If you configured a webhook signing secret, verify X-Signature before processing the body.

Push vs pull API export

See API Integration for detailed authentication and request examples.