Extractions

Two things share the word "extraction", and the API separates them.

A project is the container

A project — POST /extractions — is where documents and their results live. It carries a model (the schema that says what to extract), an owner who can open it in the UI, and a history of runs. In the product it is called an extraction; the API keeps the resource name /extractions.

Creating one through the API defaults to isQuick: true, which auto-scaffolds the model and a single data group so you can upload and run immediately. Set isQuick: false to clone a template model (sourceModuleId) or attach an existing one (moduleId) instead — the three are mutually exclusive. Projects created either way appear in GET /extractions; narrow with ?isQuick=.

ownerUserId names the human who owns the project. Omit it and the user who created your API key becomes the owner.

A session is one run

An extraction session — POST /extraction-sessions — runs the project's schema over its documents once. It returns a job handle; poll GET /jobs/{jobId} or subscribe to the extraction.* webhooks for the outcome, then read GET /extraction-sessions/{id}/results.

A session only starts when every target document is processed. While any is still uploaded or processing the call answers 202 with { status: "pending", documentsReady, documentsTotal } and does not start — re-POST to poll. If any document is failed, it answers 422 naming the failed ids; re-process them with POST /documents/process first.

The lifecycle, end to end

1. Create a project.
2. Upload documents to it, then process them.
3. Create a session. Wait for extraction.completed or poll the job.
4. Review and correct results on the validation surface.
5. Promote what is correct into the data mart.

Steps 4 and 5 are optional for a headless integration that trusts the extraction as-is: promote with { all: true } straight after the session completes.