Guides

Uploading documents

Send a document as multipart/form-data to POST /v1/documents. Processing starts straight away in the background.

Field	Required	Description
`file`	Yes	PDF (digital or scanned), PNG or JPEG, up to 50 MB. The type is checked from the file itself.
`company_name`	No	The company the report belongs to. Used to compare with the previous year's report.
`fiscal_year`	No	The financial year the report covers, e.g. 2024.
`template`	No	`general` (companies) or `bank`. Detected from the statements if not given.
`external_ref`	No	Your own reference, e.g. the document's ID in your system. Returned everywhere, including webhooks.

bash

curl https://api.genni.scribblegreen.com/v1/documents \
  -H "Authorization: Bearer $GENNI_KEY" \
  -F file=@zenith-2024.pdf -F company_name="Zenith Bank Plc" -F fiscal_year=2024 \
  -F external_ref=doc-8841

The response is the new document with status: "uploaded" and a job_id.

Uploading the same file twice

Genni fingerprints every file. Uploading an identical file again returns the existing document with duplicate: true and status 200 instead of 201, so retrying an upload is always safe.

What happens next

Genni reads every page and finds the primary statements: financial position, profit or loss, comprehensive income, cash flows and changes in equity. Contents pages, notes and five-year summaries are skipped.
Scanned pages are read from their images.
Each statement is transcribed line by line and mapped to the template.
Accounting checks run, and the document becomes completed or in_review.

Check GET /v1/documents/{id} for progress. Its statement_pages shows where each statement was found, e.g. {"financial_position": [23], "cash_flows": [26]}.

Call	What it does
`GET /v1/documents`	List documents (filter by status; paginate with limit and offset).
`GET /v1/documents/{id}/pages/{n}/image`	A page as a PNG, e.g. to show a figure beside its source.
`POST /v1/documents/{id}/process`	Run processing again. Needs force=true if people have already reviewed it.
`DELETE /v1/documents/{id}`	Delete the file and everything extracted from it.

Uploading documents

Uploading the same file twice

What happens next

Other document calls