Fin

Fin Catalogue API

A set of endpoints to retrieve contextual data to assemble requests to fin.com's API

GitHub OpenAPI

Documentation

📖
Authentication
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/authentication/fin-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/openapi/fin-catalogue-api-openapi.yml

Other Resources

🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/asyncapi/fin-webhooks.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/errors/fin-problem-types.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/conventions/fin-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/fin/refs/heads/main/data-model/fin-data-model.yml

OpenAPI Specification

fin-catalogue-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  title: Fin.com Authentication Catalogue API
  version: 1.0.0
  description: A simple API specificationFo
servers:
- url: https://sandbox.api.fin.com
  description: Sandbox server
- url: https://api.fin.com
  description: Production server
tags:
- name: Catalogue
  description: 'A set of endpoints to retrieve contextual data to assemble requests

    to fin.com''s API

    '
paths:
  /v1/industries:
    get:
      summary: List Industries
      description: Retrieve a list of available industries
      x-mint:
        content: "<Note>\n  This endpoint is used for **Create Business Customer V1** only. It is not applicable for Create Business Customer V2.\n</Note>\n"
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: List of industries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      industries:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Oilseed Except Soybean Farming
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/occupations:
    get:
      summary: List Occupations
      description: Retrieve a list of available occupations
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: List of occupations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      occupations:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Software Engineer
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/source-of-funds:
    get:
      summary: List Source of Funds
      description: Retrieve a list of available source of funds
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      - name: type
        in: query
        description: Filter source of funds by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      responses:
        '200':
          description: List of source of funds retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      source_of_funds:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Employment Income
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/source-of-wealth:
    get:
      summary: List Source of Wealth
      description: Retrieve a list of available source of wealth options
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      - name: type
        in: query
        description: Filter source of wealth by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      responses:
        '200':
          description: List of source of wealth retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      source_of_wealth:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Business dividends or profits
              example:
                data:
                  pagination:
                    current_page: 1
                    per_page: 10
                    total_page: 1
                    total: 7
                  source_of_wealth:
                  - id: 1
                    title: Business dividends or profits
                  - id: 2
                    title: Investment income
                  - id: 3
                    title: Real estate
                  - id: 4
                    title: Inheritance
                  - id: 5
                    title: Salary
                  - id: 6
                    title: Sale of business
                  - id: 7
                    title: Other
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/purposes:
    get:
      summary: List Account Purposes
      description: Retrieve a list of available account purposes
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      - name: type
        in: query
        description: Filter account purposes by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      responses:
        '200':
          description: List of account purposes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      purposes:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Personal Savings
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/countries:
    get:
      summary: List Generic Country Codes
      description: Retrieve a list of country specific codes following ISO 3166-1 alpha-3 standard
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      responses:
        '200':
          description: List of countries retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      countries:
                        type: array
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                              example: BLR
                            name:
                              type: string
                              example: Belarus
                            currency_code:
                              type: string
                              example: BYN
                            phone_code:
                              type: string
                              example: '+375'
                            flag_url:
                              type: string
                              format: uri
                              example: https://flagcdn.com/by.svg
                            postal_code:
                              type: object
                              properties:
                                required:
                                  type: boolean
                                  example: true
                                regex:
                                  type: string
                                  nullable: true
                                  example: \A\d{6}\Z
              example:
                data:
                  pagination:
                    current_page: 1
                    per_page: 20
                    total_page: 13
                    total: 248
                  countries:
                  - code: AFG
                    name: Afghanistan
                    currency_code: AFN
                    phone_code: '+93'
                    flag_url: https://flagcdn.com/af.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: ALA
                    name: Åland Islands
                    currency_code: EUR
                    phone_code: '+358'
                    flag_url: https://flagcdn.com/ax.svg
                    postal_code:
                      required: true
                      regex: \A22\d{3}\Z
                  - code: ALB
                    name: Albania
                    currency_code: ALL
                    phone_code: '+355'
                    flag_url: https://flagcdn.com/al.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: DZA
                    name: Algeria
                    currency_code: DZD
                    phone_code: '+213'
                    flag_url: https://flagcdn.com/dz.svg
                    postal_code:
                      required: true
                      regex: \A\d{5}\Z
                  - code: ASM
                    name: American Samoa
                    currency_code: USD
                    phone_code: +1-684
                    flag_url: https://flagcdn.com/as.svg
                    postal_code:
                      required: true
                      regex: \A(96799)(?:[ \-](\d{4}))?\Z
                  - code: AND
                    name: Andorra
                    currency_code: EUR
                    phone_code: '+376'
                    flag_url: https://flagcdn.com/ad.svg
                    postal_code:
                      required: true
                      regex: \AAD[1-7]0\d\Z
                  - code: AGO
                    name: Angola
                    currency_code: AOA
                    phone_code: '+244'
                    flag_url: https://flagcdn.com/ao.svg
                    postal_code:
                      required: false
                      regex: null
                  - code: AIA
                    name: Anguilla
                    currency_code: XCD
                    phone_code: +1-264
                    flag_url: https://flagcdn.com/ai.svg
                    postal_code:
                      required: true
                      regex: \A(?:AI-)?2640\Z
                  - code: ATA
                    name: Antarctica
                    flag_url: https://flagcdn.com/aq.svg
                    postal_code:
                      required: false
                      regex: null
                  - code: ATG
                    name: Antigua and Barbuda
                    currency_code: XCD
                    phone_code: +1-268
                    flag_url: https://flagcdn.com/ag.svg
                    postal_code:
                      required: false
                      regex: null
                  - code: ARG
                    name: Argentina
                    currency_code: ARS
                    phone_code: '+54'
                    flag_url: https://flagcdn.com/ar.svg
                    postal_code:
                      required: true
                      regex: \A((?:[A-HJ-NP-Z])?\d{4})([A-Z]{3})?\Z
                  - code: ARM
                    name: Armenia
                    currency_code: AMD
                    phone_code: '+374'
                    flag_url: https://flagcdn.com/am.svg
                    postal_code:
                      required: true
                      regex: \A(?:37)?\d{4}\Z
                  - code: ABW
                    name: Aruba
                    currency_code: AWG
                    phone_code: '+297'
                    flag_url: https://flagcdn.com/aw.svg
                    postal_code:
                      required: false
                      regex: null
                  - code: AUS
                    name: Australia
                    currency_code: AUD
                    phone_code: '+61'
                    flag_url: https://flagcdn.com/au.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: AUT
                    name: Austria
                    currency_code: EUR
                    phone_code: '+43'
                    flag_url: https://flagcdn.com/at.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: AZE
                    name: Azerbaijan
                    currency_code: AZN
                    phone_code: '+994'
                    flag_url: https://flagcdn.com/az.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: BHS
                    name: Bahamas
                    currency_code: BSD
                    phone_code: +1-242
                    flag_url: https://flagcdn.com/bs.svg
                    postal_code:
                      required: false
                      regex: null
                  - code: BHR
                    name: Bahrain
                    currency_code: BHD
                    phone_code: '+973'
                    flag_url: https://flagcdn.com/bh.svg
                    postal_code:
                      required: true
                      regex: \A(?:\d|1[0-2])\d{2}\Z
                  - code: BGD
                    name: Bangladesh
                    currency_code: BDT
                    phone_code: '+880'
                    flag_url: https://flagcdn.com/bd.svg
                    postal_code:
                      required: true
                      regex: \A\d{4}\Z
                  - code: BRB
                    name: Barbados
                    currency_code: BBD
                    phone_code: +1-246
                    flag_url: https://flagcdn.com/bb.svg
                    postal_code:
                      required: true
                      regex: \ABB\d{5}\Z
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/countries/{country_code}/subdivisions:
    get:
      summary: 'List Subdivision Codes: ISO 3166-1 alpha-2'
      description: Retrieve a list of subdivision codes for a specific country following ISO 3166-2 standard
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CountryCodeParam'
      responses:
        '200':
          description: List of subdivisions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      subdivisions:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: Bandarban
                            code:
                              type: string
                              example: BD-01
        '401':
          $ref: '#/components/responses/AuthenticationError'
  /v1/transaction-purposes:
    get:
      summary: List Transaction Purposes
      description: Retrieve a list of available transaction purposes
      tags:
      - Catalogue
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/PerPageParam'
      - $ref: '#/components/parameters/CurrentPageParam'
      - name: type
        in: query
        description: Filter transaction purposes by type
        required: true
        schema:
          type: string
          enum:
          - INDIVIDUAL
          - BUSINESS
      responses:
        '200':
          description: List of transaction purposes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                      transaction_purposes:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            title:
                              type: string
                              example: Personal Transfer
        '401':
          $ref: '#/components/responses/AuthenticationError'
