Demo 04 · Via the API

ForkLabs Doc Extract API

Send a document, get structured fields with a status for each value. This page is generated from openapi.json.

The demo key only works on the sample documents.

Try it

Sample document

curl -X POST "https://your-demo-site/api/v1/extract" \
  -H "X-Api-Key: fl-demo-1a5e3ecbd357a4f5" \
  -H "Content-Type: application/json" \
  -d '{"sample_id": "<sample_id>"}'

Endpoints

post/v1/extract

Extract a sample document

Returns the precomputed pipeline result for one sample document. The demo key only works on the sample documents.

Header: X-Api-Key

Request body

Field	Type	Description
sample_id*	string	One of the sample document ids.

Responses

200 The extraction result. SampleResult
400 The body is not {"sample_id": "<id>"}. Error
401 Missing or wrong X-Api-Key. Error
404 There is no sample with that id. Error

get/jobs/{id}

Get a job

Status of a document uploaded with an invite, and its result once done. Jobs and results are deleted automatically within 24 hours.

Parameters

id (path, string, required) The job id.

Responses

200 Job status, with the result when it is done. Job
404 The job does not exist or has been deleted. Error

Schemas

Field

One extracted value. Money travels as decimal strings.

Field	Type	Description
raw*	string \| null	Exactly as printed on the document.
value*	string \| null	Normalized value (decimal string for amounts, ISO date for dates).

LineItem

Field	Type	Description
description*	Field
quantity*	Field
unit_price*	Field
line_total*	Field
category*	string \| null

Header

Field	Type	Description
vendor_name*	Field
vendor_address*	Field
vendor_tax_id*	Field
customer_name*	Field
number*	Field
issue_date*	Field
due_date*	Field
currency*	Field
subtotal*	Field
discount*	Field
tax_total*	Field
tax_rate*	Field
shipping*	Field
grand_total*	Field
payment_terms*	Field

Extraction

Field	Type	Description
doc_type*	"invoice" \| "receipt"
header*	Header
items*	LineItem[]
custom*	map<string, Field>	Custom fields by name.

Box

Bounding box as fractions (0-1) of the page size.

Field	Type	Description
page*	integer	Zero-based page index.
x0*	number
y0*	number
x1*	number
y1*	number

FieldResult

Field	Type	Description
path*	string	header.<name>, items[<i>].<name> or custom.<name>.
status*	"verified" \| "check" \| "missing"
reason*	string \| null	Why the field needs a check, in plain words.
boxes*	Box[]
rechecked*	boolean	True when a second model re-read this field.

Result

Field	Type	Description
extraction*	Extraction
fields*	map<string, FieldResult>	Status per field path.
pages*	integer
cost_usd*	string \| number	Decimal serialized by the backend.
models*	string[]

SampleResult

Includes everything in Result.

Field	Type	Description
sample_id	string
file	string	Path of the sample document.
tags	string[]
duplicate_of	string \| null

ExtractRequest

Field	Type	Description
sample_id*	string	One of the sample document ids.

Job

Field	Type	Description
status*	string	For example queued, processing, done or failed.
error_code	string
error_message	string
result	Result

Error

Field	Type	Description
code*	string
message*	string