openapi: 3.0.1
info:
  title: Flinks Authorize Fraud 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).
security:
- flinks_auth_key: []
tags:
- name: Fraud
paths:
  /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:
  schemas:
    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
    UploadRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: The bank statement or transaction document to process.
        Tag:
          type: string
      required:
      - file
    RequestIdBody:
      type: object
      properties:
        RequestId:
          type: string
          format: uuid
          description: RequestId returned by /Authorize.
      required:
      - RequestId
  securitySchemes:
    flinks_auth_key:
      type: apiKey
      in: header
      name: flinks-auth-key
      description: Short-lived (30-minute) authorize token obtained from /GenerateAuthorizeToken.