Flinks Authorize / Connect API

openapi: 3.0.1
info:
  title: Flinks API
  description: >-
    Representative specification of the Flinks financial data API. Businesses
    connect to consumer and business bank accounts to aggregate account,
    transaction, and statement data, verify identity, and derive income,
    credit-risk, and fraud analytics. A session is opened with the multi-step
    /Authorize (MFA) endpoint using a LoginId returned by Flinks Connect; the
    resulting RequestId is passed to subsequent data, enrichment, and analytics
    endpoints. All calls are authenticated with a short-lived authorize token
    supplied in the flinks-auth-key header.
  termsOfService: https://flinks.com/terms-of-service/
  contact:
    name: Flinks Support
    url: https://help.flinks.com/
  version: '3.0'
servers:
  - url: https://{instance}-api.private.fin.ag/v3/{customerId}/BankingServices
    description: Flinks per-customer instance host.
    variables:
      instance:
        default: toolbox
        description: Assigned instance / environment prefix (e.g. toolbox for sandbox).
      customerId:
        default: '00000000-0000-0000-0000-000000000000'
        description: Your Flinks customer identifier (GUID).
paths:
  /GenerateAuthorizeToken:
    post:
      operationId: generateAuthorizeToken
      tags:
        - Authorize
      summary: Generate a short-lived authorize token.
      description: >-
        Exchanges your API secret for a 30-minute authorize token that must be
        supplied in the flinks-auth-key header on all other endpoints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAuthorizeTokenRequest'
      responses:
        '200':
          description: Authorize token generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeTokenResponse'
  /Authorize:
    post:
      operationId: authorize
      tags:
        - Connect
      summary: Open a banking session and handle MFA.
      description: >-
        Opens a session for a Flinks Connect LoginId. Returns HTTP 200 with a
        RequestId and Links on success, or HTTP 203 with SecurityChallenges when
        a multi-factor challenge is required. Resubmit with RequestId and
        SecurityResponses to complete the challenge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeRequest'
      responses:
        '200':
          description: Authorization successful; session is ready for data calls.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizeResponse'
        '203':
          description: Multi-factor authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaChallengeResponse'
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /GetAccountsDetail:
    post:
      operationId: getAccountsDetail
      tags:
        - Connect
      summary: Retrieve full account detail and transactions.
      description: >-
        Returns full detail for each linked account - identity, balances, up to
        90 or 365 days of transactions, and holder KYC. May return HTTP 202;
        poll /GetAccountsDetailAsync with the same RequestId until HTTP 200.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetAccountsDetailRequest'
      responses:
        '200':
          description: Account detail returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsResponse'
        '202':
          description: Request accepted and processing; poll the async endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPendingResponse'
  /GetAccountsDetailAsync/{requestId}:
    get:
      operationId: getAccountsDetailAsync
      tags:
        - Connect
      summary: Poll a pending accounts-detail request.
      parameters:
        - name: requestId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: The RequestId returned by /Authorize.
      responses:
        '200':
          description: Account detail returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsResponse'
        '202':
          description: Still processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPendingResponse'
  /GetAccountsSummary:
    post:
      operationId: getAccountsSummary
      tags:
        - Connect
      summary: Retrieve general account summary information.
      description: >-
        Returns cardholder name (when available), balance, category, and EFT
        eligibility for each linked account, without full transaction history.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestIdBody'
      responses:
        '200':
          description: Account summary returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountsResponse'
        '202':
          description: Processing; poll /GetAccountsSummaryAsync.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncPendingResponse'
  /GetStatements:
    post:
      operationId: getStatements
      tags:
        - Connect
      summary: Retrieve PDF bank statements.
      description: >-
        Signs up one or more connected accounts to retrieve PDF statements
        issued by their financial institution.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetStatementsRequest'
      responses:
        '200':
          description: Statements returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementsResponse'
  /FieldMatch:
    post:
      operationId: fieldMatch
      tags:
        - Identity
      summary: Verify applicant fields against the connected account holder.
      description: >-
        Compares supplied applicant identity fields (name, address, phone,
        email) against the identity captured on the connected bank account and
        returns per-field match results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldMatchRequest'
      responses:
        '200':
          description: Field match results returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMatchResponse'
  /GetCategorization:
    post:
      operationId: getCategorization
      tags:
        - Enrich
      summary: Return categorized transactional data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestIdBody'
      responses:
        '200':
          description: Categorized transactions returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategorizationResponse'
  /GetIncomeAttributes:
    post:
      operationId: getIncomeAttributes
      tags:
        - Score
      summary: Standardized income verification attributes.
      description: >-
        Returns a high-level overview of total income, employment income, and
        government income for standardized income verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributesRequest'
      responses:
        '200':
          description: Income attributes returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributesResponse'
  /GetCreditRiskAttributes:
    post:
      operationId: getCreditRiskAttributes
      tags:
        - Score
      summary: Credit risk and income attributes.
      description: >-
        Returns overall financial information, employment and non-employment
        income sources, loan payments, bill payments, and additional risk
        analysis measures.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributesRequest'
      responses:
        '200':
          description: Credit risk attributes returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributesResponse'
  /Upload:
    post:
      operationId: upload
      tags:
        - Fraud
      summary: Process externally supplied bank statement / transaction data.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadRequest'
      responses:
        '200':
          description: Upload accepted and processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadResponse'
  /FraudAnalysis:
    post:
      operationId: fraudAnalysis
      tags:
        - Fraud
      summary: Run fraud analysis on uploaded documents.
      description: >-
        Surfaces tampering and fraud signals from an uploaded document set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestIdBody'
      responses:
        '200':
          description: Fraud analysis result returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FraudAnalysisResponse'