components:
  parameters:
    CountryCodeParam:
      name: country_code
      in: path
      description: ISO 3166-1 alpha-3 country code
      required: true
      schema:
        $ref: '#/components/schemas/CountryCode'
    PerPageParam:
      name: per_page
      in: query
      description: Number of items to return per page
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 512
    CurrentPageParam:
      name: current_page
      in: query
      description: The page number to retrieve
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
  responses:
    AuthenticationError:
      description: Authentication failed due to invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Authentication failed
  schemas:
    CountryCode:
      type: string
      description: ISO 3166-1 alpha-3 country code
      example: USA
      enum:
      - AFG
      - ALB
      - DZA
      - ASM
      - AND
      - AGO
      - AIA
      - ATA
      - ATG
      - ARG
      - ARM
      - ABW
      - AUS
      - AUT
      - AZE
      - BHS
      - BHR
      - BGD
      - BRB
      - BLR
      - BEL
      - BLZ
      - BEN
      - BMU
      - BTN
      - BOL
      - BES
      - BIH
      - BWA
      - BVT
      - BRA
      - IOT
      - BRN
      - BGR
      - BFA
      - BDI
      - CPV
      - KHM
      - CMR
      - CAN
      - CYM
      - CAF
      - TCD
      - CHL
      - CHN
      - CXR
      - CCK
      - COL
      - COM
      - COD
      - COG
      - COK
      - CRI
      - HRV
      - CUB
      - CUW
      - CYP
      - CZE
      - CIV
      - DNK
      - DJI
      - DMA
      - DOM
      - ECU
      - EGY
      - SLV
      - GNQ
      - ERI
      - EST
      - SWZ
      - ETH
      - FLK
      - FRO
      - FJI
      - FIN
      - FRA
      - GUF
      - PYF
      - ATF
      - GAB
      - GMB
      - GEO
      - DEU
      - GHA
      - GIB
      - GRC
      - GRL
      - GRD
      - GLP
      - GUM
      - GTM
      - GGY
      - GIN
      - GNB
      - GUY
      - HTI
      - HMD
      - VAT
      - HND
      - HKG
      - HUN
      - ISL
      - IND
      - IDN
      - IRN
      - IRQ
      - IRL
      - IMN
      - ISR
      - ITA
      - JAM
      - JPN
      - JEY
      - JOR
      - KAZ
      - KEN
      - KIR
      - PRK
      - KOR
      - KWT
      - KGZ
      - LAO
      - LVA
      - LBN
      - LSO
      - LBR
      - LBY
      - LIE
      - LTU
      - LUX
      - MAC
      - MDG
      - MWI
      - MYS
      - MDV
      - MLI
      - MLT
      - MHL
      - MTQ
      - MRT
      - MUS
      - MYT
      - MEX
      - FSM
      - MDA
      - MCO
      - MNG
      - MNE
      - MSR
      - MAR
      - MOZ
      - MMR
      - NAM
      - NRU
      - NPL
      - NLD
      - NCL
      - NZL
      - NIC
      - NER
      - NGA
      - NIU
      - NFK
      - MNP
      - NOR
      - OMN
      - PAK
      - PLW
      - PSE
      - PAN
      - PNG
      - PRY
      - PER
      - PHL
      - PCN
      - POL
      - PRT
      - PRI
      - QAT
      - MKD
      - ROU
      - RUS
      - RWA
      - REU
      - BLM
      - SHN
      - KNA
      - LCA
      - MAF
      - SPM
      - VCT
      - WSM
      - SMR
      - STP
      - SAU
      - SEN
      - SRB
      - SYC
      - SLE
      - SGP
      - SXM
      - SVK
      - SVN
      - SLB
      - SOM
      - ZAF
      - SGS
      - SSD
      - ESP
      - LKA
      - SDN
      - SUR
      - SJM
      - SWE
      - CHE
      - SYR
      - TWN
      - TJK
      - TZA
      - THA
      - TLS
      - TGO
      - TKL
      - TON
      - TTO
      - TUN
      - TUR
      - TKM
      - TCA
      - TUV
      - UGA
      - UKR
      - ARE
      - GBR
      - UMI
      - USA
      - URY
      - UZB
      - VUT
      - VEN
      - VNM
      - VGB
      - VIR
      - WLF
      - ESH
      - YEM
      - ZMB
      - ZWE
      - ALA
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 10
        total_page:
          type: integer
          example: 1
        total:
          type: integer
          example: 10
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication. Obtain token from [Issue a Token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint