Open Banking

Mastercard payment and fraud detection APIs

developer.mastercard.com ↗

Version

1.16.2

OpenAPI

3.0.3

Endpoints

104

Schemas

514

81

Quality

Updated

3 days ago

Payments payments fintech fraud

Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.finicity.com

Endpoints

Clear filters

GET POST PUT PATCH DELETE

Accountvalidationassistance 2 endpoints

POST /microentry/v1/customers/{customerId} Initiate Micro Entries

Initiate the micro entries to customer’s account.

Two random micro amounts less than a dollar each will be deposited to provided customer’s account.

Supported regions:

operationId: AccountValidationAssistance_initiateMicroEntries

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID

Request Body

application/json

schema MicroDepositInitiation

Property	Type	Required
receiver	object	required
└ memo	string	optional
└ name	string	required
└ accountType	string	required
└ accountNumber	string	required
└ routingNumber	string	required
callbackUrl	string	optional
institutionLoginId	string	optional

Responses

200

Micro entries were successfully initiated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

409

The resource already exists

429

The service can’t accept more requests or is not available from the Test Drive.

POST /microentry/v1/customers/{customerId}

POST /microentry/v1/customers/{customerId}/accounts/{accountId}/amounts Verify Micro Entries

Verify the micro entries as received by customer in customer’s account.
Customer needs to verify the micro amounts received in customer’s account. customerId and accountId are the identifiers of the customer and account receiving the micro entries.

Supported regions:

operationId: AccountValidationAssistance_verifyMicroEntries

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
accountId	path	optional		The account ID

Request Body

application/json

schema MicroDepositVerification

Property	Type	Required
amounts	array	required

Responses

200

Micro entries were successfully verified

400

Micro entries verification failed. status field could be any except “Verified” and “Completed”.

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /microentry/v1/customers/{customerId}/accounts/{accountId}/amounts

Accounts 4 endpoints

POST /aggregation/v1/customers/{customerId}/accounts Refresh Customer Accounts

Refresh account and transaction data for all accounts associated with the given customerId with a connection to the institution.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day. Because many financial institutions only post transactions once per day, calling Refresh services repeatedly is usually a waste of resources and is not recommended.

Apps may call Refresh services for a specific customer when there is a specific business case for the need of data that is up to date as of the moment. Please discuss with your account manager and systems engineer for further clarification.

The recommended timeout setting for this request is 120 seconds in order to receive a response. However, you can terminate the connection after making the call the operation will still complete. You will have to pull the account records to check for an updated aggregation attempt date to know when the refresh is complete.

Note: This service is not available for all tiers of dynamic billing.

Supported regions:

operationId: Accounts_refreshCustomerAggregation

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID

Responses

200

The account list was successfully refreshed

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/accounts

POST /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts Refresh Customer Accounts by Institution Login ID

Refresh account and transaction data for all accounts associated with a given institutionLoginId with a connection to the institution.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day. Because many financial institutions only post transactions once per day, calling Refresh repeatedly is usually a waste of resources and is not recommended.

Note: This service is not available for all tiers of dynamic billing.

Supported regions:

operationId: Accounts_refreshCustomerByInstitutionLogin

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
institutionLoginId	path	optional		The institution login ID

Responses

200

The account list was successfully refreshed

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts

POST /aggregation/v2/customers/{customerId}/accounts Refresh Customer Accounts for Data Access Tiers

Refresh account and transaction data for all accounts associated with the given customerId with a connection to the institution.

Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day.
Apps may call Refresh services for a specific customer when there is a specific business case for the need of data that is up to date as of the moment. Please discuss with your account manager and systems engineer for further clarification.

Note: This service will be used for dynamic billing tiers ASD, AFD and ATD.

Supported regions:

operationId: Accounts_refreshCustomerData

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID

Responses

204

The account list was successfully refreshed

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v2/customers/{customerId}/accounts

POST /aggregation/v2/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts Refresh Customer Account by Institution Login ID for Data Access Tiers

