{ "openapi": "3.1.1", "info": { "title": "Form Translator API", "version": "1.0.0", "summary": "Plain-language help for confusing forms: field-by-field hints and jargon explained.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://formtranslator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Plain-language help for confusing forms: field-by-field hints and jargon explained.", "description": "Paste or upload (incl. photo/OCR) an official, insurance or tax form in English or German. Form Translator detects the fields, recognises what kind of entry each needs (date, signature, checkbox, IBAN, tax ID …), explains jargon from a curated glossary of 160 terms and lists the documents you will probably need.\n\nMethodology:\n- Lines are scanned for field labels: \"Label:\" followed by blanks, labels next to fill lines (____ or ....), checkbox options (☐, □, [ ], ( )) and short label-only lines that contain a field keyword.\n- Each label is classified with keyword rules into field types (date, signature, checkbox, IBAN/bank, tax ID, ID/reference number, e-mail, phone, address, name, amount, marital status, nationality, place+date), each with a fixed fill-in hint.\n- Jargon is matched against an editorial glossary (160 English and German admin, tax, insurance, benefits, banking and legal terms incl. inflected German forms). Explanations are written by usefulweb.site editors, not generated.\n- Documents are listed when a sentence asks to attach/enclose/provide proof (beifügen, Nachweis, Kopie, Bescheinigung …), quoted verbatim, plus documents commonly requested for recognised glossary terms (marked as such).\n- IBANs found in the text are checked with the ISO 13616 mod-97 checksum (German IBANs must have 22 characters). A valid checksum does not prove the account exists.\n\nNot legal, tax or insurance advice. Explanations are editorial plain-language summaries for orientation and may not match the exact legal meaning in your country, contract or authority. The detection is rule-based and never complete; when in doubt, ask the issuing office.", "tags": [ "everyday" ], "x-mcp-tool": "form_translator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormTranslatorInput" }, "examples": { "example1": { "summary": "German Kindergeld-style application", "value": { "text": "Antrag auf Kindergeld\n\n1. Angaben zur antragstellenden Person\nName, Vorname: ______________________\nGeburtsdatum (TT.MM.JJJJ): __________\nSteuer-ID: ___________\nAnschrift (Straße, Hausnummer, PLZ, Ort): ____________________\nFamilienstand:\n☐ ledig ☐ verheiratet ☐ geschieden ☐ verwitwet\n\n2. Angaben zum Ehegatten / eingetragenen Lebenspartner\nName, Vorname: ______________\n\n3. Bankverbindung\nIBAN: DE89 3704 0044 0532 0130 00\nKontoinhaber: ______________\n\nBitte fügen Sie eine Kopie der Geburtsurkunde und ggf. eine Schulbescheinigung bei.\nIch versichere, dass meine Angaben vollständig und richtig sind.\nOrt, Datum: ____________ Unterschrift: ________________" } }, "example2": { "summary": "US health insurance enrollment", "value": { "text": "Health Plan Enrollment Form\n\nPolicyholder name: ____________\nDate of birth (MM/DD/YYYY): ________\nSocial Security Number: ___-__-____\nMarital status: [ ] Single [ ] Married [ ] Divorced\nDependents (name, DOB, relationship): ______________\nPrimary beneficiary: ______________\n\nPlan options: The Silver plan has a $2,000 deductible, 20% coinsurance and a $30 copay for primary care visits.\nDo you have a pre-existing condition? [ ] Yes [ ] No\n\nPlease attach a copy of your ID and proof of address.\nSignature of applicant: ______________ Date: ________" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormTranslatorResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "FormTranslatorInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Form text", "description": "Paste the form text (labels and instructions), or upload a PDF/DOCX/photo below.", "type": "string", "maxLength": 200000 }, "file": { "title": "Or upload a file", "description": "TXT, PDF, DOCX, HTML or a photo/scan (PNG/JPG, read with OCR). Max 5 MiB. Upload as {filename, contentType?, contentBase64}. Max 5120 KiB. Accepts .txt,.pdf,.docx,.png,.jpg,.jpeg,.html.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } } }, "required": [] }, "FormTranslatorResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "disclaimer", "editorialNote", "confidence", "fields", "glossaryHits", "documentsNeeded", "ibanChecks", "glossarySize" ], "properties": { "disclaimer": { "type": "string" }, "editorialNote": { "type": "string" }, "confidence": { "type": "string", "const": "pattern-match" }, "glossarySize": { "type": "integer", "minimum": 0 }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "label", "line", "fieldTypes", "hint", "glossaryTerms" ], "properties": { "label": { "type": "string", "description": "Field label exactly as found in the form text." }, "line": { "type": "integer", "minimum": 1 }, "fieldTypes": { "type": "array", "items": { "type": "string" } }, "hint": { "type": "string", "description": "Editorial fill-in hint." }, "glossaryTerms": { "type": "array", "items": { "type": "string" } } } } }, "glossaryHits": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "term", "matched", "language", "domain", "explanation", "occurrences" ], "properties": { "term": { "type": "string" }, "matched": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string", "enum": [ "en", "de" ] }, "domain": { "type": "string" }, "explanation": { "type": "string", "description": "Editorial plain-language explanation." }, "hint": { "type": "string" }, "occurrences": { "type": "integer", "minimum": 1 } } } }, "documentsNeeded": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "item", "basis", "rule" ], "properties": { "item": { "type": "string" }, "basis": { "type": "string", "enum": [ "quoted from form", "commonly requested (glossary)" ] }, "rule": { "type": "string" } } } }, "ibanChecks": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "iban", "checksumValid" ], "properties": { "iban": { "type": "string" }, "checksumValid": { "type": "boolean" } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }