MX Technologies Institutions API

openapi: 3.2.0
info:
  title: Mx Technologies Institutions API
  contact:
    name: MX Platform API
    url: https://www.mx.com/products/platform-api
  version: '1.0'
  description: 'Operations tagged institutions across 2 of this provider''s published API definitions: mx-technologies-platform-openapi.yml, mx-technologies-platform-v20250224-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: Institutions
paths:
  /institutions:
    get:
      description: This endpoint returns a list of institutions based on the specified search term or parameter.
      operationId: listInstitutions
      parameters:
      - $ref: '#/components/parameters/institutionName'
      - $ref: '#/components/parameters/isoCountryCode'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      - $ref: '#/components/parameters/supportsAccountIdentification'
      - $ref: '#/components/parameters/supportsAccountStatement'
      - $ref: '#/components/parameters/supportsAccountVerification'
      - $ref: '#/components/parameters/supportsTransactionHistory'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InstitutionsResponseBody'
          description: OK
      summary: List institutions
      tags:
      - Institutions
    servers:
    - url: https://int-api.mx.com
    - url: https://api.mx.com
  /institutions/favorites:
    get:
      description: This endpoint returns a paginated list containing institutions that have been set as the partner’s favorites, sorted by popularity. Please contact MX to set a list of favorites.
      operationId: listFavoriteInstitutions
      parameters:
      - $ref: '#/components/parameters/isoCountryCode'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InstitutionsResponseBody'
          description: OK
      summary: List favorite institutions
      tags:
      - Institutions
    servers:
    - url: https://int-api.mx.com
    - url: https://api.mx.com
  /institutions/{institution_code}:
    get:
      description: This endpoint returns information about the institution specified by `institution_code`.
      operationId: readInstitution
      parameters:
      - $ref: '#/components/parameters/institutionCode'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/InstitutionResponseBody'
          description: OK
      summary: Read institution
      tags:
      - Institutions
    servers:
    - url: https://int-api.mx.com
    - url: https://api.mx.com
  /institutions/{institution_code}/credentials:
    get:
      description: 'Use this endpoint to see which credentials will be needed to create a member for a specific institution.


        Passing an invalid `institution_code` returns a `404`.'
      operationId: listInstitutionCredentials
      parameters:
      - $ref: '#/components/parameters/institutionCode'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      responses:
        '200':
          content:
            application/vnd.mx.api.v1+json:
              schema:
                $ref: '#/components/schemas/CredentialsResponseBody'
          description: OK
      summary: List institution credentials
      tags:
      - Institutions
    servers:
    - url: https://int-api.mx.com
    - url: https://api.mx.com
  /institutions/{institution_identifier}/credentials:
    get:
      description: 'Use this endpoint to see which credentials will be needed to create a member for a specific institution.


        Passing an invalid `institution_identifier` returns a `404`.'
      operationId: getInstitutionsByInstitutionIdentifierCredentials
      parameters:
      - $ref: '#/components/parameters/acceptVersion'
      - $ref: '#/components/parameters/institutionIdentifier'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/recordsPerPageMax1000'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialsResponseBody'
          description: OK
      summary: List institution credentials
      tags:
      - Institutions
      x-operation-id-source: normalized
      x-operation-id-original: listInstitutionCredentials
    servers:
    - url: https://int-api.mx.com
    - url: https://api.mx.com
components:
  schemas:
    CredentialsResponseBody:
      properties:
        credentials:
          items:
            $ref: '#/components/schemas/CredentialResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    InstitutionResponseBody:
      properties:
        institution:
          $ref: '#/components/schemas/InstitutionResponse'
      type: object
    CredentialResponse:
      properties:
        display_order:
          example: 1
          type:
          - integer
          - 'null'
        field_name:
          example: LOGIN
          type:
          - string
          - 'null'
        field_type:
          example: TEXT
          type:
          - string
          - 'null'
        guid:
          example: CRD-1ec152cd-e628-e81a-e852-d1e7104624da
          type:
          - string
          - 'null'
        label:
          example: Username
          type:
          - string
          - 'null'
        type:
          example: TEXT
          type:
          - string
          - 'null'
      type: object
    InstitutionResponse:
      properties:
        code:
          example: mxbank
          type:
          - string
          - 'null'
        forgot_password_url:
          example: https://example.url.mxbank.com/forgot-password
          type:
          - string
          - 'null'
        forgot_username_url:
          example: https://example.url.mxbank.com/forgot-username
          type:
          - string
          - 'null'
        instructional_text:
          description: Render this text when end users are asked for their credentials, as it helps end users provide the correct credentials when creating a new member. May contain `<a></a>` tags to link to explanatory material.
          example: Some instructional text <a href="https://example.url.mxbank.com/instructions" id="instructional_text">for end users</a>.
          type:
          - string
          - 'null'
        instructional_text_steps:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An array of instructional steps that may contain html elements.
          example:
          - 'Step 1: Do this.'
          - 'Step 2: Do that.'
        is_disabled_by_client:
          example: false
          type:
          - boolean
          - 'null'
        iso_country_code:
          example: US
          type: string
        medium_logo_url:
          example: https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png
          type:
          - string
          - 'null'
        name:
          example: MX Bank
          type:
          - string
          - 'null'
        small_logo_url:
          example: https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png
          type:
          - string
          - 'null'
        supports_account_identification:
          example: true
          type:
          - boolean
          - 'null'
        supports_account_statement:
          example: true
          type:
          - boolean
          - 'null'
        supports_account_verification:
          example: true
          type:
          - boolean
          - 'null'
        supports_oauth:
          example: true
          type:
          - boolean
          - 'null'
        supports_tax_document:
          example: true
          type:
          - boolean
          - 'null'
        supports_transaction_history:
          example: true
          type:
          - boolean
          - 'null'
        trouble_signing_in_url:
          example: https://example.url.mxbank.com/login-trouble
          type:
          - string
          - 'null'
        url:
          example: https://www.mxbank.com
          type:
          - string
          - 'null'
      type: object
    PaginationResponse:
      properties:
        current_page:
          example: 1
          type: integer
        per_page:
          example: 25
          type: integer
        total_entries:
          example: 1
          type: integer
        total_pages:
          example: 1
          type: integer
      type: object
    InstitutionsResponseBody:
      properties:
        institutions:
          items:
            $ref: '#/components/schemas/InstitutionResponse'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
      type: object
    InstitutionResponse_2:
      properties:
        code:
          description: The code identifying a financial institution.
          example: mxbank
          type:
          - string
          - 'null'
        created_at:
          description: The date and time the institution was created, represented in ISO 8601 format with a timestamp.
          example: '2025-02-13T18:08:00+00:00'
          type: string
        forgot_password_url:
          description: URL for the forgot password page of the institution.
          example: https://example.url.mxbank.com/forgot-password
          type:
          - string
          - 'null'
        forgot_username_url:
          description: URL for the forgot username page of the institution.
          example: https://example.url.mxbank.com/forgot-username
          type:
          - string
          - 'null'
        guid:
          description: The unique identifier for the institution. Defined by MX.
          example: INS-1572a04c-912b-59bf-5841-332c7dfafaef
          type: string
        instructional_text:
          description: Render this text when end users are asked for their credentials, as it helps end users provide the correct credentials when creating a new member. May contain `<a></a>` tags to link to explanatory material.
          example: Some instructional text <a href="https://example.url.mxbank.com/instructions" id="instructional_text">for end users</a>.
          type:
          - string
          - 'null'
        instructional_text_steps:
          type:
          - array
          - 'null'
          items:
            type: string
          description: An array of instructional steps that may contain html elements.
          example:
          - 'Step 1: Do this.'
          - 'Step 2: Do that.'
        is_disabled_by_client:
          description: Indicates whether the institution is disabled by the client.
          example: false
          type:
          - boolean
          - 'null'
        is_hidden:
          example: true
          type: boolean
          description: If the institution is available for creating new member connections, this field will be `false`. Otherwise, this field will be `true`.
        iso_country_code:
          description: The ISO country code associated with the institution.
          example: US
          type: string
          enum:
          - US
          - CA
        medium_logo_url:
          description: The URL for a 100px X 100px logo for each `institution`. A generic logo is returned for institutions that don't have one.
          example: https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png
          type:
          - string
          - 'null'
        name:
          description: The name of the institution.
          example: MX Bank
          type:
          - string
          - 'null'
        small_logo_url:
          description: The URL for a 50px X 50px logo for each `institution`. A generic logo is returned for institutions that don't have one.
          example: https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png
          type:
          - string
          - 'null'
        supported_products:
          items:
            $ref: '#/components/schemas/SupportedProducts'
        supports_oauth:
          description: 'If true, this indicates that the institution supports OAuth and that you have been properly registered for OAuth with that institution.

            '
          example: true
          type:
          - boolean
          - 'null'
        supports_tax_document:
          description: This indicates whether the institution supports tax documents.
          example: true
          type:
          - boolean
          - 'null'
        trouble_signing_in_url:
          description: The URL of the institution for helping users troubleshoot any other sign-in issue.
          example: https://example.url.mxbank.com/login-trouble
          type:
          - string
          - 'null'
        url:
          description: The URL for an institution's website.
          example: https://www.mxbank.com
          type:
          - string
          - 'null'
      type: object
    PaginationResponse_2:
      properties:
        current_page:
          description: The page delivered by the current response.
          example: 1
          type: integer
        per_page:
          description: The number of records delivered with each page.
          example: 25
          type: integer
        total_entries:
          description: The total number of records available.
          example: 1
          type: integer
        total_pages:
          description: The total number of pages available.
          example: 1
          type: integer
      type: object
    SupportedProducts:
      type: string
      enum:
      - account_verification
      - identity_verification
      - transactions
      - transaction_history
      - statements
      - investments
      - rewards
  parameters:
    supportsAccountStatement:
      description: Filter only institutions which support account statements.
      example: true
      in: query
      name: supports_account_statement
      schema:
        type: boolean
    isoCountryCode:
      description: An array of strings that filters institutions in the widget by the specified country code. Acceptable codes include `US`, `CA`, and `MX` (Mexico).
      required: false
      in: query
      name: iso_country_code
      example:
      - US
      - CA
      schema:
        type: array
        items:
          type: string
    supportsAccountVerification:
      description: Filter only institutions which support account verification.
      example: true
      in: query
      name: supports_account_verification
      schema:
        type: boolean
    institutionName:
      description: This will list only institutions in which the appended string appears.
      example: mxbank
      in: query
      name: name
      schema:
        type: string
    recordsPerPageMax1000:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `1000`. If the value exceeds `1000`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    page:
      description: Results are paginated. Specify current page.
      example: 1
      in: query
      name: page
      schema:
        type: integer
    supportsTransactionHistory:
      description: Filter only institutions which support extended transaction history.
      example: true
      in: query
      name: supports_transaction_history
      schema:
        type: boolean
    supportsAccountIdentification:
      description: Filter only institutions which support account identification.
      example: true
      in: query
      name: supports_account_identification
      schema:
        type: boolean
    institutionCode:
      description: The institution_code of the institution.
      example: mxbank
      in: path
      name: institution_code
      required: true
      schema:
        type: string
    supportedProducts:
      name: supported_products
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
          enum:
          - account_verification
          - identity_verification
          - transactions
          - history
          - statements
          - investments
          - rewards
      description: Filters institutions that support specific products. Values may include account_verification, identity_verification, transactions, history, statements, investments.
      example:
      - account_verification
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: string
        default: v20250224
        example: v20250224
      description: MX Platform API version.
    recordsPerPage:
      description: This specifies the number of records to be returned on each page. Defaults to `25`. The valid range is from `10` to `100`. If the value exceeds `100`, the default value of `25` will be used instead.
      example: 10
      in: query
      name: records_per_page
      schema:
        type: integer
    institutionIdentifier:
      description: The identifier for the institution. For this identifier, use either the `institution_code` or the institution `guid`.
      example: mxbank
      in: path
      name: institution_identifier
      required: true
      schema:
        type: string
    institutionCode_2:
      description: A unique identifier for each institution, defined by MX.
      example: mxbank
      in: path
      name: institution_code
      required: true
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      scheme: basic
      type: http
x-refined-from:
- mx-technologies-platform-openapi.yml
- mx-technologies-platform-v20250224-openapi.yml