{ "openapi": "3.1.0", "info": { "title": "The Finance Brokers API", "version": "1.0.0", "summary": "Read the UK commercial finance catalogue of The Finance Brokers, and submit a funding enquiry.", "description": "The Finance Brokers is a whole-of-market UK commercial finance brokerage with a panel of 300+ lenders.\n\nThis API exists so that an AI assistant answering a question about UK business or property finance can\nread our product catalogue, amount ranges and glossary directly instead of scraping the website, and so\nthat an assistant acting for a business owner can pass an enquiry to a human broker.\n\n**No authentication.** Every read endpoint is public and cacheable. There are no API keys to request.\n\n**Errors** are always JSON in the shape `{ error: { code, message, hint, docs } }`, never HTML.\n\n**Markdown**: every page on the website is also available as markdown — append `.md` to the URL, or send\n`Accept: text/markdown`. Responses vary on `Accept`.\n\n**MCP**: the read endpoints are also exposed as Model Context Protocol tools over Streamable HTTP at\n`https://www.thefinancebrokers.co.uk/api/mcp`, discoverable at `https://www.thefinancebrokers.co.uk/.well-known/mcp`.", "contact": { "name": "The Finance Brokers", "email": "ben@thefinancebrokers.co.uk", "url": "https://www.thefinancebrokers.co.uk/contact" }, "license": { "name": "Content is © The Finance Brokers; the API may be queried freely.", "url": "https://www.thefinancebrokers.co.uk/terms" }, "termsOfService": "https://www.thefinancebrokers.co.uk/terms" }, "servers": [ { "url": "https://www.thefinancebrokers.co.uk", "description": "Production" } ], "externalDocs": { "description": "Human-readable API reference", "url": "https://www.thefinancebrokers.co.uk/developers" }, "tags": [ { "name": "Catalogue", "description": "The finance products we broker, and the values the enquiry endpoint accepts." }, { "name": "Content", "description": "Guides and glossary definitions, returned as markdown." }, { "name": "Enquiries", "description": "Hand a funding enquiry to a human broker." } ], "paths": { "/api/v1/services": { "get": { "operationId": "listServices", "tags": [ "Catalogue" ], "summary": "List every finance product", "description": "Returns all eleven finance products with their published amount ranges, indicative decision times, and the `finance_type` value to use when submitting an enquiry. Use this to answer 'what kind of funding could this business get, and how much'.", "responses": { "200": { "description": "The full catalogue.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "count", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "count": { "type": "integer", "description": "Number of items in `data`. The API does not paginate." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "example": { "object": "list", "count": 11, "data": [ { "object": "service", "slug": "secured-business-loans", "title": "Secured Business Loans", "description": "Secured business loans from £25,000 to £10M against commercial property, residential investment, plant or equipment. Competitive rates from a panel of 300+ UK lenders. No upfront fees.", "category": "business", "finance_type": "Secured Business Loan", "min_amount_gbp": 25000, "max_amount_gbp": 10000000, "decision_hours": null, "url": "https://www.thefinancebrokers.co.uk/services/secured-business-loans" } ] } } } } } } }, "/api/v1/services/{slug}": { "get": { "operationId": "getService", "tags": [ "Catalogue" ], "summary": "Get one finance product", "description": "Returns a single finance product by slug. 404s with the list of valid slugs in the error `hint` if the slug is unknown.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The product identifier, as returned by listServices.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "secured-business-loans", "x-known-values": "service" } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "404": { "description": "No product with that slug. The error hint lists the valid slugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/finance-options": { "get": { "operationId": "listFinanceOptions", "tags": [ "Catalogue" ], "summary": "List the enum values the enquiry endpoint accepts", "description": "Returns the exact `finance_type` and `loan_amount` strings `submitEnquiry` will accept. Call this before submitting an enquiry so the values land as the CRM expects rather than as free text.", "responses": { "200": { "description": "The accepted values.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "finance_types", "loan_amounts" ], "properties": { "object": { "type": "string", "const": "finance_options" }, "finance_types": { "type": "array", "items": { "type": "object", "required": [ "group", "category", "values" ], "properties": { "group": { "type": "string" }, "category": { "type": "string", "enum": [ "business", "property", "other" ] }, "values": { "type": "array", "items": { "type": "string", "enum": [ "Unsecured Business Loan", "Secured Business Loan", "Invoice Finance", "Asset Finance", "VAT & Tax Loan", "Merchant Cash Advance", "Trade & Import Finance", "Bridging Refinance", "Commercial Mortgage", "Development Finance", "Property Finance", "Other" ] } } } } }, "loan_amounts": { "type": "array", "items": { "type": "string", "enum": [ "Under £25k", "£25k - £100k", "£100k - £250k", "£250k - £500k", "£500k - £1m", "£1m - £5m", "£5m+" ] } } } } } } } } } }, "/api/v1/glossary": { "get": { "operationId": "listGlossaryTerms", "tags": [ "Content" ], "summary": "List every defined finance term", "description": "Returns every commercial-finance term the site defines, with a one-paragraph definition. Use this to resolve UK lending jargon such as GDV, LTC or QS report.", "responses": { "200": { "description": "The glossary index.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "count", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "count": { "type": "integer", "description": "Number of items in `data`. The API does not paginate." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/GlossaryTerm" } } } } } } } } } }, "/api/v1/glossary/{slug}": { "get": { "operationId": "getGlossaryTerm", "tags": [ "Content" ], "summary": "Get one term's full explainer", "description": "Returns one glossary term including its full explainer as markdown in `content_markdown`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The term identifier, as returned by listGlossaryTerms.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "gdv", "x-known-values": "glossary_term" } ], "responses": { "200": { "description": "The term.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GlossaryTerm" } } } }, "404": { "description": "No term with that slug. The error hint lists the valid slugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/guides": { "get": { "operationId": "listGuides", "tags": [ "Content" ], "summary": "List the long-form guide library", "description": "Returns the guide index, newest first, with titles, descriptions, tags and dates. Bodies are fetched one at a time with getGuide.", "responses": { "200": { "description": "The guide index.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "count", "data" ], "properties": { "object": { "type": "string", "const": "list" }, "count": { "type": "integer", "description": "Number of items in `data`. The API does not paginate." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guide" } } } } } } } } } }, "/api/v1/guides/{slug}": { "get": { "operationId": "getGuide", "tags": [ "Content" ], "summary": "Get one guide's full markdown", "description": "Returns one guide including its complete body as markdown in `content_markdown`.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The guide identifier, as returned by listGuides.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "ground-up-development-finance", "x-known-values": "guide" } ], "responses": { "200": { "description": "The guide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Guide" } } } }, "404": { "description": "No guide with that slug. The error hint lists the valid slugs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/enquiry": { "post": { "operationId": "submitEnquiry", "tags": [ "Enquiries" ], "summary": "Send a funding enquiry to a human broker", "description": "Records a funding enquiry and alerts the broking team. A human replies by email, Monday to Friday, 9am to 6pm UK time.\n\nOnly submit this when the person you are acting for has asked you to make contact and has given you the\nemail address you are sending. Do not invent contact details: an enquiry we cannot reply to wastes the\nenquirer's time as well as ours. `email` is the only required field, but `finance_type`, `loan_amount`\nand a one-line `message` get a materially better first reply.\n\nNo authentication and no rate limit beyond ordinary abuse protection. Not idempotent: submitting twice\ncreates two enquiries.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryRequest" }, "example": { "name": "Jane Okafor", "email": "jane@example.co.uk", "phone": "+44 7700 900123", "finance_type": "Development Finance", "loan_amount": "£1m - £5m", "message": "Ground-up scheme of 9 units in Leeds, land owned outright, looking at a GDV of £3.4M.", "consent": true, "agent": "example-assistant/1.0" } } } }, "responses": { "201": { "description": "The enquiry was recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "status", "next_step" ], "properties": { "object": { "type": "string", "const": "enquiry" }, "status": { "type": "string", "const": "received" }, "recorded": { "type": "boolean", "description": "The enquiry was written to our CRM." }, "team_notified": { "type": "boolean", "description": "The broking team was emailed." }, "next_step": { "type": "string", "description": "What the enquirer should expect, in plain language." }, "contact": { "type": "string", "format": "email" } } }, "example": { "object": "enquiry", "status": "received", "recorded": true, "team_notified": true, "next_step": "A broker replies by email, Monday to Friday, 9am to 6pm UK time. No documents are needed to get an indication.", "contact": "ben@thefinancebrokers.co.uk" } } } }, "400": { "description": "The body was not valid JSON, or not a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "One or more fields were rejected; `error.fields` says which and why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Nothing was saved, so retrying is safe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Service": { "type": "object", "required": [ "object", "slug", "title", "description", "category", "finance_type", "url" ], "properties": { "object": { "type": "string", "const": "service" }, "slug": { "type": "string", "description": "URL-safe identifier, also the path segment on the website." }, "title": { "type": "string" }, "description": { "type": "string", "description": "The product summary as published on its page." }, "category": { "type": "string", "enum": [ "business", "property" ] }, "finance_type": { "type": "string", "enum": [ "Unsecured Business Loan", "Secured Business Loan", "Invoice Finance", "Asset Finance", "VAT & Tax Loan", "Merchant Cash Advance", "Trade & Import Finance", "Bridging Refinance", "Commercial Mortgage", "Development Finance", "Property Finance", "Other" ], "description": "The exact value to send as `finance_type` when submitting an enquiry for this product." }, "min_amount_gbp": { "type": [ "integer", "null" ], "description": "Smallest facility size in GBP, or null where no minimum is published." }, "max_amount_gbp": { "type": [ "integer", "null" ], "description": "Largest facility size in GBP, or null where no maximum is published." }, "decision_hours": { "type": [ "array", "null" ], "description": "Indicative [min, max] hours to a lender decision, or null where none is published.", "items": { "type": "integer" }, "minItems": 2, "maxItems": 2 }, "url": { "type": "string", "format": "uri" }, "markdown_url": { "type": "string", "format": "uri", "description": "The same page as clean markdown." } } }, "GlossaryTerm": { "type": "object", "required": [ "object", "slug", "term", "definition", "url" ], "properties": { "object": { "type": "string", "const": "glossary_term" }, "slug": { "type": "string" }, "term": { "type": "string", "description": "The term as it is written in the industry." }, "definition": { "type": "string", "description": "One-paragraph definition." }, "tags": { "type": "array", "items": { "type": "string" } }, "related_services": { "type": "array", "items": { "type": "string" } }, "content_markdown": { "type": "string", "description": "The full explainer in markdown. Only returned by the single-term endpoint." }, "url": { "type": "string", "format": "uri" } } }, "Guide": { "type": "object", "required": [ "object", "slug", "title", "description", "url" ], "properties": { "object": { "type": "string", "const": "guide" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "published_at": { "type": [ "string", "null" ], "format": "date" }, "updated_at": { "type": [ "string", "null" ], "format": "date" }, "related_services": { "type": "array", "items": { "type": "string" } }, "content_markdown": { "type": "string", "description": "The full guide in markdown. Only returned by the single-guide endpoint." }, "url": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint", "docs" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code.", "enum": [ "invalid_request", "invalid_json", "validation_failed", "not_found", "method_not_allowed", "rate_limited", "internal_error" ] }, "message": { "type": "string", "description": "What went wrong, in one sentence." }, "hint": { "type": "string", "description": "What to do instead." }, "docs": { "type": "string", "format": "uri", "description": "Link to the human reference." }, "fields": { "type": "array", "description": "Present on validation_failed: the specific fields that were rejected.", "items": { "type": "object", "required": [ "field", "issue" ], "properties": { "field": { "type": "string" }, "issue": { "type": "string" } } } } } } } }, "EnquiryRequest": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Where the broker replies. Must be an address the enquirer actually gave you." }, "name": { "type": "string", "maxLength": 200, "description": "The enquirer's name." }, "phone": { "type": "string", "maxLength": 40, "description": "Optional. UK numbers in any common format." }, "finance_type": { "type": "string", "enum": [ "Unsecured Business Loan", "Secured Business Loan", "Invoice Finance", "Asset Finance", "VAT & Tax Loan", "Merchant Cash Advance", "Trade & Import Finance", "Bridging Refinance", "Commercial Mortgage", "Development Finance", "Property Finance", "Other" ], "description": "The product wanted. Must be one of these exact strings; see listFinanceOptions." }, "loan_amount": { "type": "string", "enum": [ "Under £25k", "£25k - £100k", "£100k - £250k", "£250k - £500k", "£500k - £1m", "£1m - £5m", "£5m+" ], "description": "The amount band. Must be one of these exact strings; see listFinanceOptions." }, "message": { "type": "string", "maxLength": 5000, "description": "Free text. Security, timescale, and what the money is for are the three most useful facts." }, "consent": { "type": "boolean", "const": true, "description": "Set true to confirm the enquirer asked you to make contact. Omit if not applicable." }, "agent": { "type": "string", "maxLength": 120, "description": "Optional identifier for the assistant submitting, e.g. \"acme-assistant/1.2\"." } } } } } }