Refresh account and transaction data for all accounts associated with a given ‘institutionLoginId` with a connection to the institution. Client apps are not permitted to automate calls to the Refresh services. Active accounts are automatically refreshed by Finicity once per day.

Note: This service will be used for dynamic billing tiers ASD, AFD and ATD.

Supported regions:

operationId: Accounts_refreshCustomerAccountByInstitutionLogin

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
institutionLoginId	path	optional		The institution login ID

Responses

204

The account list was successfully refreshed

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v2/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts

Appregistration 1 endpoints

POST /aggregation/v1/partners/applications Register App

Supported regions:

operationId: AppRegistration_createNewApplication

Request Body

application/json

schema Application

Property	Type	Required
image	string	required
appUrl	string	required
appName	string	required
ownerCity	string	required
ownerName	string	required
ownerState	string	required
ownerCountry	string	required
appDescription	string	required
ownerPostalCode	string	required
ownerAddressLine1	string	required
ownerAddressLine2	string	required

Responses

201

The app registration was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /aggregation/v1/partners/applications

Authentication 1 endpoints

POST /aggregation/v2/partners/authentication Create Access Token

Send Partner ID and Partner Secret to the Partner Authentication service to obtain a token for accessing Finicity APIs.

The token is valid for two hours and is required on all calls to the Finicity APIs
As a best practice, use a single token for all calls. Assign a timestamp for each token, and then check the current timestamp before making any calls. If the token is greater than 90 minutes, generate a new one.
⚠️ After five failed attempts to authenticate, your account will be locked. Contact support@finicity.com to get help resetting your account.

Supported regions:

operationId: Authentication_createAccessToken

Request Body

application/json

schema PartnerCredentials

Property	Type	Required
partnerId	string	required
partnerSecret	string	required

Responses

200

The access token was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check Partner ID, Partner Secret or Finicity-App-Key.

POST /aggregation/v2/partners/authentication

Balanceanalytics 3 endpoints

POST /analytics/balance/v1/customer/{customerId} Generate Balance Analytics

Balance Analytics for Business analyzes bank balances over time to report metrics and identify behavior that may indicate risk.

Calculated metrics include:

Current/available account balances
Minimum/maximum/average account balances over the requested time
period and broken down by month
Daily ending balance of accounts for each day in the requested time
period
Propensity of the customer’s account balances to increase week over
week
Number of days in the requested time period ending with a negative
balance

This version of the API is intended for piloting and integration testing your application with the Balance Analytics product. It does not adhere to FCRA requirements, and should not be used for production/lending purposes. See Generate Balance Analytics - FCRA for the FCRA compliant version of this API.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get Balance Analytics Report (operation: GetObbAnalyticsReport).

Supported regions:

operationId: BalanceAnalytics_generateAnalyticsReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Request Body

application/json

schema BalanceAndCashFlowAnalyticsReportConstraints

Property	Type	Required
accountIds	array	optional
lengthOfReport	integer	optional

Responses

200

Response given when balance analytics were generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

409

Resource conflict

POST /analytics/balance/v1/customer/{customerId}

POST /analytics/balance/v1/customer/{customerId}/fcra Generate Balance Analytics - FCRA

Balance Analytics for Business analyzes bank balances over time to report metrics and identify behavior that may indicate risk.

Calculated metrics include:

Current/available account balances
Minimum/maximum/average account balances over the requested time
period and broken down by month
Daily ending balance of accounts for each day in the requested time
period
Propensity of the customer’s account balances to increase week over
week
Number of days in the requested time period ending with a negative
balance

This version of the API is intended for production use. It maintains and enforces all compliance with FCRA rules and requirements.

Note: this is a premium service, billable per every successful API call for non-testing customers.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get Balance Analytics Report - FCRA (operation: GetObbAnalyticsReportFCRA).

Supported regions:

operationId: BalanceAnalytics_generateFcraAnalyticsReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Request Body

application/json

schema BalanceAndCashFlowAnalyticsReportConstraints

Property	Type	Required
accountIds	array	optional
lengthOfReport	integer	optional

Responses

200

Response given when balance analytics (FCRA) were generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

409

Resource conflict

POST /analytics/balance/v1/customer/{customerId}/fcra

POST /decisioning/v2/customers/{customerId}/reports/balance-analytics/userTypes/{userType} Generate Balance Analytics Report - Personal/Business

Generate a Balance Analytics Report for a given customer. This service retrieves up to two years of transaction history from connected accounts.

Balance Analytics analyzes bank balances over time to report metrics and identify behavior that may indicate risk.

Before calling this API, A consumer or business may need to be created for the given customer ID based on the user type (see Consumer/Business APIs).

If no account type of checking or savings is found, the service will return HTTP 400 Bad Request.

This is a premium service, billable per every successful API call for non-testing customers. A successful call to this API will generate analytics report which can be retrieved via Get Report by Customer or Get Report by Consumer.

Supported regions:

operationId: BalanceAnalytics_generateReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
userType	path	optional		UserType indicates if the request is for a business or personal use case, Allowed values: business/personal.
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema AnalyticsReportConstraints

Property	Type	Required
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
analyticsReportData	object	optional
└ forCraPurpose	boolean	required
└ timeIntervalTypes	array	optional
└ applicantIsPersonalGuarantor	boolean	optional

Responses

202

The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don’t use a callback URL, Get Report returns a minimal report with the following status: ‘inProgress’. Repeat the call every 20 seconds until Get Report returns a different status.

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/reports/balance-analytics/userTypes/{userType}

Bankstatements 1 endpoints

POST /decisioning/v2/customers/{customerId}/statement Generate Statement Report

Generate a Statement Report for the given accounts under the given customer.

This is a premium service. A billable event will be created upon the successful generation of the Statement Report.

Before calling this API, a consumer must be created for the given customer ID (see Consumers APIs).

Supported regions:

operationId: BankStatements_generateReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema StatementReportConstraints

Property	Type	Required
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
statementReportData	object	required
└ accountId	integer	required
└ statementIndex	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/statement

Businessesapi 1 endpoints

POST /business-services/customers/{customer_id}/businesses Create a New Business for a Customer

Create a new business record for the associated customer.
A customer can have one business record associated.

Supported regions:

operationId: BusinessesApi_createNewBusiness

Parameters

Name	In	Required	Type	Description
customer_id	path	optional		Unique identifier of the customer

Request Body

application/json

schema NewBusiness

Property	Type	Required
url	string	optional
name	string	required
type	string	optional
email	string	optional
taxId	string	optional
address	object	required
└ city	string	optional
└ state	string	optional
└ country	string	optional
└ postalCode	string	optional
└ addressLine1	string	optional
└ addressLine2	string	optional
phoneNumber	object	required
└ phoneNo	string	optional
└ countryCode	string	optional
personallyLiable	boolean	required

Responses

200

The business was successfully created.

404

The customer does not exist

409

The resource already exists

POST /business-services/customers/{customer_id}/businesses

Cashflow 2 endpoints

POST /decisioning/v2/customers/{customerId}/cashFlowBusiness Generate Cash Flow Report - Business

Generate a Cash Flow Report (Business) report for all checking and savings under the given customer. This service retrieves up to two years of transaction history for the given account. It then uses this information to generate the CFR report. A consumer is not required to generate this report.

This report is not provided under FCRA rules, and this report is not available in the Finicity Consumer Portal for the borrower to view.

If no account type of checking or savings is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: CashFlow_generateReportBusiness

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema CashFlowReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/cashFlowBusiness

POST /decisioning/v2/customers/{customerId}/cashFlowPersonal Generate Cash Flow Report - Personal

Generate a Cash Flow Report (Personal) report for all checking and savings under the given customer. This service retrieves up to two years of transaction history for the given account. It then uses this information to generate the CFR report.

This report is provided under FCRA rules, with Finicity acting as the CRA (Consumer Reporting Agency). If an individual account is included in the report - for example, with an individual acting as an personal guarantor on the loan - then this version of the report should be used. In case of an adverse action on the loan where the decision was based on this report, then the borrower can be referred to the Finicity Consumer Portal where they can view this report and submit a dispute if they feel any information in this report is inaccurate.

Before calling this API, a consumer must be created for the given customer ID (see Consumers APIs).

If no account type of checking or savings is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: CashFlow_generatePersonalReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema CashFlowReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/cashFlowPersonal

Cashflowanalytics 3 endpoints

POST /analytics/cashflow/v1/customer/{customerId} Generate Cash Flow Analytics

Cash Flow Analytics for Business analyzes cash flow over time to report metrics and identify behavior that may indicate risk.

Calculated metrics include:

Average transaction value by month over the requested time period
Net cash flow over the requested time period and broken down by month
Count and report of weeks in the requested time period where there
were zero transactions posted to the customer’s accounts
Minimum/maximum/average/sum/count of deposits by month
Minimum/maximum/average/sum/count of withdrawals by month
Estimated amount of deposits that can be classified as business
revenue
Number of transactions posted incurring a non-sufficient funds (NSF)
fee, and net amount charged in NSF fees

This version of the API is intended for piloting and integration testing your application with the Cash Flow Analytics product. It does not adhere to FCRA requirements, and should not be used for production/lending purposes. See Generate Cash Flow Analytics - FCRA for the FCRA compliant version of this API.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get Cash Flow Analytics Report (operation: GetCashFlowAnalyticsReport).

Supported regions:

operationId: CashFlowAnalytics_generateAnalytics

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Request Body

application/json

schema BalanceAndCashFlowAnalyticsReportConstraints

Property	Type	Required
accountIds	array	optional
lengthOfReport	integer	optional

Responses

200

Response given when cash flow analytics were generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

409

Resource conflict

POST /analytics/cashflow/v1/customer/{customerId}

POST /analytics/cashflow/v1/customer/{customerId}/fcra Generate Cash Flow Analytics - FCRA

Cash Flow Analytics for Business analyzes cash flow over time to report metrics and identify behavior that may indicate risk.

Calculated metrics include:

Average transaction value by month over the requested time period
Net cash flow over the requested time period and broken down by month
Count and report of weeks in the requested time period where there
were zero transactions posted to the customer’s accounts
Minimum/maximum/average/sum/count of deposits by month
Minimum/maximum/average/sum/count of withdrawals by month
Estimated amount of deposits that can be classified as business
revenue
Number of transactions posted incurring a non-sufficient funds (NSF)
fee, and net amount charged in NSF fees

This version of the API is intended for production use. It maintains and enforces all compliance with FCRA rules and requirements.

Note: this is a premium service, billable per every successful API call for non-testing customers.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get Cash Flow Analytics Report - FCRA (operation: GetCashFlowAnalyticsReportFCRA).

Supported regions:

operationId: CashFlowAnalytics_generateFcraAnalyticsReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Request Body

application/json

schema BalanceAndCashFlowAnalyticsReportConstraints

Property	Type	Required
accountIds	array	optional
lengthOfReport	integer	optional

Responses

200

Response given when cash flow analytics (FCRA) were generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

409

Resource conflict

POST /analytics/cashflow/v1/customer/{customerId}/fcra

POST /decisioning/v2/customers/{customerId}/reports/cashflow-analytics/userTypes/{userType} Generate Cashflow Analytics Report - Personal/Business

Generate a Cashflow Analytics Report for a given customer. This service retrieves up to two years of transaction history from connected accounts.

Cashflow Analytics analyzes transaction over time to report metrics and identify behavior that may indicate risk.

Before calling this API, A consumer or business may need to be created for the given customer ID based on the user type (see Consumer/Business APIs).

If no account type of checking or savings is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: CashFlowAnalytics_generateReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
userType	path	optional		UserType indicates if the request is for a business or personal use case, Allowed values: business/personal.
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema AnalyticsReportConstraints

Property	Type	Required
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
analyticsReportData	object	optional
└ forCraPurpose	boolean	required
└ timeIntervalTypes	array	optional
└ applicantIsPersonalGuarantor	boolean	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/reports/cashflow-analytics/userTypes/{userType}

Connect🔗 7 endpoints

POST /connect/v2/generate Generate Connect URL

Generate a Connect 2.0 URL link to add within your own applications.

Optional Parameters:

experience: Configure different customer experiences per Connect session by changing the brand, color, logo, icon, the type of credit decisioning report to generate after the session ends, and more.
language: By default, the Connect application is in English. You don’t need to pass this parameter unless you want to translate Connect into one of our supported languages.
- Spanish (United States)
- French (Canada)

MVS Developers: You can pre-populate the consumer’s SSN on the Find employment records page at the beginning of the MVS payroll app. Pass the SSN value for the consumer in the body of the request call.

Supported regions:

operationId: Connect_generateUrl

Request Body

application/json

schema ConnectParameters

Property	Type	Required
webhook	string	optional
fromDate	integer	optional
language	string	optional
isWebView	boolean	optional
partnerId	string	required
consumerId	string	optional
customerId	string	required
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
webhookHeaders	object	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
webhookContentType	string	optional
institutionSettings	object	optional
optionalConsumerInfo	object	optional
└ dob	integer	optional
└ ssn	string	required

Responses

200

The URL link was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/generate

POST /connect/v2/generate/fix Generate Fix Connect URL

Use the Connect Fix API when the following conditions occur:

The connection to the user’s financial institution is lost
The user’s credentials were updated (for any number of reasons)
The user’s MFA challenge has expired

Supported regions:

operationId: Connect_fixUrlGeneration

Request Body

application/json

schema FixConnectParameters

Property	Type	Required
webhook	string	optional
language	string	optional
isWebView	boolean	optional
partnerId	string	required
customerId	string	required
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
webhookHeaders	object	optional
institutionLoginId	string	required
webhookContentType	string	optional

Responses

200

The URL link was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /connect/v2/generate/fix

POST /connect/v2/generate/jointBorrower Generate Connect URL - Joint Borrower

Same as Connect Full (POST /connect/v2/generate) but for joint borrowers.

MVS prompts both the primary and joint borrower to enter each of their financial, payroll, and paystub information in the same Connect session.

Supported regions:

operationId: Connect_generateJointBorrowerUrl

Request Body

application/json

schema ConnectJointBorrowerParameters

Property	Type	Required
webhook	string	optional
fromDate	integer	optional
language	string	optional
borrowers	array	required
└ type	string	required
└ consumerId	string	required
└ customerId	string	required
└ optionalConsumerInfo	object	optional
└ dob	integer	optional
└ ssn	string	required
partnerId	string	required
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
webhookHeaders	object	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
webhookContentType	string	optional
institutionSettings	object	optional

Responses

200

The URL link was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/generate/jointBorrower

POST /connect/v2/generate/lite Generate Lite Connect URL

Connect Lite is a variation of Connect Full (POST /connect/v2/generate), which has a limited set of features.

Sign in, user’s credentials, and Multi-Factor Authentication (MFA)
No user account management

The Connect Web SDK isn’t a requirement when using Connect lite. However, if you want to use the SDK events, routes, and user events, then you must integrate with the Connect Web SDK.

Supported regions:

operationId: Connect_generateLiteUrl

Request Body

application/json

schema LiteConnectParameters

Property	Type	Required
webhook	string	optional
language	string	optional
isWebView	boolean	optional
partnerId	string	required
customerId	string	required
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
institutionId	integer	required
webhookHeaders	object	optional
webhookContentType	string	optional

Responses

200

The URL link was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/generate/lite

POST /connect/v2/generate/microentry/verify Account Validation Assistant User verification of microdeposits

The UI re-engages the consumer to enter two microdeposit amounts found in their account and validates them.

Supported regions:

operationId: Connect_verifyMicroEntryMicrodeposits

Request Body

application/json

schema MicroEntryVerifyRequestParameter

Property	Type	Required
webhook	string	optional
accountId	string	optional
partnerId	string	optional
customerId	string	optional
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
webhookHeaders	object	optional
webhookContentType	string	optional

Responses

200

The URL link was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/generate/microentry/verify

POST /connect/v2/send/email Send Connect Email

Same as Connect Full (POST /connect/v2/generate) but send a Connect email to a consumer.

Supported regions:

operationId: Connect_sendConnectEmail

Request Body

application/json

schema ConnectEmailParameters

Property	Type	Required
email	object	required
└ to	string	required
└ from	string	optional
└ subject	string	optional
└ firstName	string	optional
└ signature	array	optional
└ supportPhone	string	optional
└ institutionName	string	optional
└ institutionAddress	string	optional
webhook	string	optional
fromDate	integer	optional
language	string	optional
partnerId	string	required
consumerId	string	required
customerId	string	required
experience	string	optional
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
webhookHeaders	object	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
webhookContentType	string	optional
institutionSettings	object	optional
optionalConsumerInfo	object	optional
└ dob	integer	optional
└ ssn	string	required

Responses

200

The URL link was successfully generated and the email sent

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/send/email

POST /connect/v2/send/email/jointBorrower Send Connect Email - Joint Borrower

Same as Connect Joint Borrower (POST /connect/v2/generate/jointBorrower) but send a Connect email to at least one of the joint borrower’s email addresses.

When the consumer opens the email, MVS prompts both the primary and joint borrower to enter each of their financial, payroll, and paystub information in the same Connect session.

Supported regions:

operationId: Connect_sendEmailJointBorrower

Request Body

application/json

schema ConnectJointBorrowerEmailParameters

Property	Type	Required
email	object	required
└ to	string	required
└ from	string	optional
└ subject	string	optional
└ firstName	string	optional
└ signature	array	optional
└ supportPhone	string	optional
└ institutionName	string	optional
└ institutionAddress	string	optional
webhook	string	optional
fromDate	integer	optional
language	string	optional
borrowers	array	required
└ type	string	required
└ consumerId	string	required
└ customerId	string	required
└ optionalConsumerInfo	object	optional
└ dob	integer	optional
└ ssn	string	required
partnerId	string	required
experience	string	required
redirectUri	string	optional
webhookData	object	optional
singleUseUrl	boolean	optional
webhookHeaders	object	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
webhookContentType	string	optional
institutionSettings	object	optional

Responses

200

The URL link was successfully generated and the email sent

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /connect/v2/send/email/jointBorrower

Consumers 1 endpoints

POST /decisioning/v1/customers/{customerId}/consumer Create Consumer

Create a consumer record associated with the given customer. A consumer persists as the owner of any reports that are generated, even after the original customer is deleted from the system.

A consumer must be created for the given customer before calling any of the Generate Report services.

Supported regions:

operationId: Consumers_createConsumerRecord

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID

Request Body

application/json

schema NewConsumer

Property	Type	Required
ssn	string	required
zip	string	required
city	string	required
email	string	optional
phone	string	required
state	string	required
suffix	string	optional
address	string	required
birthday	object	required
└ year	integer	optional
└ month	integer	optional
└ dayOfMonth	integer	optional
lastName	string	required
firstName	string	required

Responses

201

The consumer was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

409

The resource already exists

POST /decisioning/v1/customers/{customerId}/consumer

Customers 2 endpoints

POST /aggregation/v2/customers/active Add Customer

Enroll an active customer, which is the actual owner of one or more real-world accounts. This is a billable customer.

Active customers must use the “FinBank Billable” profiles for testing purposes.

Supported regions:

operationId: Customers_enrollActiveCustomer

Request Body

application/json

schema NewCustomer

Property	Type	Required
email	string	optional
phone	string	optional
lastName	string	optional
username	string	required
firstName	string	optional
applicationId	string	optional

Responses

201

The customer was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

429

The service can’t accept more requests or is not available from the Test Drive.

POST /aggregation/v2/customers/active

POST /aggregation/v2/customers/testing Add Testing Customer

Enroll a testing customer (Test Drive accounts).

For using testing customers with FinBank OAuth, you must register a test application with your systems engineer or account manager. Then, use that testing applicationId when creating testing customers.

Testing Customers can access FinBank profiles (except “FinBank Billable” profiles), and cannot access live financial institutions.

Supported regions:

operationId: Customers_enrollTestingCustomer

Request Body

application/json

schema NewCustomer

Property	Type	Required
email	string	optional
phone	string	optional
lastName	string	optional
username	string	required
firstName	string	optional
applicationId	string	optional

Responses

201

The customer was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

POST /aggregation/v2/customers/testing

Paystatements 1 endpoints

POST /aggregation/v1/customers/{customerId}/payStatements Store Customer Pay Statement

Upload pay statements for a customer.

Supported regions:

operationId: PayStatements_uploadForCustomer

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID

Request Body

application/json

schema PayStatement

Property	Type	Required
label	string	required
statement	string	required

Responses

200

The pay statement was successfully uploaded

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/payStatements

Paymenthistory 2 endpoints

POST /analytics/payment-history/v1/customer/{customerId} Generate Payment History

Payment history report analyzes up to 12-months of transactions and predicts the probability that a SMB will experience a payment risk event, such as NSF/Overdraft or missed recurring payments, in the near future when making a payment. The Risk Score provided in the report is a 2-digit ranking with four levels of risk going from low to high.

Some of the highlights of calculated risk present in the report include:

Risk Score representing the likelihood of a missed payment
based on analysis of permissioned open-banking data
Monthly average balance for all accounts by month in the requested
time period
Total deposit amount by month for all accounts in the requested time
period
Total withdrawal amounts by month for all accounts in the requested
time period
Number of NSF counts and aggregate amount per month in the requested
time period
Recurring loan payment amounts per month in the requested time period
Insurance payment amount per month in the requested time period
Tax payment amounts per month in the requested time period

This version of the API is intended for piloting and integration testing your application with the Payment History product. It does not adhere to FCRA requirements, and should not be used for production/lending purposes. See Generate Payment History - FCRA for the FCRA compliant version of this API.

Note: this is a premium service, billable per every successful API call for non-testing customers.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get OBB Analytics Report (operation: GetObbAnalyticsReport).
Note: this is a premium service, billable per every successful API call for non-testing customers.

Supported regions:

operationId: PaymentHistory_generateCustomerPaymentReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Responses

200

Response given when payment history was generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

POST /analytics/payment-history/v1/customer/{customerId}

POST /analytics/payment-history/v1/customer/{customerId}/fcra Generate Payment History - FCRA

Some of the highlights of calculated risk present in the report include:

Risk Score representing the likelihood of a missed payment
based on analysis of permissioned open-banking data
Monthly average balance for all accounts by month in the requested
time period
Total deposit amount by month for all accounts in the requested time
period
Total withdrawal amounts by month for all accounts in the requested
time period
Number of NSF counts and aggregate amount per month in the requested
time period
Recurring loan payment amounts per month in the requested time period
Insurance payment amount per month in the requested time period
Tax payment amounts per month in the requested time period

This version of the API is intended for production use. It maintains and
enforces all compliance with FCRA rules and requirements.

Note: this is a premium service, billable per every successful API call for non-testing customers.

A successful call to this API will generate analytics and store a report within Finicity. The report can be retrieved via Get OBB Analytics Report - FCRA (operation: GetObbAnalyticsReportFcra).

Supported regions:

operationId: PaymentHistory_generateFcraPaymentReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
reference-number	query	optional	string	Partner-provided reference number to correlate reports.

Responses

200

Response given when payment history (FCRA) was generated successfully, providing the caller with a report ID which can be used to retrieve the report as JSON or a PDF.

400

A bad request was provided

401

Unauthorized request

403

Access forbidden

404

Resource not found

409

Resource conflict

POST /analytics/payment-history/v1/customer/{customerId}/fcra

Thirdpartyaccess 1 endpoints

POST /aggregation/v1/partners/accessKey Generate Third Party Access Key

Generate access key for third party partners.
A partner can provide access to third party partners with this access key.

operationId: ThirdPartyAccess_generateKey

Request Body

application/json

schema ThirdPartyAccessKeyData

Property	Type	Required
products	array	required
└ payorId	string	optional
└ product	string	required
└ maxCalls	integer	optional
└ accountId	string	required
└ accessPeriod	object	required
└ type	string	required
└ endTime	string	required
└ startTime	string	required
partnerId	string	required
customerId	string	required
provenance	object	optional
└ token	string	optional
└ ipAddress	string	optional
└ clientFingerprint	string	optional
thirdPartyPartnerId	string	required

Responses

200

The third party access key was successfully generated

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/partners/accessKey

Transactions 2 endpoints

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions/historic Load Historic Transactions for Customer Account

Connect to the account’s financial institution and load up to 24 months of historic transactions for the account. Length of history varies by institution.

This is a premium service. The billable event is a call to this service specifying a customer ID that has not been seen before by this service. (If this service is called multiple times with the same customer ID, to load transactions from multiple accounts, only one billable event has occurred.)

The recommended timeout setting for this request is 180 seconds in order to receive a response. However, you can terminate the connection after making the call the operation will still complete. You will have to pull the account records to check for an updated aggregation attempt date to know when the refresh is complete.

The date range sent to the institution is calculated from the account’s createdDate. This means that calling this service a second time for the same account normally will not add any new transactions for the account. For this reason, a second call to this service for a known account ID will usually return immediately.

In a few specific scenarios, it may be desirable to force a second connection to the institution for a known account ID. Some examples are:

The institution’s policy has changed, making more transactions available
Finicity has now added a longer transaction history support for the institution
The first call encountered an error, and the resulting Aggregation Ticket has now been fixed by the Finicity Support Team

In these cases, the POST request can contain the parameter force=true in the request body to force the second connection.

Supported regions:

operationId: Transactions_loadHistoricTransactionsForCustomerAccount

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
accountId	path	optional		The account ID

Responses

203

The response contains an MFA challenge in XML or JSON format. Contact your Account Manager or Systems Engineers to determine the best route to handle this error.

204

Historic transactions have been loaded successfully. The transactions are now available by calling the Get Customer Account Transactions API.

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions/historic

POST /decisioning/v2/customers/{customerId}/transactions Generate Transactions Report

Generate a Transaction Report for the given accounts under the given customer. This service retrieves up to 24 months of transaction history for the given customer. It then uses this information to generate the Transaction Report.

This is a premium service. A billable event will be created upon the successful generation of the Transactions Report.

Before calling this API, a consumer must be created for the given customer ID (see Consumers APIs).

There cannot be more than 24 months between fromDate and toDate.

Supported regions:

operationId: Transactions_get24MonthsHistoryAndGenerateReport

Parameters

Name	In	Required	Type	Description
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.
customerId	path	optional		A customer ID
toDate	query	optional		A end date
includePending	query	optional		If pending transactions must be included

Request Body

application/json

schema TransactionsReportConstraints

Property	Type	Required
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/transactions

Txpush 2 endpoints

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions Create TxPush Test Transaction

Inject a transaction into the transaction list for a testing account. This allows an app to trigger TxPush notifications for the account in order to test the app’s TxPush Listener service. This causes the platform to send one transaction event and one account event (showing that the account balance has changed). This service is only supported for testing accounts.

For additional details on this process, see TxPush Listener Service.

Supported regions:

operationId: TxPush_injectTestTransaction

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
accountId	path	optional		The account ID

Request Body

application/json

schema TestTxPushTransaction

Property	Type	Required
amount	number	required
status	string	optional
postedDate	integer	optional
description	string	required
transactionDate	integer	required

Responses

201

The test notification was successfully sent

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/transactions

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush Subscribe to TxPush Notifications

Each call to this service will return two records, one with class account and one with class transaction. Account events are sent when values change in the account’s fields (such as balance or interestRate). Transaction events are sent whenever a new transaction is posted for the account. For institutions that do not provide TxPush services, notifications are sent as soon as Finicity finds a new transaction or new account data through regular aggregation processes.

The listener’s URL must be secure (HTTPS) for any real-world account. In addition, the client’s TxPush Listener will need to be verified. HTTP and HTTPS connections are only allowed on the standard ports 80 (HTTP) and 443 (HTTPS). The use of other ports will result with the call failing.

For additional details on this process, see TxPush Listener Service.

Supported regions:

operationId: TxPush_subscribeNotifications

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
accountId	path	optional		The account ID

Request Body

application/json

schema TxPushSubscriptionParameters

Property	Type	Required
callbackUrl	string	required

Responses

201

The subscription was successfully created

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /aggregation/v1/customers/{customerId}/accounts/{accountId}/txpush

Verifyassets 4 endpoints

POST /decisioning/v2/customers/{customerId}/assetSummary Generate Prequalification (Non-CRA) Report

Retrieve all checking, savings, money market, and investment accounts for a customer. The account, owner information, and the number of insufficient funds (NSFs) for checking accounts are also provided.

If no account type of checking, savings, money market, or investment is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: VerifyAssets_getAssetSummary

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema PrequalificationReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/assetSummary

POST /decisioning/v2/customers/{customerId}/preQualVoa Generate Prequalification (CRA) Report

Retrieve all checking, savings, money market, and investment accounts for a consumer. The account, owner information, and the number of insufficient funds (NSFs) for checking accounts are also provided.

If no account of type checking, savings, money market, or investment is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: VerifyAssets_getCheckingSavingsInvestmentAccounts

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema PrequalificationReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/preQualVoa

POST /decisioning/v2/customers/{customerId}/voa Generate VOA Report

Generate a Verification of Assets (VOA) report for all checking, savings, money market, and investment accounts for the given customer. This service retrieves up to twelve months of transaction history for each account and uses this information to generate the VOA report.

This is a premium service. The billing rate is the variable rate for Verification of Assets under the current subscription plan. The billable event is the successful generation of a VOA report.

Before calling this API, a consumer must be created for the given customer ID (see Consumers APIs).

If no account of type checking, savings, money market, or investment is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: VerifyAssets_customerVOAReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOAReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voa

POST /decisioning/v2/customers/{customerId}/voaHistory Generate VOA With Income Report

Generate a Verification of Assets with Income (VOAI) report for all checking, savings, money market, and investment accounts for the given customer. This service retrieves up to 24 months of transaction history for each account and uses this information to generate the VOAI report. The report includes 1 - 6 months of all debit and credit transactions for asset verification. By default, the history is set to 61 days, however, you can change the transaction history in this section by setting the fromDate parameter. The report also includes up to 24 months of income credit transactions (ordered by account and confidence level) regardless of fromDate for income verification.

This is a premium service. The billable event is the successful generation of a VOAI report.

Before calling this API, a consumer must be created for the given customer ID (see Consumers APIs).

If no account of type checking, savings, money market, or investment is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: VerifyAssets_generateVOAWithIncomeReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOAWithIncomeReportConstraints

Property	Type	Required
showNsf	boolean	optional
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voaHistory

Verifyincomeandemployment 7 endpoints

POST /decisioning/v2/customers/{customerId}/payStatement Generate Pay Statement Report

Generate Pay Statement Extraction Report for the given customer. This service accepts asset IDs of the stored pay statements to generate a Pay Statement Extraction Report.

This is a premium service. The billing rate is the variable rate for Pay Statement Extraction Report under the current subscription plan. The billable event is the successful generation of a Pay Statement Extraction Report.

Supported regions:

operationId: VerifyIncomeAndEmployment_generatePayStatementReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema PayStatementReportConstraints

Property	Type	Required
paystatementReport	object	required
└ assetIds	array	required
└ extractEarnings	boolean	optional
└ extractDeductions	boolean	optional
└ extractDirectDeposit	boolean	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/payStatement

POST /decisioning/v2/customers/{customerId}/voePayroll Generate VOE - Payroll Report

Generate or refresh a VOE - Payroll report. Often used as a complementary report to the VOIE-Payroll report to fulfill the pre-close VOE requirements. It retrieves the customer’s employment details and employment status through the payroll source without any income information.

This is a premium service. The billable event is the successful generation of a VOE - Payroll report.

Supported regions:

operationId: VerifyIncomeAndEmployment_generateVoePayrollReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema PayrollReportConstraints

Property	Type	Required
purpose	string	optional
payrollData	object	required
└ dob	integer	required
└ ssn	string	required
└ reportId	string	optional
marketSegment	string	optional
excludeEmpInfo	boolean	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
payStatementsFromDate	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voePayroll

POST /decisioning/v2/customers/{customerId}/voeTransactions Generate VOE - Transactions Report

Premium Service: A billable event when the API response is successful.

MVS-Direct integration developers only.

Used as a complimentary report to the VOA with Income and VOIE - Paystub (with TXVerify) reports and used to fulfill the pre-close VOE requirements.

Retrieve the latest credit transaction information from the borrower’s connected bank accounts and groups them into income streams so that you can view their payment history to ensure a direct deport was made within the expected cadence. The report displays transaction descriptions without any dollar amounts so that income re-verification isn’t necessary.

Supported regions:

operationId: VerifyIncomeAndEmployment_generateVOETransactionsReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOETransactionsReportConstraints

Property	Type	Required
fromDate	integer	optional
reportId	string	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voeTransactions

POST /decisioning/v2/customers/{customerId}/voi Generate VOI Report

Generate a Verification of Income (VOI) report for all checking, savings, and money market accounts for the given customer. This service retrieves up to two years of transaction history for each account and uses this information to generate the VOI report.

This is a premium service. The billing rate is the variable rate for Verification of Income under the current subscription plan. The billable event is the successful generation of a VOI report.

If no account of type checking, savings, or money market is found, the service will return HTTP 400 Bad Request.

Supported regions:

operationId: VerifyIncomeAndEmployment_createVOIReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOIReportConstraints

Property	Type	Required
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voi

POST /decisioning/v2/customers/{customerId}/voiePayroll Generate VOIE - Payroll Report

Generate or refresh a VOIE - Payroll report. For clients using the product via a consumer permissioning experience via Connect, the original VOIE - Payroll report generates when the consumer completes the Connect experience, and this API is only used for future report refreshes without reengaging the consumer.

This is a premium service. The billable event is the successful generation of a VOIE - Payroll report.

Supported regions:

operationId: VerifyIncomeAndEmployment_refreshVOIEPayrollReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema PayrollReportConstraints

Property	Type	Required
purpose	string	optional
payrollData	object	required
└ dob	integer	required
└ ssn	string	required
└ reportId	string	optional
marketSegment	string	optional
excludeEmpInfo	boolean	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
payStatementsFromDate	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voiePayroll

POST /decisioning/v2/customers/{customerId}/voieTxVerify/withInterview Generate VOIE - Paystub (with TXVerify) Report

Generate a VOIE - Paystub (with TXVerify) report for all checking and savings under the given customer. This service retrieves up to two years of transaction history for the given accounts. It then uses this information as well as the provided paystub(s), which are passed into the request body as asset IDs (generated using the Store Customer Pay Statement API) to generate the VOIE - Paystub (with TXVerify) report.

Note: if you are using this API to refresh the bank transactions, use the same asset ID from the first report. A new paystub is not required unless the paystub is too old for underwriting requirements. Using the same asset ID that was on the original report and the previously extracted details will be used to speed up report generation response time.

This is a premium service. The billing rate is the variable rate for VOIE TXVerify under the current subscription plan. The billable event is the successful generation of a VOIE TXVerify Report.

Supported regions:

operationId: VerifyIncomeAndEmployment_generateVOIEPaystubWithTxVerifyReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOIEWithTXVerifyReportConstraints

Property	Type	Required
fromDate	integer	optional
accountIds	string	optional
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
voieWithInterviewData	object	required
└ extractEarnings	boolean	optional
└ extractDeductions	boolean	optional
└ txVerifyInterview	array	required
└ assetId	string	required
└ accounts	array	optional
└ extractDirectDeposit	boolean	optional
incomeStreamConfidenceMinimum	integer	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voieTxVerify/withInterview

POST /decisioning/v2/customers/{customerId}/voieTxVerify/withStatement Generate VOIE - Paystub Report

Generate a VOIE - Paystub report. This service uses the provided paystub(s), which are passed into the request body as asset IDs (generated using the Store Customer Pay Statement API) to generate the VOIE - Paystub report with digitized paystub details.

This is a premium service. The billing rate is the variable rate for VOIE - Paystub under the current subscription plan. The billable event is the successful generation of a VOIE - Paystub Report.

Supported regions:

operationId: VerifyIncomeAndEmployment_generateVoiePaystubReport

Parameters

Name	In	Required	Type	Description
customerId	path	optional		A customer ID
callbackUrl	query	optional	string	A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code.

Request Body

application/json

schema VOIEReportConstraints

Property	Type	Required
reportCustomFields	array	optional
└ label	string	optional
└ shown	boolean	optional
└ value	string	optional
voieWithStatementData	object	required
└ assetIds	array	required
└ extractEarnings	boolean	optional
└ extractDeductions	boolean	optional
└ extractDirectDeposit	boolean	optional

Responses

202

400

The request was rejected

401

The request lacks valid authentication credentials. Check “Finicity-App-Key” or “Finicity-App-Token”.

404

The resource doesn’t exist

POST /decisioning/v2/customers/{customerId}/voieTxVerify/withStatement

Load more endpoints

Schemas

object ACHDetails

{
  "type": "object",
  "required": [
    "routingNumber",
    "realAccountNumber"
  ],
  "properties": {
    "routingNumber": {
      "type": "string",
      "example": "123456789",
      "description": "The routing number of the financial institution for specific customer account"
    },
    "realAccountNumber": {
      "type": "string",
      "example": "002345678901",
      "description": "The account number for initiating ACH transfers for this account"
    }
  },
  "description": "The routing and account number information to initiate ACH transfers"
}

object AFBalanceAnalyticsReport

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/AnalyticsReportAck"
    },
    {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "example": 730,
          "description": "Number of days covered by the report"
        },
        "endDate": {
          "$ref": "#/components/schemas/ReportEndDate"
        },
        "seasoned": {
          "type": "boolean",
          "example": true,
          "description": "\"true\" if the report covers more than 365 days"
        },
        "startDate": {
          "$ref": "#/components/schemas/ReportStartDate"
        },
        "institutions": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ReportInstitution"
          },
          "description": "A list of institution records, including information about the individual accounts used in this report"
        },
        "customerAnalytics": {
          "$ref": "#/components/schemas/CustomerAnalytics"
        }
      }
    }
  ],
  "description": "A Balance Analytics Report"
}

object AFBusiness

{
  "type": "object",
  "required": [
    "name",
    "address"
  ],
  "properties": {
    "name": {
      "$ref": "#/components/schemas/BusinessName"
    },
    "address": {
      "type": "object",
      "properties": {
        "city": {
          "$ref": "#/components/schemas/City"
        },
        "state": {
          "$ref": "#/components/schemas/State"
        },
        "country": {
          "$ref": "#/components/schemas/Country"
        },
        "postalCode": {
          "$ref": "#/components/schemas/ZipCode"
        },
        "addressLine1": {
          "$ref": "#/components/schemas/AddressLine1"
        },
        "addressLine2": {
          "$ref": "#/components/schemas/AddressLine2"
        }
      }
    }
  }
}

object AFCashFlowAnalyticsReport

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/AnalyticsReportAck"
    },
    {
      "type": "object",
      "properties": {
        "days": {
          "type": "integer",
          "example": 730,
          "description": "Number of days covered by the report"
        },
        "endDate": {
          "$ref": "#/components/schemas/ReportEndDate"
        },
        "seasoned": {
          "type": "boolean",
          "example": true,
          "description": "\"true\" if the report covers more than 365 days"
        },
        "startDate": {
          "$ref": "#/components/schemas/ReportStartDate"
        },
        "institutions": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ReportInstitution"
          },
          "description": "A list of institution records, including information about the individual accounts used in this report"
        },
        "customerAnalytics": {
          "$ref": "#/components/schemas/CustomerAnalytics"
        }
      }
    }
  ],
  "description": "A Cash Flow Analytics Report"
}

object AccessToken

{
  "type": "object",
  "required": [
    "token"
  ],
  "properties": {
    "token": {
      "type": "string",
      "example": "YBh22Sb9Es6e66Q7lWdt",
      "description": "The access token value"
    }
  },
  "description": "A temporary access token to be passed in the `Finicity-App-Token` HTTP header of all subsequent API requests"
}

object AccountAnalytics

{
  "type": "object",
  "required": [
    "transactionalAttributes",
    "stateAttributes",
    "streams"
  ],
  "properties": {
    "streams": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StreamModel"
      },
      "description": "List of generated streams"
    },
    "stateAttributes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StateAttribute"
      },
      "description": "List of calculated state attributes"
    },
    "transactionalAttributes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TransactionalAttribute"
      },
      "description": "List of calculated transactional attributes"
    }
  },
  "description": "Analytics calculated for one account in the report."
}

object AccountDetails

{
  "type": "object",
  "properties": {
    "vestedBalance": {
      "type": "number",
      "example": 300000,
      "description": "Only available for investment accounts. Vested amount in account."
    },
    "currentLoanBalance": {
      "type": "number",
      "example": 0,
      "description": "Only available for investment accounts. Current loan balance."
    },
    "availableCashBalance": {
      "type": "number",
      "example": 1500,
      "description": "Only available for investment accounts. Amount available for cash withdrawal."
    },
    "interestMarginBalance": {
      "type": "number",
      "example": -50000,
      "description": "Only available for investment accounts. Net interest earned after deducting interest paid out."
    },
    "availableBalanceAmount": {
      "type": "number",
      "example": 1000,
      "description": "The available balance for the account"
    }
  }
}

object AccountDetailsTxBased

{
  "type": "object",
  "allOf": [
    {
      "$ref": "#/components/schemas/AccountDetails"
    },
    {
      "type": "object",
      "properties": {
        "marginBalance": {
          "type": "number",
          "example": 100,
          "description": "Net interest earned after deducting interest paid out"
        },
        "currentBalance": {
          "type": "number",
          "example": 1000,
          "description": "Current balance"
        }
      }
    }
  ]
}

string AccountId

{
  "type": "string",
  "example": "5011648377",
  "description": "An account ID"
}

string AccountNumberDisplay

{
  "type": "string",
  "description": "The account number from a financial institution in truncated format:\n\n  * Last four digits: \"1234\"\n\n  * Last four digits with suffix: \"1234-9\"\n\n  * Full value for string accounts: \"john@gmail.com\"\nexample: '1234-9'"
}

string AccountNumberLast4

{
  "type": "string",
  "example": "5678",
  "description": "The last 4 digits of the ACH account number"
}

object AccountOwner

{
  "type": "object",
  "required": [
    "ownerName",
    "ownerAddress"
  ],
  "properties": {
    "asOfDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "ownerName": {
      "type": "string",
      "example": "John Smith",
      "description": "The name of the account owner. Can be multiple account owners in one string. This is how the source data is returned from the institution."
    },
    "ownerAddress": {
      "$ref": "#/components/schemas/Address"
    }
  },
  "description": "Owner of a customer account"
}

object AccountOwnerAddress

{
  "type": "object",
  "properties": {
    "city": {
      "$ref": "#/components/schemas/City"
    },
    "type": {
      "$ref": "#/components/schemas/AddressType"
    },
    "line1": {
      "$ref": "#/components/schemas/AddressLine1"
    },
    "line2": {
      "$ref": "#/components/schemas/AddressLine2"
    },
    "line3": {
      "$ref": "#/components/schemas/AddressLine3"
    },
    "state": {
      "$ref": "#/components/schemas/State"
    },
    "country": {
      "$ref": "#/components/schemas/Country"
    },
    "postalCode": {
      "$ref": "#/components/schemas/ZipCode"
    },
    "ownerAddress": {
      "$ref": "#/components/schemas/Address"
    }
  },
  "description": "Account owner address"
}

array AccountOwnerAddresses

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AccountOwnerAddress"
  },
  "description": "List of addresses"
}

object AccountOwnerDetails

{
  "type": "object",
  "required": [
    "ownerName",
    "addresses"
  ],
  "properties": {
    "emails": {
      "$ref": "#/components/schemas/AccountOwnerEmails"
    },
    "phones": {
      "$ref": "#/components/schemas/AccountOwnerPhones"
    },
    "suffix": {
      "$ref": "#/components/schemas/Suffix"
    },
    "lastName": {
      "$ref": "#/components/schemas/LastName"
    },
    "addresses": {
      "$ref": "#/components/schemas/AccountOwnerAddresses"
    },
    "firstName": {
      "$ref": "#/components/schemas/FirstName"
    },
    "ownerName": {
      "$ref": "#/components/schemas/AccountOwnerName"
    },
    "middleName": {
      "$ref": "#/components/schemas/MiddleName"
    },
    "relationship": {
      "$ref": "#/components/schemas/AccountOwnerRelationshipType"
    },
    "documentations": {
      "$ref": "#/components/schemas/AccountOwnerDocumentations"
    },
    "identityInsights": {
      "$ref": "#/components/schemas/AccountOwnerIdentityInsights"
    },
    "nameClassification": {
      "$ref": "#/components/schemas/NameClassificationType"
    },
    "nameClassificationconfidencescore": {
      "$ref": "#/components/schemas/ClassificationConfidenceScore"
    }
  },
  "description": "Owner of a customer account"
}

object AccountOwnerDocumentation

{
  "type": "object",
  "properties": {
    "taxId": {
      "$ref": "#/components/schemas/TaxId"
    },
    "governmentId": {
      "$ref": "#/components/schemas/GovernmentId"
    },
    "taxIdCountry": {
      "$ref": "#/components/schemas/Country"
    }
  },
  "description": "Account owner documentation"
}

array AccountOwnerDocumentations

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AccountOwnerDocumentation"
  },
  "description": "List of account owner documentation"
}

object AccountOwnerEmail

{
  "type": "object",
  "properties": {
    "email": {
      "$ref": "#/components/schemas/EmailAddress"
    },
    "emailType": {
      "$ref": "#/components/schemas/AccountOwnerEmailType"
    },
    "isPrimary": {
      "$ref": "#/components/schemas/AccountOwnerEmailPrimary"
    }
  },
  "description": "Account owner email"
}

boolean AccountOwnerEmailPrimary

{
  "type": "boolean",
  "example": true,
  "description": "The email is primary."
}

string AccountOwnerEmailType

{
  "type": "string",
  "example": "Personal",
  "description": "The account owner's email type.\n\n* \"Personal\" \n\n* \"Business\""
}

array AccountOwnerEmails

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AccountOwnerEmail"
  },
  "description": "List of emails"
}

object AccountOwnerHolders

{
  "type": "object",
  "required": [
    "holders"
  ],
  "properties": {
    "holders": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AccountOwnerDetails"
      },
      "description": "List of account owners"
    }
  }
}

object AccountOwnerIdentityInsights

{
  "type": "object",
  "properties": {
    "ipRisk": {
      "$ref": "#/components/schemas/IpRisk"
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Warnings"
      }
    },
    "emailToName": {
      "$ref": "#/components/schemas/EmailToName"
    },
    "ipRiskScore": {
      "$ref": "#/components/schemas/IpRiskScore"
    },
    "phoneToName": {
      "$ref": "#/components/schemas/PhoneToName"
    },
    "isEmailValid": {
      "$ref": "#/components/schemas/EmailValid"
    },
    "isPhoneValid": {
      "$ref": "#/components/schemas/PhoneValid"
    },
    "phoneCarrier": {
      "$ref": "#/components/schemas/PhoneCarrier"
    },
    "addressToName": {
      "$ref": "#/components/schemas/AddressToName"
    },
    "phoneLineType": {
      "$ref": "#/components/schemas/PhoneLineType"
    },
    "ipLastSeenDays": {
      "$ref": "#/components/schemas/IpLastSeenDays"
    },
    "phoneToAddress": {
      "$ref": "#/components/schemas/PhoneToAddress"
    },
    "ipPhoneDistance": {
      "$ref": "#/components/schemas/IpPhoneDistance"
    },
    "phoneCountryCode": {
      "$ref": "#/components/schemas/PhoneCountryCode"
    },
    "identityRiskScore": {
      "$ref": "#/components/schemas/IdentityRiskScore"
    },
    "ipAddressDistance": {
      "$ref": "#/components/schemas/IpAddressDistance"
    },
    "phoneLastSeenDays": {
      "$ref": "#/components/schemas/PhoneLastSeenDays"
    },
    "emailFirstSeenDays": {
      "$ref": "#/components/schemas/EmailFirstSeenDays"
    },
    "addressValidityLevel": {
      "$ref": "#/components/schemas/AddressValidityLevel"
    },
    "identityNetworkScore": {
      "$ref": "#/components/schemas/IdentityNetworkScore"
    },
    "emailDomainCreationDate": {
      "$ref": "#/components/schemas/EmailDomainCreationDate"
    },
    "phoneEmailFirstSeenDays": {
      "$ref": "#/components/schemas/PhoneEmailFirstSeenDays"
    },
    "ipGeolocationCountryCode": {
      "$ref": "#/components/schemas/IpGeolocationCountryCode"
    },
    "ipGeolocationSubdivision": {
      "$ref": "#/components/schemas/IpGeolocationSubdivision"
    }
  },
  "description": "List of account owner Identity Insights"
}

string AccountOwnerName

{
  "type": "string",
  "example": "John Smith, PhD",
  "description": "The full name of the account owner. Multiple account owners are returned in one string per the source data from the institution."
}

object AccountOwnerPhone

{
  "type": "object",
  "properties": {
    "type": {
      "$ref": "#/components/schemas/AccountOwnerPhoneType"
    },
    "phone": {
      "$ref": "#/components/schemas/PhoneNumber"
    },
    "country": {
      "$ref": "#/components/schemas/PhoneCountry"
    }
  },
  "description": "Consumer phone"
}

string AccountOwnerPhoneType

{
  "type": "string",
  "example": "HOME",
  "description": "The account owner's phone type:   \n\n* \"HOME\"\n\n* \"BUSINESS\"\n\n* \"CELL\"\n\n* \"FAX\""
}

array AccountOwnerPhones

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AccountOwnerPhone"
  },
  "description": "List of phones"
}

string AccountOwnerRelationshipType

{
  "type": "string",
  "example": "AUTHORIZED_USER",
  "description": "The type of relationship to the account:  \n* \"AUTHORIZED_USER\"  \n\n* \"BUSINESS\"   \n\n* \"FOR_BENEFIT_OF_PRIMARY\"  \n\n* \"FOR_BENEFIT_OF_PRIMARY_JOINT_RESTRICTED\"  \n\n* \"FOR_BENEFIT_OF_SECONDARY\"\n\n* \"FOR_BENEFIT_OF_SECONDARY_JOINT_RESTRICTED\"\n\n* \"FOR_BENEFIT_OF_SOLE_OWNER_RESTRICTED\"\n\n* \"POWER_OF_ATTORNEY\"\n\n* \"PRIMARY_JOINT_TENANTS\"\n\n* \"PRIMARY\"\n\n* \"PRIMARY_BORROWER\"\n\n* \"PRIMARY_JOINT\"\n\n* \"SECONDARY\"\n\n* \"SECONDARY_JOINT_TENANTS\"\n\n* \"SECONDARY_BORROWER\"\n\n* \"SECONDARY_JOINT\"\n\n* \"SOLE_OWNER\"\n\n* \"TRUSTEE\"\n\n* \"UNIFORM_TRANSFER_TO_MINOR\""
}

string AccountStatus

{
  "type": "string",
  "example": "pending",
  "description": "An account status"
}

string AccountType

{
  "type": "string",
  "example": "checking",
  "description": "The list of supported account types.\n* \"checking\": Standard checking\n* \"savings\": Standard savings\n* \"cd\": Certificates of deposit\n* \"moneyMarket\": Money Market\n* \"creditCard\": Standard credit cards\n* \"lineOfCredit\": Home equity, line of credit\n* \"investment\": Generic investment (no details)\n* \"investmentTaxDeferred\": Generic tax-advantaged investment (no details)\n* \"employeeStockPurchasePlan\": ESPP, Employee Stock Ownership Plans (ESOP), Stock Purchase Plans\n* \"ira\": Individual Retirement Account (not Rollover or Roth)\n* \"401k\": 401K Plan\n* \"roth\": Roth IRA, Roth 401K\n* \"403b\": 403B Plan\n* \"529plan\": 529 Plan (True value is 529)\n* \"rollover\": Rollover IRA\n* \"ugma\": Uniform Gifts to Minors Act\n* \"utma\": Uniform Transfers to Minors Act\n* \"keogh\": Keogh Plan\n* \"457plan\": 457 Plan (True value is 457)\n* \"401a\": 401A Plan\n* \"brokerageAccount\": Brokerage Account\n* \"educationSavings\": Education Savings Account that is not a 529\n* \"healthSavingsAccount\": HSA (Health Savings Accounts)\n* \"pension\": Pension\n* \"profitSharingPlan\": Profit Sharing Plan\n* \"roth401k\": Roth 401K\n* \"sepIRA\": Simplified Employee Pension IRA\n* \"simpleIRA\": Simple IRA\n* \"thriftSavingsPlan\": Thrift Savings Plan\n* \"variableAnnuity\": Variable Annuity\n* \"cryptocurrency\": Cryptocurrency Wallet, Cryptocurrency Account\n* \"mortgage\": Standard Mortgages\n* \"loan\": Auto loans, equity loans, other loans\n* \"studentLoan\": Student Loan\n* \"studentLoanGroup\": Student Loan Group\n* \"studentLoanAccount\": Student Loan Account"
}

string ActiveStatus

{
  "type": "string",
  "example": "ACTIVE",
  "description": "Possible values: \"ACTIVE\", \"INACTIVE\""
}

string Address

{
  "type": "string",
  "example": "434 W Ascension Way",
  "description": "A street address"
}

string AddressLine1

{
  "type": "string",
  "example": "434 W Ascension Way",
  "description": "Address line 1"
}

string AddressLine2

{
  "type": "string",
  "example": "Suite #200",
  "description": "Address line 2"
}

string AddressLine3

{
  "type": "string",
  "example": "UT 84123",
  "description": "Address line 3"
}

string AddressToName

{
  "type": "string",
  "example": "match",
  "description": "The match status between the input name and the queried entity.\n* not-found\n* match\n* no-match"
}

string AddressType

{
  "type": "string",
  "example": "Home",
  "description": "The type of address location:\n* \"Business\"\n* \"Home\"\n* \"Mailing\""
}

number AddressValidityLevel

{
  "type": "number",
  "example": null,
  "description": "The most granular level to which the address could be validated. Ex. If the address was only valid to the city level (but not to the house level), it would return “valid_to_city”.\n  * missing_address - An input address was not provided.\n\n  * invalid - The input address is not valid.\n\n  * valid - The input address is valid.\n\n  * valid_to_country - The input address could only be validated to the\ncountry level. This means the country of the input address is valid, but the other elements of the input address were unable to be confirmed as valid or invalid.\n\n  * valid_to_city - The input address was validated to the city level.\nThis means the country, state, city, and postal code of the input address are valid, but the street, house number, and subpremise of the input address were unable to be confirmed as valid or invalid.\n\n  * valid_to_street - The input address was validated to the street\nlevel. This means the country, state, city, postal code, and street of the input address are valid, but the house number and subpremise of the input address were unable to be confirmed as valid or invalid.\n\n    * valid_to_house_number - The input address was validated to the\nstreet and house number level. This means the country, state, city, postal code, street, and house number of the input address are valid, but the subpremise of the input address was unable to be confirmed as valid or invalid. \n\n    * valid_to_house_number_missing_apt - The input address was\nvalidated to the street and house number level. This means the country, state, city, postal code, street, and house number of the input address are valid, but the subpremise of the input address was missing and thus unable to be confirmed as valid or invalid."
}

string AggregationStatus

{
  "type": "string",
  "example": "active",
  "description": "\"pending\" during account discovery, always \"active\" following\n  successful account activation"
}

integer AggregationStatusCode

{
  "type": "integer",
  "description": "The status of the most recent aggregation attempt (see [Aggregation Status Codes](https://developer.mastercard.com/open-banking-us/documentation/products/manage/account-aggregation/#aggregation-status-codes)). Won't be present until you have run your first aggregation for the account."
}

object AnalyticsReportAck

{
  "allOf": [
    {
      "$ref": "#/components/schemas/BaseReportAck"
    },
    {
      "type": "object",
      "properties": {
        "reportPin": {
          "$ref": "#/components/schemas/ReportPin"
        },
        "constraints": {
          "$ref": "#/components/schemas/AnalyticsReportConstraintsOut"
        },
        "businessDetails": {
          "$ref": "#/components/schemas/BusinessDetails"
        }
      }
    }
  ],
  "required": [
    "id",
    "customerType",
    "customerId",
    "requestId",
    "requesterName",
    "createdDate",
    "title",
    "type",
    "status",
    "constraints"
  ]
}

object AnalyticsReportConstraints

{
  "type": "object",
  "properties": {
    "fromDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "accountIds": {
      "$ref": "#/components/schemas/ReportAccountIdsString"
    },
    "reportCustomFields": {
      "$ref": "#/components/schemas/ReportCustomFields"
    },
    "analyticsReportData": {
      "$ref": "#/components/schemas/AnalyticsReportData"
    }
  }
}

object AnalyticsReportConstraintsOut

{
  "type": "object",
  "properties": {
    "fromDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "accountIds": {
      "$ref": "#/components/schemas/ReportAccountIds"
    },
    "reportCustomFields": {
      "$ref": "#/components/schemas/ReportCustomFields"
    },
    "analyticsReportData": {
      "$ref": "#/components/schemas/AnalyticsReportData"
    }
  }
}

object AnalyticsReportData

{
  "type": "object",
  "required": [
    "forCraPurpose"
  ],
  "properties": {
    "forCraPurpose": {
      "type": "boolean",
      "example": true,
      "description": "Field to indicate if the requested report is for CRA or NONCRA. For small business lending or other similar business use cases, pass the value as “true” for purposes of this field."
    },
    "timeIntervalTypes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TimeIntervalType"
      },
      "example": [
        "MONTHLY_CALENDAR"
      ],
      "maxItems": 2,
      "description": "Requested time interval for attribute values."
    },
    "applicantIsPersonalGuarantor": {
      "type": "boolean",
      "example": true,
      "description": "Field to indicate if the business owner will personally guarantee the loan. If true, a consumer record will be required."
    }
  },
  "description": "Parameters supplied by the client requesting the analytics."
}

object AnalyticsReportsAccount

{
  "type": "object",
  "required": [
    "id",
    "name",
    "number",
    "type",
    "currency",
    "transactions"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64",
      "example": 1000023996,
      "description": "The ID of the account"
    },
    "name": {
      "type": "string",
      "example": "Checking",
      "description": "The account name from the institution"
    },
    "type": {
      "type": "string",
      "example": "checking",
      "description": "One of the values from account types"
    },
    "number": {
      "type": "string",
      "example": "XX1111",
      "description": "The account number from the institution (obfuscated)"
    },
    "details": {
      "$ref": "#/components/schemas/AccountDetails"
    },
    "ownerName": {
      "$ref": "#/components/schemas/ReportAccountOwnerName"
    },
    "balanceDate": {
      "type": "integer",
      "format": "int64",
      "example": 1614880526,
      "description": "A timestamp showing when the `balance` was captured"
    },
    "ownerAddress": {
      "$ref": "#/components/schemas/ReportAccountOwnerAddress"
    },
    "transactions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ReportTransaction"
      },
      "description": "a list of transaction records"
    },
    "currentBalance": {
      "type": "number",
      "example": 100000,
      "description": "The cleared balance of the account as-of `balanceDate`"
    },
    "accountAnalytics": {
      "$ref": "#/components/schemas/AccountAnalytics"
    },
    "availableBalance": {
      "type": "number",
      "example": 1000,
      "description": "Available balance"
    },
    "aggregationStatusCode": {
      "type": "integer",
      "format": "int32",
      "example": 0,
      "description": "The status of the most recent aggregation attempt"
    }
  }
}

object AnnualIncome

{
  "type": "object",
  "required": [
    "year",
    "grossPayAmountYTD"
  ],
  "properties": {
    "year": {
      "type": "string",
      "example": 2022,
      "description": "The year for the amounts given in YTD totals for an employer"
    },
    "netPayAmountYTD": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) net pay amount for the indicated year"
    },
    "basePayAmountYTD": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) base pay amount for the year indicated"
    },
    "grossPayAmountYTD": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) gross pay amount for the indicated year"
    },
    "otherPayAmountYTD": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) other pay amount for the indicated year. Other pay is pay that is not categorized into one of the other categories."
    },
    "commissionPayAmount": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) commission pay amount for the indicated year"
    },
    "overtimePayAmountYTD": {
      "type": "number",
      "example": 123.45,
      "description": "Year to date (YTD) overtime pay amount for the year indicated"
    }
  }
}

object AppFinancialInstitutionStatus

{
  "type": "object",
  "required": [
    "id",
    "decryptionKeyActivated",
    "createdDate",
    "lastModifiedDate",
    "status"
  ],
  "properties": {
    "id": {
      "$ref": "#/components/schemas/NumericInstitutionId"
    },
    "status": {
      "type": "boolean",
      "example": true,
      "description": "\"false\" indicates registration is still pending"
    },
    "logoUrl": {
      "type": "string",
      "example": "https://prod-direct-integration-client.s3.us-west-2.amazonaws.com/976521f99-7b36-4b3b-a3e0-faff9545836d/102224/90x90.png",
      "description": "An URL to a logo file"
    },
    "abbrvName": {
      "type": "string",
      "example": "VAEJ",
      "description": "The application's abbreviated name"
    },
    "createdDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "lastModifiedDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "decryptionKeyActivated": {
      "type": "boolean",
      "example": false,
      "description": "Status of decryption keys for financial institution app registration"
    }
  },
  "description": "The registration status fields for each specific OAuth financial institution"
}

string AppRegistrationStatus

{
  "type": "string",
  "example": "P",
  "description": "The status of an app registration request. \"A\" means approved. \"P\" means pending which is the status when initially submitted or when the app is modified and awaiting approval. \"R\" means rejected. If it is rejected there will be a note with the rejected reason."
}

object AppStatus

{
  "type": "object",
  "required": [
    "partnerId",
    "preAppId",
    "appName",
    "submittedDate",
    "modifiedDate",
    "status"
  ],
  "properties": {
    "note": {
      "type": "string",
      "example": "Approved",
      "description": "A note on the registration. Typically used to indicate reasons for rejected apps."
    },
    "scopes": {
      "type": "string",
      "example": "Account Info",
      "description": "Indicates scopes of data accessible to the app"
    },
    "status": {
      "$ref": "#/components/schemas/AppRegistrationStatus"
    },
    "appName": {
      "$ref": "#/components/schemas/ApplicationName"
    },
    "preAppId": {
      "$ref": "#/components/schemas/PreAppId"
    },
    "partnerId": {
      "$ref": "#/components/schemas/PartnerId"
    },
    "modifiedDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "applicationId": {
      "$ref": "#/components/schemas/ApplicationId"
    },
    "submittedDate": {
      "$ref": "#/components/schemas/UnixDate"
    },
    "institutionDetails": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AppFinancialInstitutionStatus"
      },
      "description": "A list of the registration status for each FI for the application"
    }
  },
  "description": "Registration status details for the application"
}

object AppStatuses

{
  "type": "object",
  "required": [
    "totalRecords",
    "totalPages",
    "pageNumber",
    "numberOfRecordsPerPage",
    "applications"
  ],
  "properties": {
    "pageNumber": {
      "type": "integer",
      "format": "int64",
      "example": 2,
      "description": "The current page number"
    },
    "totalPages": {
      "type": "integer",
      "format": "int64",
      "example": 5,
      "description": "The total number of pages"
    },
    "applications": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AppStatus"
      },
      "description": "A list of applications with their statuses"
    },
    "totalRecords": {
      "type": "integer",
      "format": "int64",
      "example": 50,
      "description": "The total number of results"
    },
    "numberOfRecordsPerPage": {
      "type": "integer",
      "format": "int64",
      "example": 10,
      "description": "The number of results per page"
    }
  },
  "description": "The response for the Get App Registration Status API which returns an array of status objects"
}

Load more schemas

Versions

Version	Endpoints	Schemas	Ingested	Status
1.16.2	104	514	2026-05-11	current
1.16.2	104	514	2026-04-20
1.16.2	104	514	2026-04-16