{"openapi":"3.1.0","info":{"title":"Digitizer API","version":"1.1.0","description":"Digitizer converts business documents into structured fields, line items, and review-ready results."},"servers":[{"url":"https://digitizer.ee"}],"tags":[{"name":"Documents","description":"Upload, retrieve, list, and delete normalized document results."},{"name":"Jobs","description":"Track documents submitted through batch uploads."},{"name":"Metadata","description":"Discover the schema and inspect business usage."},{"name":"Callbacks","description":"Connect a business to your software with signed document notifications."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Party":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"registry_code":{"type":["string","null"]},"vat_id":{"type":["string","null"]},"address":{"type":["string","null"]},"document_address":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"city":{"type":["string","null"]},"county":{"type":["string","null"]},"country":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":[],"additionalProperties":false},"LineItem":{"type":"object","properties":{"description":{"type":["string","null"]},"code":{"type":["string","null"],"description":"Item or service code; distinct from barcode identifiers."},"ean":{"type":["string","null"],"description":"Barcode identifier when present. Leading zeros are preserved."},"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"unit_price":{"type":["number","null"],"description":"Gross unit price before line discounts. Unit prices may retain more precision than currency totals."},"net_unit_price":{"type":["number","null"],"description":"Net unit price before line discounts. Printed unit prices are preserved."},"discount_percent":{"type":["number","null"],"description":"Percentage points: 20 means 20%."},"discount_amount":{"type":["number","null"],"description":"Line discount amount when available; derived net discounts are expressed before tax."},"subtotal":{"type":["number","null"],"description":"Net line amount after line discounts."},"vat_rate":{"type":["number","null"],"description":"Percentage points: 20 means 20%. Null when unknown or ambiguous."},"vat_amount":{"type":["number","null"],"description":"Line tax in document currency. May include a minor-unit adjustment to match a printed tax-group total."},"total":{"type":["number","null"],"description":"Gross line amount after line discounts."},"amount":{"type":["number","null"],"deprecated":true,"description":"Always aliases total, including null. Prefer subtotal and total."}},"required":[],"additionalProperties":false},"DocumentFields":{"type":"object","properties":{"document_number":{"type":["string","null"]},"issue_date":{"description":"Document date in YYYY-MM-DD format. Review fields flagged as uncertain.","type":["string","null"]},"due_date":{"type":["string","null"],"description":"ISO 8601 date"},"currency":{"type":["string","null"],"description":"ISO 4217 code"},"subtotal":{"type":["number","null"]},"vat_amount":{"type":["number","null"]},"rounding":{"type":["number","null"],"description":"Rounding adjustment applied to reach the total."},"total":{"type":["number","null"]},"amount_due":{"type":["number","null"]},"vat_rates":{"type":["array","null"],"description":"VAT amounts grouped by percentage. An unknown or ambiguous percentage is null.","items":{"type":"object","properties":{"rate":{"type":["number","null"]},"net":{"type":["number","null"]},"vat":{"type":["number","null"]},"gross":{"type":["number","null"]}}}},"vendor":{"$ref":"#/components/schemas/Party"},"customer":{"$ref":"#/components/schemas/Party"},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"banks":{"type":["array","null"],"description":"Every bank printed for payment, each with its account.","items":{"type":"object","properties":{"name":{"type":["string","null"]},"iban":{"type":["string","null"]},"swift_bic":{"type":["string","null"]}}}},"account_number":{"type":["string","null"]},"previous_balance":{"type":["number","null"]},"payments_credits":{"type":["number","null"]},"service_address":{"type":["string","null"]},"consumption":{"type":["object","null"],"properties":{"unit":{"type":["string","null"]},"value":{"type":["number","null"]}}},"payment":{"type":["object","null"],"description":"Card or cash payment details, when printed.","properties":{"method":{"type":["string","null"],"enum":["card","cash","transfer","other",null]},"card_number":{"type":["string","null"]},"card_last4":{"type":["string","null"]},"auth_code":{"type":["string","null"]},"reference":{"type":["string","null"]},"receipt_number":{"type":["string","null"],"description":"Printed card-payment/terminal receipt number, distinct from the sales document number and bank reference."},"amount":{"type":["number","null"],"description":"Payment applied to the transaction; for cash with returned change, tendered minus change."},"tendered":{"type":["number","null"],"description":"Printed cash handed over, before returned change."},"change":{"type":["number","null"],"description":"Printed cash returned to the customer."}}}},"required":["line_items"],"additionalProperties":false},"DocumentSummary":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"type":{"const":"document"},"status":{"enum":["processed","failed"]},"pages":{"type":"integer"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Indicative confidence score, not a probability or guarantee of accuracy. Use field_status and review_fields for review decisions."},"created_at":{"type":"string","format":"date-time"},"processing_ms":{"type":"integer"},"duplicates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"reasons":{"type":"array","items":{"enum":["file","image","data"]}}},"required":["id","filename","reasons"],"additionalProperties":false}}},"required":["id","filename","content_type","size_bytes","type","status","pages","confidence","created_at","processing_ms"],"additionalProperties":false},"Region":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"box":{"type":"array","items":{"type":"number","minimum":0,"maximum":1000},"minItems":4,"maxItems":4,"description":"[x0,y0,x1,y1], page-relative coordinates on a 0?1000 scale."},"normalized_value":{"type":["string","number"]}},"required":["page","box"],"additionalProperties":false},"FieldStatus":{"type":"object","properties":{"status":{"enum":["read","derived","review","enriched"]},"review":{"type":"boolean"}},"required":["status","review"],"additionalProperties":false},"Document":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"type":{"const":"document"},"status":{"enum":["processed","failed"]},"pages":{"type":"integer"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Indicative confidence score, not a probability or guarantee of accuracy. Use field_status and review_fields for review decisions."},"created_at":{"type":"string","format":"date-time"},"processing_ms":{"type":"integer"},"duplicates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"reasons":{"type":"array","items":{"enum":["file","image","data"]}}},"required":["id","filename","reasons"],"additionalProperties":false}},"is_document":{"type":"boolean"},"extraction":{"$ref":"#/components/schemas/DocumentFields"},"field_confidence":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":1},"description":"Available field scores, keyed by paths such as vendor.name or line_items[0].subtotal. Scores are indicative, not calibrated probabilities."},"field_status":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FieldStatus"},"description":"Available field outcomes. Derived means calculated; review means the value needs checking."},"review_fields":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"regions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Region"},"description":"Located values keyed by field path, when regions=true. Calculated fields may have no location. Multi-part fields use one enclosing box."},"raw_text":{"type":"string","description":"Document text, included when raw_text=true and available."}},"required":["id","filename","content_type","size_bytes","type","status","pages","confidence","created_at","processing_ms","is_document","extraction","field_confidence","field_status","review_fields","warnings"],"additionalProperties":false},"PublicError":{"type":"object","properties":{"code":{"type":"string","enum":["billing_details_required","quota_exceeded","api_billing_required","api_custom_plan_required","missing_api_key","invalid_api_key","invalid_request","unsupported_media_type","file_too_large","too_many_pages","pdf_unreadable","pdf_password_required","not_found","rate_limited","service_unavailable","processing_failed","internal_error"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"ErrorEnvelope":{"type":"object","properties":{"success":{"const":false},"error":{"$ref":"#/components/schemas/PublicError"}},"required":["success","error"],"additionalProperties":false},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["queued","processing","succeeded","failed"]},"type":{"const":"document"},"document_id":{"type":["string","null"]},"error":{"anyOf":[{"$ref":"#/components/schemas/PublicError"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","status","type","document_id","error","created_at","updated_at"],"additionalProperties":false},"BatchAccepted":{"type":"object","properties":{"id":{"type":"string"},"status":{"const":"queued"},"document_ids":{"type":"array","items":{"type":"string"}},"job_ids":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","document_ids","job_ids","count","created_at"],"additionalProperties":false},"DocumentList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummary"}},"count":{"type":"integer"},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"]}},"required":["limit","next_cursor"],"additionalProperties":false}},"required":["items","count","pagination"],"additionalProperties":false},"Deletion":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"const":true}},"required":["id","deleted"],"additionalProperties":false},"DocumentTypes":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"const":"document"},"label":{"type":"string"},"fields":{"type":"integer"}},"required":["id","label","fields"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},"FieldMetadata":{"type":"object","properties":{"type":{"const":"document"},"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"type":{"enum":["string","number","boolean","date","object","array"]},"nullable":{"type":"boolean"},"description":{"type":"string"}},"required":["type","nullable","description"],"additionalProperties":false}}},"required":["type","fields"],"additionalProperties":false},"Callback":{"type":"object","properties":{"url":{"type":"string"},"enabled":{"type":"boolean"},"updated_at":{"type":["string","null"]},"signing_secret":{"type":"string","description":"Only returned on initial setup or secret rotation."},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"document_id":{"type":"string"},"status":{"enum":["queued","sending","delivered","failed","cancelled"]},"attempts":{"type":"integer"},"last_http_status":{"type":["integer","null"]},"last_error":{"type":["string","null"]},"created_at":{"type":"string"},"delivered_at":{"type":["string","null"]}},"required":["id","document_id","status","attempts","last_http_status","last_error","created_at","delivered_at"],"additionalProperties":false}}},"required":["url","enabled","updated_at","deliveries"],"additionalProperties":false},"CallbackEvent":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"document.processed"},"created_at":{"type":"string"},"business_id":{"type":"string"},"source":{"type":"object","properties":{"channel":{"enum":["api","email","dashboard"]},"email_id":{"type":"string"}},"required":["channel"],"additionalProperties":false},"data":{"$ref":"#/components/schemas/Document"}},"required":["id","type","created_at","business_id","source","data"],"additionalProperties":false},"Usage":{"type":"object","properties":{"documents":{"type":"integer"},"pages":{"type":"integer"},"by_type":{"type":"object","additionalProperties":{"type":"integer"}},"last_request_at":{"type":["string","null"],"format":"date-time"}},"required":["documents","pages","by_type","last_request_at"],"additionalProperties":false}}},"paths":{"/api/v1/documents":{"post":{"operationId":"create-document","summary":"Extract a document","description":"Upload a PDF or image and receive normalized document data synchronously. Multipart file uploads and base64 JSON are supported. If multiple files or pages entries are supplied, only the first is processed; meta.ignored_files reports the rest. Use the batch endpoint for multiple documents.","tags":["Documents"],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"file":{"type":"string","format":"binary"}},"required":["file"],"additionalProperties":false}},"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"content":{"type":"string","contentEncoding":"base64"},"content_type":{"type":"string","default":"image/png"},"filename":{"type":"string"}},"required":["content"],"additionalProperties":false},{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"pages":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string","contentEncoding":"base64"},"content_type":{"type":"string","default":"image/png"},"filename":{"type":"string"}},"required":["content"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["pages"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"A document with normalized fields, line items, review status, and optional field locations and document text.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Document"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"id":"doc_example","filename":"invoice-1042.pdf","content_type":"application/pdf","size_bytes":48320,"type":"document","status":"processed","is_document":true,"pages":1,"confidence":0.96,"created_at":"2026-09-22T09:12:44Z","processing_ms":2841,"extraction":{"document_number":"INV-1042","issue_date":"2026-08-02","currency":"USD","subtotal":4200,"vat_amount":420,"total":4620,"vat_rates":[{"rate":10,"net":4200,"vat":420,"gross":4620}],"vendor":{"name":"Northwind Supply Co."},"line_items":[{"description":"Maintenance service","code":"SVC-1042","ean":null,"quantity":2,"unit":"hour","net_unit_price":2100,"unit_price":2310,"discount_percent":null,"discount_amount":null,"subtotal":4200,"vat_rate":10,"vat_amount":420,"total":4620,"amount":4620}]},"field_confidence":{"document_number":0.99},"field_status":{"document_number":{"status":"read","review":false},"line_items[0].total":{"status":"derived","review":false}},"review_fields":[],"warnings":[]},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"operationId":"list-documents","summary":"List documents","description":"Browse the complete document history for this API key, newest first. Pages contain up to 100 documents; follow next_cursor using the same search and filter until it is null. Limit defaults to 25.","tags":["Documents"],"parameters":[{"name":"limit","in":"query","required":false,"description":"Results per page, 1-100. Default: 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"Opaque next_cursor from the previous page. Omit for the first page.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Case-insensitive filename search across all history; maximum 254 characters.","schema":{"type":"string"}},{"name":"filter","in":"query","required":false,"description":"all (default), review, or duplicates. Applies across all history.","schema":{"type":"string"}}],"responses":{"200":{"description":"Document summaries, count, and pagination metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/DocumentList"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"items":[{"id":"doc_example","filename":"invoice-1042.pdf","content_type":"application/pdf","size_bytes":48320,"type":"document","status":"processed","pages":1,"confidence":0.96,"created_at":"2026-09-22T09:12:44Z","processing_ms":2841}],"count":1,"pagination":{"limit":25,"next_cursor":null}},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/documents/batch":{"post":{"operationId":"create-batch","summary":"Create extraction batch","description":"Submit up to 100 documents. The response is HTTP 202 with job ids; poll each job, then fetch its document_id. There is no separate batch polling endpoint. JSON pages entries represent independent documents, not pages to combine.","tags":["Documents"],"parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"files":{"type":"array","items":{"type":"string","format":"binary"},"minItems":1,"maxItems":100}},"required":["files"],"additionalProperties":false}},"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"content":{"type":"string","contentEncoding":"base64"},"content_type":{"type":"string","default":"image/png"},"filename":{"type":"string"}},"required":["content"],"additionalProperties":false},{"type":"object","properties":{"hints":{"type":"string"},"raw_text":{"type":"boolean","default":false},"regions":{"type":"boolean","default":false},"pages":{"type":"array","items":{"type":"object","properties":{"content":{"type":"string","contentEncoding":"base64"},"content_type":{"type":"string","default":"image/png"},"filename":{"type":"string"}},"required":["content"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["pages"],"additionalProperties":false}]}}}},"responses":{"202":{"description":"A batch acceptance receipt with job ids in upload order.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/BatchAccepted"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"id":"bat_example","status":"queued","document_ids":[],"job_ids":["job_example"],"count":1,"created_at":"2026-09-22T09:12:44Z"},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/documents/{document_id}":{"get":{"operationId":"get-document","summary":"Get document","description":"Retrieve the stored document result. Optional locations and text are available only if requested at upload.","tags":["Documents"],"parameters":[{"name":"document_id","in":"path","required":true,"description":"Document id returned by extraction.","schema":{"type":"string"}}],"responses":{"200":{"description":"The document result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Document"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"id":"doc_example","filename":"invoice-1042.pdf","content_type":"application/pdf","size_bytes":48320,"type":"document","status":"processed","is_document":true,"pages":1,"confidence":0.96,"created_at":"2026-09-22T09:12:44Z","processing_ms":2841,"extraction":{"document_number":"INV-1042","issue_date":"2026-08-02","currency":"USD","subtotal":4200,"vat_amount":420,"total":4620,"vat_rates":[{"rate":10,"net":4200,"vat":420,"gross":4620}],"vendor":{"name":"Northwind Supply Co."},"line_items":[{"description":"Maintenance service","code":"SVC-1042","ean":null,"quantity":2,"unit":"hour","net_unit_price":2100,"unit_price":2310,"discount_percent":null,"discount_amount":null,"subtotal":4200,"vat_rate":10,"vat_amount":420,"total":4620,"amount":4620}]},"field_confidence":{"document_number":0.99},"field_status":{"document_number":{"status":"read","review":false},"line_items[0].total":{"status":"derived","review":false}},"review_fields":[],"warnings":[]},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"delete-document","summary":"Delete document","description":"Remove a document and its extraction from the business. This cannot be undone.","tags":["Documents"],"parameters":[{"name":"document_id","in":"path","required":true,"description":"Document id to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"The deleted id and deleted=true.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Deletion"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"id":"doc_example","deleted":true},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"operationId":"get-job","summary":"Get job status","description":"Poll a batch job no faster than once per second. Status is queued, processing, succeeded, or failed. On success, fetch document_id; on failure, inspect error.code.","tags":["Jobs"],"parameters":[{"name":"job_id","in":"path","required":true,"description":"Job id from the batch response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Job status and result id or error.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Job"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"id":"job_example","status":"succeeded","type":"document","document_id":"doc_example","error":null,"created_at":"2026-09-22T09:12:44Z","updated_at":"2026-09-22T09:12:48Z"},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/metadata/document-types":{"get":{"operationId":"list-document-types","summary":"List document types","description":"Invoices, receipts, bills, and similar documents share the document type and one schema.","tags":["Metadata"],"parameters":[],"responses":{"200":{"description":"Supported document types and field counts.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/DocumentTypes"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"items":[{"id":"document","label":"Document","fields":20}]},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/metadata/fields":{"get":{"operationId":"list-fields","summary":"List extractable fields","description":"Get top-level field names, data types, nullability, and descriptions. Nested field schemas are defined in /openapi.json.","tags":["Metadata"],"parameters":[{"name":"type","in":"query","required":false,"description":"Only document is supported; default: document.","schema":{"type":"string","enum":["document"],"default":"document"}}],"responses":{"200":{"description":"The selected type and its field definitions.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/FieldMetadata"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"type":"document","fields":{"document_number":{"type":"string","nullable":true,"description":"Invoice, bill or receipt identifier."},"issue_date":{"type":"date","nullable":true,"description":"Document date, ISO 8601."},"due_date":{"type":"date","nullable":true,"description":"Payment due date."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code."},"subtotal":{"type":"number","nullable":true,"description":"Net of VAT."},"vat_amount":{"type":"number","nullable":true,"description":"Total VAT."},"rounding":{"type":"number","nullable":true,"description":"Rounding adjustment applied to reach the total."},"total":{"type":"number","nullable":true,"description":"Gross amount printed."},"amount_due":{"type":"number","nullable":true,"description":"Unpaid balance."},"vat_rates":{"type":"array","nullable":true,"description":"VAT per rate: rate, net, vat, gross."},"vendor":{"type":"object","nullable":true,"description":"Issuing party."},"customer":{"type":"object","nullable":true,"description":"Billed party."},"line_items":{"type":"array","nullable":false,"description":"Line item rows: description, code, ean, quantity, unit, gross unit_price, net_unit_price, discount_percent, discount_amount, subtotal, vat_rate, vat_amount, total. amount is a deprecated alias of total."},"banks":{"type":"array","nullable":true,"description":"Every bank printed for payment: name, iban, swift_bic."},"account_number":{"type":"string","nullable":true,"description":"Customer account number."},"previous_balance":{"type":"number","nullable":true,"description":"Balance carried forward."},"payments_credits":{"type":"number","nullable":true,"description":"Payments and credits applied."},"service_address":{"type":"string","nullable":true,"description":"Address the service applies to."},"consumption":{"type":"object","nullable":true,"description":"unit and value for metered documents."},"payment":{"type":"object","nullable":true,"description":"Payment: method, card_number, card_last4, auth_code, reference, receipt_number, amount, tendered, change."}}},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/usage":{"get":{"operationId":"get-usage","summary":"Get usage","description":"Return all-time processing usage for the current business from its durable ledger, including usage for deleted documents. Legacy configured API keys report retained documents without a history cap.","tags":["Metadata"],"parameters":[],"responses":{"200":{"description":"Business document counts, page counts, and last successful processing time.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Usage"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"documents":128,"pages":143,"by_type":{"document":128},"last_request_at":"2026-09-22T09:12:44Z"},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/callback":{"get":{"operationId":"get-callback","summary":"Get callback settings","description":"Returns the current business callback and latest 20 deliveries. Signing secrets are never returned by GET.","tags":["Callbacks"],"parameters":[],"responses":{"200":{"description":"Callback settings and delivery status.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Callback"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"url":"","enabled":false,"updated_at":null,"deliveries":[]},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"operationId":"set-callback","summary":"Configure a callback","description":"Configure one optional public HTTPS callback per business. Applies to new documents from API, dashboard, and approved email attachments. Read /docs/callbacks for signature verification and retries. Changing configuration cancels pending deliveries.","tags":["Callbacks"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"enabled":{"type":"boolean"},"rotate_secret":{"type":"boolean","default":false}},"required":["url","enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated settings; signing_secret is returned only on first setup or rotation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/Callback"},"meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string"}},"additionalProperties":true}},"required":["success","data","meta"],"additionalProperties":false},"example":{"success":true,"data":{"url":"https://software.example.com/webhook","enabled":true,"updated_at":"2026-09-22T12:00:00Z","deliveries":[],"signing_secret":"whsec_example_only"},"meta":{"request_id":"req_example"}}}}},"400":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Request failed; inspect error.code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}