Flinks Statements API
Signs up one or more of the connected customer accounts to retrieve PDF bank statements issued by their financial institution, referenced by the session RequestId.
OpenAPI Specification
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: []