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
    Industry Sort Code Directory — the reference database of UK sort codes. With
    a subscription you can download the complete directory in your choice of
    format, or fetch just the weekly changes.

    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`. There is no sandbox
    environment for this API.

    New EISCD data files are published **every Friday from 12:00 GMT**, and the
    data should be treated as valid from the following Monday.

    ## Status codes

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

    | Status | Meaning |
    |---|---|
    | `200` OK | The request succeeded. |
    | `400` Bad request | Something was wrong with the request. Check the error message in the response. |
    | `401` Unauthorised | Your credentials are invalid or have expired. |
    | `403` Forbidden | Authentication failed — the key has expired, or no key was provided. |
    | `429` Too many requests | You have exceeded the rate limit. Wait, then retry. |
    | `500` Server error | Something went wrong on our side — get in touch so we can look into it. |

    ## 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,
    process delta files, and schedule automated data syncs.

    **[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
    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.
  - 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.
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' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --output eiscd-delta.txt
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd/delta-files/2025/week-18/eiscd-delta.txt', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            const buffer = Buffer.from(await res.arrayBuffer())
            await writeFile('eiscd-delta.txt', buffer)
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd/delta-files/2025/week-18/eiscd-delta.txt')
            res.raise_for_status()
            Path('eiscd-delta.txt').write_bytes(res.content)
      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.
        

        File format is identical to Vocalink tab delimited: [Vocalink Spec](https://www.vocalink.com/media/thfivwco/extended-iscd-tech-spec-tab-delimited-v280.pdf)
        

        Additional column in 0th position identifies the change as NEW, UPDATED, or DELETED.


        New files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.
      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' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --output eiscd-text.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd/eiscd-text.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            const buffer = Buffer.from(await res.arrayBuffer())
            await writeFile('eiscd-text.zip', buffer)
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd/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)


        New files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.
      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' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --output eiscd-xml.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd/eiscd-xml.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            const buffer = Buffer.from(await res.arrayBuffer())
            await writeFile('eiscd-xml.zip', buffer)
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd/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)


        New files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.
      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' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --output eiscd-csv.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd/eiscd-csv.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            const buffer = Buffer.from(await res.arrayBuffer())
            await writeFile('eiscd-csv.zip', buffer)
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd/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)


        New files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.
      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' \
              --header 'X-API-KEY: YOUR_API_KEY' \
              --output eiscd-xlsx.zip
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.mintly.uk/eiscd/eiscd-xlsx.zip', {
              headers: { 'x-api-key': process.env.MINTLY_API_KEY },
            })
            const buffer = Buffer.from(await res.arrayBuffer())
            await writeFile('eiscd-xlsx.zip', buffer)
        - lang: Python
          source: |
            res = session.get('https://api.mintly.uk/eiscd/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)


        New files are available from 12:00 GMT every Friday, and the data should be considered valid from the following Monday.
      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