{ "openapi": "3.0.3", "info": { "title": "Mintly EISCD API", "termsOfService": "https://www.mintly.uk/terms", "contact": { "email": "support@mintly.uk" }, "version": "1.1.0", "description": "The Mintly EISCD API gives your application direct access to the Extended\nIndustry Sort Code Directory — the reference database of UK sort codes. With\na subscription you can download the complete directory in your choice of\nformat, or fetch just the weekly changes.\n\nThe API is RESTful, using predictable, resource-oriented URLs with standard\nHTTP methods and status codes. It is OpenAPI 3.0 compliant, so it integrates\ncleanly with any tooling that understands the OpenAPI standard.\n\nQuestions? Email us at [support@mintly.uk](mailto:support@mintly.uk).\n\n## Authentication\n\nEvery request must carry an `X-API-KEY` header set to your organisation's\nunique key. Keep this secret.\n\n```\nX-API-KEY: YOUR_API_KEY\n```\n\n## Environment\n\nProduction is at `https://api.mintly.uk/eiscd`. There is no sandbox\nenvironment for this API.\n\nNew EISCD data files are published **every Friday from 12:00 GMT**, and the\ndata should be treated as valid from the following Monday.\n\n## Status codes\n\nWe use standard HTTP status codes, including but not limited to:\n\n| Status | Meaning |\n|---|---|\n| `200` OK | The request succeeded. |\n| `400` Bad request | Something was wrong with the request. Check the error message in the response. |\n| `401` Unauthorised | Your credentials are invalid or have expired. |\n| `403` Forbidden | Authentication failed — the key has expired, or no key was provided. |\n| `429` Too many requests | You have exceeded the rate limit. Wait, then retry. |\n| `500` Server error | Something went wrong on our side — get in touch so we can look into it. |\n\n## Backwards compatibility\n\nThe API is designed to be backwards compatible, so changes should not\ndisrupt existing integrations. We follow\n[semantic versioning](https://semver.org) for API releases. Build your\nintegration to handle non-breaking changes gracefully. If a breaking change\never becomes necessary, we will give advance notice and a clear migration\npath, and keep the existing version available for a defined deprecation\nperiod.\n\n## AI agent skill\n\nInstall the Mintly EISCD agent skill for AI-assisted integration help inside\nyour editor. Once installed, invoke `/eiscd-api` to generate client code,\nprocess delta files, and schedule automated data syncs.\n\n**[Download the agent skill](https://www.mintly.uk/assets/eiscd-api-skill.zip)**\n\nBuilt on the [Agent Skills open standard](https://agentskills.io/clients),\nit works with Claude Code, VS Code (GitHub Copilot), OpenAI Codex, Cursor,\nGemini CLI, and many more.\n" }, "externalDocs": { "description": "Find out more about Mintly", "url": "https://www.mintly.uk" }, "servers": [ { "url": "https://api.mintly.uk/eiscd", "description": "Production" } ], "tags": [ { "name": "Base", "description": "The base EISCD, offering a complete snapshot of the data. Base EISCD files are available in tab delimited (TXT), Comma Separated Value (CSV), XML or Excel (XLSX) format. Use the GET endpoint for the file format you require.\n" }, { "name": "Delta", "description": "The weekly changes to the EISCD. This file is only available in tab delimited (TXT) format. Contains all the changes since the last base file. Changes are available once per week.\n" } ], "x-tagGroups": [ { "name": "EISCD data files", "tags": [ "Base", "Delta" ] } ], "paths": { "/delta-files/{year}/{week}/eiscd-delta.txt": { "get": { "tags": [ "Delta" ], "operationId": "getEiscdDelta", "summary": "Fetches the changes since the previous EISCD data file", "x-codeSamples": [ { "lang": "cURL", "source": "curl 'https://api.mintly.uk/eiscd/delta-files/2025/week-18/eiscd-delta.txt' \\\n --header 'X-API-KEY: YOUR_API_KEY' \\\n --output eiscd-delta.txt\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const res = await fetch('https://api.mintly.uk/eiscd/delta-files/2025/week-18/eiscd-delta.txt', {\n headers: { 'x-api-key': process.env.MINTLY_API_KEY },\n})\nconst buffer = Buffer.from(await res.arrayBuffer())\nawait writeFile('eiscd-delta.txt', buffer)\n" }, { "lang": "Python", "source": "res = session.get('https://api.mintly.uk/eiscd/delta-files/2025/week-18/eiscd-delta.txt')\nres.raise_for_status()\nPath('eiscd-delta.txt').write_bytes(res.content)\n" } ], "description": "Takes a year and ISO-8601 week number, and returns a text file with all the changes to the EISCD file, with one change on each line of the file.\n\nFile format is identical to Vocalink tab delimited: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)\n\nAdditional column in 0th position identifies the change as NEW, UPDATED, or DELETED.\n\nNew files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.\n", "security": [ { "api_key": [] } ], "parameters": [ { "$ref": "#/components/parameters/yearParameter" }, { "$ref": "#/components/parameters/weekParameter" } ], "responses": { "200": { "description": "Successful operation. The response body contains the text file with changes OR an error message that the file cannot be found.", "content": { "application/octet-stream": { "schema": { "type": "string", "description": "The text content of the file" } }, "application/xml": { "schema": { "oneOf": [ { "type": "string", "description": "Binary data may also be streamed as a string" }, { "$ref": "#/components/schemas/S3Error" } ] } } } }, "403": { "description": "Forbidden." }, "429": { "description": "Too many requests. Rate limit exceeded." }, "500": { "description": "Unexpected error" } } } }, "/eiscd-text.zip": { "get": { "tags": [ "Base" ], "operationId": "getEiscdText", "summary": "Fetches the entire EISCD data file in tab delimited text format.", "x-codeSamples": [ { "lang": "cURL", "source": "curl 'https://api.mintly.uk/eiscd/eiscd-text.zip' \\\n --header 'X-API-KEY: YOUR_API_KEY' \\\n --output eiscd-text.zip\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const res = await fetch('https://api.mintly.uk/eiscd/eiscd-text.zip', {\n headers: { 'x-api-key': process.env.MINTLY_API_KEY },\n})\nconst buffer = Buffer.from(await res.arrayBuffer())\nawait writeFile('eiscd-text.zip', buffer)\n" }, { "lang": "Python", "source": "res = session.get('https://api.mintly.uk/eiscd/eiscd-text.zip')\nres.raise_for_status()\nPath('eiscd-text.zip').write_bytes(res.content)\n" } ], "description": "Fetches the most recent EISCD data file in text format. Response body is a zip file approx 850KB.\n\nSpecification of the text (tab delimited) file can be found here: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)\n\nNew files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.\n", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful operation. The response body contains the zip file.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the file" } }, "application/xml": { "schema": { "oneOf": [ { "type": "string", "description": "Binary data may also be streamed as a string" }, { "$ref": "#/components/schemas/S3Error" } ] } } } }, "403": { "description": "Forbidden." }, "429": { "description": "Too many requests. Rate limit exceeded." }, "500": { "description": "Unexpected error" } } } }, "/eiscd-xml.zip": { "get": { "tags": [ "Base" ], "operationId": "getEiscdXml", "summary": "Fetches the entire EISCD data file in XML format.", "x-codeSamples": [ { "lang": "cURL", "source": "curl 'https://api.mintly.uk/eiscd/eiscd-xml.zip' \\\n --header 'X-API-KEY: YOUR_API_KEY' \\\n --output eiscd-xml.zip\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const res = await fetch('https://api.mintly.uk/eiscd/eiscd-xml.zip', {\n headers: { 'x-api-key': process.env.MINTLY_API_KEY },\n})\nconst buffer = Buffer.from(await res.arrayBuffer())\nawait writeFile('eiscd-xml.zip', buffer)\n" }, { "lang": "Python", "source": "res = session.get('https://api.mintly.uk/eiscd/eiscd-xml.zip')\nres.raise_for_status()\nPath('eiscd-xml.zip').write_bytes(res.content)\n" } ], "description": "Fetches the most recent EISCD data file in XML format. Response body is a zip file approx 2MB.\n\nSpecification of the XML file can be found here: [Vocalink Spec](https://www.vocalink.com/media/kkeemoy1/extended-iscd-specification-xml-v190.pdf)\n\nNew files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.\n", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful operation. The response body contains the zip file.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the file" } }, "application/xml": { "schema": { "oneOf": [ { "type": "string", "description": "Binary data may also be streamed as a string" }, { "$ref": "#/components/schemas/S3Error" } ] } } } }, "403": { "description": "Forbidden." }, "429": { "description": "Too many requests. Rate limit exceeded." }, "500": { "description": "Unexpected error" } } } }, "/eiscd-csv.zip": { "get": { "tags": [ "Base" ], "operationId": "getEiscdCsv", "summary": "Fetches the entire EISCD data file in CSV format.", "x-codeSamples": [ { "lang": "cURL", "source": "curl 'https://api.mintly.uk/eiscd/eiscd-csv.zip' \\\n --header 'X-API-KEY: YOUR_API_KEY' \\\n --output eiscd-csv.zip\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const res = await fetch('https://api.mintly.uk/eiscd/eiscd-csv.zip', {\n headers: { 'x-api-key': process.env.MINTLY_API_KEY },\n})\nconst buffer = Buffer.from(await res.arrayBuffer())\nawait writeFile('eiscd-csv.zip', buffer)\n" }, { "lang": "Python", "source": "res = session.get('https://api.mintly.uk/eiscd/eiscd-csv.zip')\nres.raise_for_status()\nPath('eiscd-csv.zip').write_bytes(res.content)\n" } ], "description": "Fetches the most recent EISCD data file in CSV format. Response body is a zip file approx 750KB.\n\nSpecification is identical to tab delimited format with comma as delimiter: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)\n\nNew files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.\n", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful operation. The response body contains the zip file.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the file" } }, "application/xml": { "schema": { "oneOf": [ { "type": "string", "description": "Binary data may also be streamed as a string" }, { "$ref": "#/components/schemas/S3Error" } ] } } } }, "403": { "description": "Forbidden." }, "429": { "description": "Too many requests. Rate limit exceeded." }, "500": { "description": "Unexpected error" } } } }, "/eiscd-xlsx.zip": { "get": { "tags": [ "Base" ], "operationId": "getEiscdXlsx", "summary": "Fetches the entire EISCD data file in XLSX Excel format.", "x-codeSamples": [ { "lang": "cURL", "source": "curl 'https://api.mintly.uk/eiscd/eiscd-xlsx.zip' \\\n --header 'X-API-KEY: YOUR_API_KEY' \\\n --output eiscd-xlsx.zip\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const res = await fetch('https://api.mintly.uk/eiscd/eiscd-xlsx.zip', {\n headers: { 'x-api-key': process.env.MINTLY_API_KEY },\n})\nconst buffer = Buffer.from(await res.arrayBuffer())\nawait writeFile('eiscd-xlsx.zip', buffer)\n" }, { "lang": "Python", "source": "res = session.get('https://api.mintly.uk/eiscd/eiscd-xlsx.zip')\nres.raise_for_status()\nPath('eiscd-xlsx.zip').write_bytes(res.content)\n" } ], "description": "Fetches the most recent EISCD data file in Excel format. Response body is a zip file approx 7MB.\n\nSee tab delimited specification for field descriptions: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)\n\nNew files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.\n", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful operation. The response body contains the zip file.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary", "description": "The binary content of the file" } }, "application/xml": { "schema": { "oneOf": [ { "type": "string", "description": "Binary data may also be streamed as a string" }, { "$ref": "#/components/schemas/S3Error" } ] } } } }, "403": { "description": "Forbidden." }, "429": { "description": "Too many requests. Rate limit exceeded." }, "500": { "description": "Unexpected error" } } } } }, "components": { "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header" } }, "parameters": { "yearParameter": { "name": "year", "in": "path", "description": "The year of the delta file that you're requesting.", "required": true, "example": "2025", "schema": { "type": "string" } }, "weekParameter": { "name": "week", "in": "path", "description": "The ISO-8601 week number of the delta file that you're requesting. Must always be in the format week-{d}.", "required": true, "examples": { "week1": { "value": "week-1", "summary": "Fetches the delta file for ISO-8601 week 1" }, "week18": { "value": "week-18", "summary": "Fetches the delta file for ISO-8601 week 18" } }, "schema": { "type": "string" } } }, "schemas": { "S3Error": { "type": "object", "properties": { "Error": { "type": "object", "properties": { "Code": { "type": "string" }, "Message": { "type": "string" }, "Key": { "type": "string" }, "RequestId": { "type": "string" }, "HostId": { "type": "string" } } } } } } } }