components:
  securitySchemes:
    flinks_auth_key:
      type: apiKey
      in: header
      name: flinks-auth-key
      description: >-
        Short-lived (30-minute) authorize token obtained from
        /GenerateAuthorizeToken.
  security:
    - flinks_auth_key: []
  schemas:
    Error:
      type: object
      properties:
        HttpStatusCode:
          type: integer
        Message:
          type: string
        FlinksCode:
          type: string
          description: >-
            Machine-readable code such as INVALID_LOGIN, DISABLED_LOGIN, or
            QUESTION_NOT_FOUND.
      required:
        - HttpStatusCode
        - Message
    GenerateAuthorizeTokenRequest:
      type: object
      properties:
        secret:
          type: string
          description: Your Flinks API secret.
      required:
        - secret
    AuthorizeTokenResponse:
      type: object
      properties:
        AuthorizeToken:
          type: string
        ExpiresIn:
          type: integer
          description: Token lifetime in seconds (1800).
    Link:
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
        method:
          type: string
    AuthorizeRequest:
      type: object
      properties:
        LoginId:
          type: string
          format: uuid
          description: Identifier returned by Flinks Connect after a successful login.
        MostRecentCached:
          type: boolean
          default: true
          description: Use cached data (true, recommended) or live mode (false).
        Language:
          type: string
          enum: [en, fr]
          default: en
        Save:
          type: boolean
          default: true
        Tag:
          type: string
        RequestId:
          type: string
          format: uuid
          description: Required when resubmitting after an MFA challenge.
        SecurityResponses:
          type: object
          description: >-
            Map of MFA question prompts to arrays of user answers.
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - LoginId
    AuthorizeResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Institution:
          type: string
        InstitutionId:
          type: string
        Login:
          type: object
        Links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
        HttpStatusCode:
          type: integer
          example: 200
    SecurityChallenge:
      type: object
      properties:
        Type:
          type: string
        Iterables:
          type: array
          items:
            type: string
        Prompt:
          type: string
    MfaChallengeResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        SecurityChallenges:
          type: array
          items:
            $ref: '#/components/schemas/SecurityChallenge'
        HttpStatusCode:
          type: integer
          example: 203
    RequestIdBody:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
          description: RequestId returned by /Authorize.
      required:
        - RequestId
    GetAccountsDetailRequest:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        WithAccountIdentity:
          type: boolean
          default: true
          description: Include transit / institution / account numbers.
        WithKYC:
          type: boolean
          default: true
          description: Include account-holder identity information.
        WithTransactions:
          type: boolean
          default: true
        DaysOfTransactions:
          type: string
          enum: [Days90, Days365]
        AccountsFilter:
          type: array
          items:
            type: string
        WithDetailsAndBankingStatements:
          type: boolean
      required:
        - RequestId
    GetStatementsRequest:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        AccountsFilter:
          type: array
          items:
            type: string
        NumberOfStatements:
          type: string
          description: Number of PDF statements to retrieve (e.g. Months3, Months12).
      required:
        - RequestId
    Balance:
      type: object
      properties:
        Available:
          type: number
        Current:
          type: number
        Limit:
          type: number
    Transaction:
      type: object
      properties:
        Date:
          type: string
          format: date
        Description:
          type: string
        Debit:
          type: number
          nullable: true
        Credit:
          type: number
          nullable: true
        Balance:
          type: number
    Holder:
      type: object
      properties:
        Name:
          type: string
        Address:
          type: object
          properties:
            CivicAddress:
              type: string
            City:
              type: string
            Province:
              type: string
            PostalCode:
              type: string
            Country:
              type: string
        Email:
          type: string
        PhoneNumber:
          type: string
    Account:
      type: object
      properties:
        Id:
          type: string
        Title:
          type: string
        AccountNumber:
          type: string
        LastFourDigits:
          type: string
        TransitNumber:
          type: string
        InstitutionNumber:
          type: string
        Category:
          type: string
        Type:
          type: string
        Currency:
          type: string
        Balance:
          $ref: '#/components/schemas/Balance'
        Transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        Holder:
          $ref: '#/components/schemas/Holder'
    AccountsResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
        Institution:
          type: string
        HttpStatusCode:
          type: integer
          example: 200
    AsyncPendingResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        HttpStatusCode:
          type: integer
          example: 202
        Message:
          type: string
          example: Operation is pending; poll the async endpoint.
    Statement:
      type: object
      properties:
        AccountId:
          type: string
        FileName:
          type: string
        Base64Content:
          type: string
          description: Base64-encoded PDF statement.
    StatementsResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Statements:
          type: array
          items:
            $ref: '#/components/schemas/Statement'
    FieldMatchRequest:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Name:
          type: string
        Address:
          type: string
        Email:
          type: string
        PhoneNumber:
          type: string
      required:
        - RequestId
    FieldMatchResult:
      type: object
      properties:
        Field:
          type: string
        Matched:
          type: boolean
        Score:
          type: number
    FieldMatchResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Results:
          type: array
          items:
            $ref: '#/components/schemas/FieldMatchResult'
    Category:
      type: object
      properties:
        Name:
          type: string
        Amount:
          type: number
        Count:
          type: integer
    CategorizationResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
    AttributesRequest:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Package:
          type: string
          description: Attributes package name to compute.
      required:
        - RequestId
    Attribute:
      type: object
      properties:
        Name:
          type: string
        Value:
          type: string
    AttributesResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
    UploadRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: The bank statement or transaction document to process.
        Tag:
          type: string
      required:
        - file
    UploadResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        Status:
          type: string
    FraudAnalysisResponse:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
        FraudScore:
          type: number
        Signals:
          type: array
          items:
            type: object
            properties:
              Name:
                type: string
              Severity:
                type: string
security:
  - flinks_auth_key: []