Processing callbacks

A processing callback is a POST that fileAI sends to your callback URL as an upload moves through processing. It tells you which step finished, whether it succeeded, and, once the upload has been split into documents, the fileId of each document, so you can fetch values without polling. This page is the payload reference. To choose between callbacks and polling, and for extract, split, classify and agent job callbacks, see Async jobs.

Upload callbacks are sent once and not retried. If your endpoint is down or returns an error, that event is lost. Keep polling GET /v1/uploads/{uploadId} as a fallback. See Async jobs.

How it works

Where the callback goes

You set callbackURL when you request the upload, or rely on your API key’s default callback URL. Multipart uploads do not fall back to the key’s default. The full rules are under Upload options. Files added in the fileAI app or by email use your organization’s file-processing callback URL, if one is set. Use an HTTPS URL that accepts POST with a JSON body. Any #fragment on the URL is dropped before sending.

What gets sent

Each event is a single POST with Content-Type: application/json. There are no other custom headers: no signature, no timestamp, no event id. fileAI logs your response status but does not act on it, and sets no client timeout of its own. A typical successful upload sends events for these steps, in roughly this order: processing_started usually arrives twice: first with waiting, then with completed. Not every upload passes through every step, and the order is not guaranteed: key your logic on step and status, not on position. fileIds first appears on split_classify, and again on processing_finished. An upload that fails sends processing_failed with status error and an errorReason.

Reprocessing a document (for example, replacing its file) can send another round of events for the same uploadId, including beethoven_ocr or ai_form_filling with status processing and a further processing_finished. Make your handler safe to run more than once.

Example

A successful upload that produced two documents ends with:

{
  "step": "processing_finished",
  "status": "completed",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "fileIds": "b765bd00-181e-4737-b4d9-004dadd6bd45,3c1a9f02-77e4-4b1e-9a51-2f0d6c8e4a10"
}

A failed upload sends:

{
  "step": "processing_failed",
  "status": "error",
  "uploadId": "e9818d17-e5be-4d57-bdc8-5a40b4f6f4e1",
  "errorReason": "ocr_failed"
}

A minimal receiver acknowledges fast and does the work afterwards:

from flask import Flask, request

app = Flask(__name__)

@app.post("/fileai/callback")
def fileai_callback():
    event = request.get_json()
    if event["step"] == "processing_finished" and event["status"] == "completed":
        file_ids = event.get("fileIds", "").split(",")  # a string, not an array
        enqueue_fetch_values(event["uploadId"], file_ids)
    elif event["status"] == "error":
        record_failure(event["uploadId"], event["step"], event.get("errorReason"))
    return "", 200

import express from "express";

const app = express();
app.use(express.json());

app.post("/fileai/callback", (req, res) => {
  const { step, status, uploadId, fileIds, errorReason } = req.body;
  if (step === "processing_finished" && status === "completed") {
    enqueueFetchValues(uploadId, (fileIds ?? "").split(",")); // a string, not an array
  } else if (status === "error") {
    recordFailure(uploadId, step, errorReason);
  }
  res.sendStatus(200);
});

Reference

Payload fields

Field	Type	Present	Description
`step`	string	Always	The processing step this event is about. See below.
`status`	string	Always	`waiting`, `processing`, `completed` or `error`.
`uploadId`	string	Always	The `uploadId` returned when you created the upload.
`fileIds`	string	`split_classify` and `processing_finished`	The `fileId`s of the documents produced from the upload, joined with commas into one string. Split it yourself.
`errorReason`	string	Only when there is a reason	Machine-readable failure reason, such as `ocr_failed`, `password_protected` or `corrupted_file`.

There is no timestamp field. Record the time you received the event if you need one; GET /v1/uploads/{uploadId} returns a timestamp per step.

Statuses

`status`	Meaning
`waiting`	The step is queued. Sent for `processing_started`.
`processing`	The step is running. Sent when a document is reprocessed.
`completed`	The step finished successfully.
`error`	The step failed. On `split_classify`, it means the upload needs attention; check `errorReason`.

Steps

`step`	Sent when
`file_uploaded`	The file has landed in storage.
`processing_started`	The upload enters the processing queue (`waiting`), then starts (`completed`).
`fraud_detection`	An internal processing step has finished. This is not fileForensics.
`first_page_analysis`	First-page analysis has finished.
`beethoven_ocr`	OCR has finished.
`ocr_evaluation`	OCR quality checks have finished.
`split_classify`	The upload has been split into documents and classified. First event carrying `fileIds`.
`ai_form_filling`	A reprocessed document’s values are being extracted again.
`processing_finished`	All documents are processed. Carries `fileIds`.
`processing_failed`	Processing stopped with an error. Carries `errorReason` when one is known.

Async jobs

Upload status polling, and callbacks for extract, split, classify and agent jobs.

Uploads

Single, batch and multipart uploads, where you set callbackURL.

Incremental loading

Pull new and changed files on a schedule instead of reacting to events.

API quickstart

Upload a file and read its values end to end.

Get started

Products

Build

Go live

How it works

Where the callback goes

What gets sent

Example

Reference

Payload fields

Statuses

Steps

Async jobs

Uploads

Incremental loading

API quickstart

​How it works

​Where the callback goes

​What gets sent

​Example

​Reference

​Payload fields

​Statuses

​Steps

​Related

Async jobs

Uploads

Incremental loading

API quickstart

How it works

Where the callback goes

What gets sent

Example

Reference

Payload fields

Statuses

Steps

Related