2. Reading documents (OCR)
From a photo or PDF to data, with the AI model of your choice.
Permissions: documents:readdocuments:extractdocuments:deletedocuments:managedocuments:scan
- 1The shop
The shop creates a document type on its screen (for example "Nota belanja", a purchase receipt), with the fields to read: number, date, total, list of items.
- 2The shop
Optional, and the most effective fix for reads that keep missing: knowledge for that document type, up to 10,000 characters. For example the abbreviations its sender uses, which column holds the price, how dates are written. The shop can write it on its screen (Asisten AI → Jenis dokumen → the type → "Pengetahuan untuk membaca dokumen ini"), or you can through the API, in the next step. Every read of that type carries it.
- 3Your system
GET /v1/document-types/{id}/knowledgeOptional: see its knowledge and the characters left. Add with POST …/knowledge/entries ({"title", "content"}), change with PUT …/knowledge/entries/{entry}, delete with DELETE (permission documents:manage). Free, no AI.
- 4Your system
POST /v1/document-types/{id}/knowledge/scans/imagesOptional, paid (permission documents:scan): send sample documents, photos or PDF, up to 8 photos or pages, in the "images" part. AI proposes knowledge; ask GET …/knowledge/scans/{scan} until succeeded, then save what you want with POST …/scans/{scan}/accept ({"items": [...]}). Nothing is saved before that.
- 5Your system
POST /v1/document-typesOr create one yourself through the API (permission documents:manage): a name, its fields (key, description, type, isNullable; a list with columns), a model if you want, "reportPages", and "reportBoxes" (mark where each value sits as a box; on when not sent, needs reportPages; switch it off to make photo reads slightly cheaper). Change it with PUT /v1/document-types/{id} (all fields are replaced; the id stays, old reads do not change), switch it off or on with PATCH {"isActive": false}.
- 6Your system
GET /v1/document-typesGet the shop's document types and their ids, with their fields.
- 7Your system
GET /v1/document-types/modelsOptional: the models that can read, per vendor, with the price of one page and whether the model reads a whole PDF or page by page. The first one is the default.
- 8Your system
POST /v1/document-types/{id}/runs/estimateOptional: send the same file to learn its cost without reading anything. "estimate" is a normal read, "most" the most expensive possible; both in rupiah.
- 9Your system
POST /v1/document-types/{id}/runsSend the file (multipart, field "file"), and if you want: "provider" and "model" together; "pages" to read only certain pages of a PDF, for example 1-3,7; "maxCharge", a cost limit in rupiah (a read that could cost more is refused 422 over_max_charge before it is read); "boxes", true or false, to switch the value-position boxes on or off for this read only, whatever the type's setting; and "clientReference". Response 202: a read with status pending, with its id.
- 10Tekomata
AI reads in the background. Done: webhook document_read.succeeded with runId. Failed: document_read.failed with the reason.
- 11Your system
GET /v1/document-types/{id}/runs/{run}Get the values and how much was charged. Each value carries "value" exactly as printed, "normalized" in one standard form for its field type ("Rp 16.650.000,00" becomes "16650000.00", "1 Oktober 2026" becomes "2026-10-01"), the model's confidence, and "pages" and "quote": every page and the text where the value was read ("page" is its first page; pages outside those sent are dropped), and "boxes": the boxes where the value is printed, one per line of text, holding "page", "x", "y", "w", "h" as fractions of the page from the top-left corner (0 to 1) and "exact". exact true means it was found in the PDF's own text, letter for letter; false means the model's estimate (a photo, a scanned PDF, or text that was not found). The image of a PDF page to place the boxes on is at GET …/runs/{run}/pages/{page} (JPEG, free); for a photo, the boxes are placed on the photo itself. "pageCount" on a PDF read is its number of pages, and "reportBoxes" on the read says whether boxes were looked for (the type's setting when it was queued, or that read's "boxes"); if false, every value's "boxes" is empty. Showing or hiding boxes you already have is up to your side: draw them or do not. "truncated" on the read means a list was cut off at its row limit.
- 12Your system
DELETE /v1/document-types/{id}/runs/{run}Optional: delete the read and its file once you have stored the data. Its cost stays recorded. Or set automatic deletion: PUT /v1/document-types/retention with {"days": 30}.
- Photos in JPG, PNG, GIF, or WebP up to 5 MB; PDFs up to 20 MB. Pages per document at most the shop's limit: 50 if unchanged, up to 500 through PUT /v1/document-types/limits. A model that reads a whole PDF ("readsPdf") takes a PDF of up to 100 pages in one call when "pages" is not sent. Otherwise the PDF is read as images in parts of 50 pages (20 for a type with a list) and then merged: single values from the most confident part, list rows in order. Each part is charged its tokens, the per-read price once. Read only part of it with "pages".
- The list of reads (GET …/runs) holds only a summary: id, file name, status, model (provider/model) and time. The values and the cost are in GET …/runs/{run}.
- In the sandbox (a developer's local copy, not tekomata.com) read results are made up, free, and not stored: they do not appear in the list, and the checks of a real read (a switched-off type, the page limit, a broken PDF, a 5 MB photo) are skipped.
- Want to decide the thousands separator or date format yourself? Use "value", the text exactly as printed, or make the field a text type.
- The content type of a field (text, number, money, date, yes/no, choice) is set by the shop on its screen. Numbers are read the Indonesian way: 1.250 is one thousand two hundred and fifty.
- A model that cannot read here is refused 422 model_not_offered before anything is sent. An insufficient balance is refused 402.
- AI uses a document type's knowledge as a reference, never copied in as a value: values are still only what is printed on the document. If a type keeps misreading something, add one line there. Scans are limited to 20 per shop per day, and in the sandbox their results are made up, free, and not stored. Because it is sent with every read, long knowledge adds a little token cost to each read, already counted in estimate and maxCharge.
- Correcting a read's values and proposing a document type from samples still happen on the shop's screen.