openapi: 3.0.3
info:
  title: Mintly EISCD API (Monthly, v2)
  termsOfService: https://www.mintly.uk/terms
  contact:
    email: support@mintly.uk
  version: 2.0.0
  description: |
    The Mintly EISCD API gives your application direct access to the Extended
    Industry Sort Code Directory — the reference database of UK sort codes. The
    monthly plan provides the complete EISCD snapshot in all four published
    formats, refreshed weekly at source, with a quota intended for a single
    download per calendar month.

    Delta files are not part of this plan and are not exposed on this API. If you
    need the weekly changes, use the
    [weekly EISCD API](https://www.mintly.uk/eiscd-docs) instead.

    The API is RESTful, using predictable, resource-oriented URLs with standard
    HTTP methods and status codes. It is OpenAPI 3.0 compliant, so it integrates
    cleanly with any tooling that understands the OpenAPI standard.

    Questions? Email us at [support@mintly.uk](mailto:support@mintly.uk).

    ## Authentication

    Every request must carry an `X-API-KEY` header set to your organisation's
    unique key. Keep this secret.

    ```
    X-API-KEY: YOUR_API_KEY
    ```

    ## Environment

    Production is at `https://api.mintly.uk/eiscd-base/v2`. There is no sandbox
    environment for this API.

    The underlying EISCD is refreshed **every Friday from 12:00 GMT**, and the
    data should be treated as valid from the following Monday. Your quota is
    intended for a single download per calendar month, so whichever snapshot you
    take is the one published at that point.

    ## Status codes

    We use standard HTTP status codes, including but not limited to:

    | Status | Meaning |
    |---|---|
    | `200` OK | The request succeeded. The response body is the file. |
    | `403` Forbidden | The API key is missing, invalid or disabled. |
    | `404` Not found | The requested file is not available. |
    | `429` Too many requests | You have exceeded the rate limit, or used your monthly quota. Wait, then retry. |
    | `500` Server error | Something went wrong on our side — get in touch so we can look into it. |

    Every non-`200` response has a JSON body with a `Status` and a `Message`
    field:

    ```json
    {
      "Status": "Invalid",
      "Message": "File not found"
    }
    ```

    A file that does not exist and a file that is not part of your plan both
    return `404`, and are deliberately indistinguishable. Requesting a delta file
    on this plan therefore returns `404`.

    ## Backwards compatibility

    The API is designed to be backwards compatible, so changes should not
    disrupt existing integrations. We follow
    [semantic versioning](https://semver.org) for API releases. Build your
    integration to handle non-breaking changes gracefully. If a breaking change
    ever becomes necessary, we will give advance notice and a clear migration
    path, and keep the existing version available for a defined deprecation
    period.

    ## AI agent skill

    Install the Mintly EISCD agent skill for AI-assisted integration help inside
    your editor. Once installed, invoke `/eiscd-api` to generate client code,
    load the base files into your own store, and schedule a monthly data refresh.

    **[Download the agent skill](https://www.mintly.uk/assets/eiscd-api-skill.zip)**

    Built on the [Agent Skills open standard](https://agentskills.io/clients),
    it works with Claude Code, VS Code (GitHub Copilot), OpenAI Codex, Cursor,
    Gemini CLI, and many more.
externalDocs:
  description: Find out more about Mintly
  url: https://www.mintly.uk
servers:
  - url: https://api.mintly.uk/eiscd-base/v2
    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.
x-tagGroups:
  - name: EISCD data files
    tags:
      - Base
paths:
  /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-base/v2/eiscd-text.zip' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --fail \
              --output eiscd-text.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd-base/v2/eiscd-text.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            if (!res.ok) throw new Error((await res.json()).Message)
            await writeFile('eiscd-text.zip', Buffer.from(await res.arrayBuffer()))
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd-base/v2/eiscd-text.zip')
            res.raise_for_status()
            Path('eiscd-text.zip').write_bytes(res.content)
      description: >
        Fetches the most recent EISCD data file in text format. Response body is a zip file approx 850KB.


        Specification 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)
      security:
        - api_key: []
      responses:
        '200':
          $ref: '#/components/responses/ZipFile'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /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-base/v2/eiscd-xml.zip' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --fail \
              --output eiscd-xml.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd-base/v2/eiscd-xml.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            if (!res.ok) throw new Error((await res.json()).Message)
            await writeFile('eiscd-xml.zip', Buffer.from(await res.arrayBuffer()))
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd-base/v2/eiscd-xml.zip')
            res.raise_for_status()
            Path('eiscd-xml.zip').write_bytes(res.content)
      description: >
        Fetches the most recent EISCD data file in XML format. Response body is a zip file approx 2MB.


        Specification of the XML file can be found here: [Vocalink Spec](https://www.vocalink.com/media/kkeemoy1/extended-iscd-specification-xml-v190.pdf)
      security:
        - api_key: []
      responses:
        '200':
          $ref: '#/components/responses/ZipFile'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /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-base/v2/eiscd-csv.zip' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --fail \
              --output eiscd-csv.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd-base/v2/eiscd-csv.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            if (!res.ok) throw new Error((await res.json()).Message)
            await writeFile('eiscd-csv.zip', Buffer.from(await res.arrayBuffer()))
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd-base/v2/eiscd-csv.zip')
            res.raise_for_status()
            Path('eiscd-csv.zip').write_bytes(res.content)
      description: >
        Fetches the most recent EISCD data file in CSV format. Response body is a zip file approx 750KB.


        Specification 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)
      security:
        - api_key: []
      responses:
        '200':
          $ref: '#/components/responses/ZipFile'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
  /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-base/v2/eiscd-xlsx.zip' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --fail \
              --output eiscd-xlsx.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd-base/v2/eiscd-xlsx.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            if (!res.ok) throw new Error((await res.json()).Message)
            await writeFile('eiscd-xlsx.zip', Buffer.from(await res.arrayBuffer()))
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd-base/v2/eiscd-xlsx.zip')
            res.raise_for_status()
            Path('eiscd-xlsx.zip').write_bytes(res.content)
      description: >
        Fetches the most recent EISCD data file in Excel format. Response body is a zip file approx 7MB.


        See tab delimited specification for field descriptions: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)
      security:
        - api_key: []
      responses:
        '200':
          $ref: '#/components/responses/ZipFile'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
  responses:
    ZipFile:
      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
    Forbidden:
      description: Forbidden. The API key is missing, invalid or disabled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >
        The requested file is not available. Returned both for a file that does not
        exist and for one that is not part of your plan; the two are deliberately
        indistinguishable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too many requests. Rate limit or quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        Status:
          type: string
          description: The status. For an error, will be "Error" or "Invalid".
          example: Invalid
        Message:
          type: string
          description: A short description of the problem.
          example: File not found
      required:
        - Status
        - Message