openapi: 3.2.0
info:
  title: Open Finance Accounts (Simple) API
  description: 'OpenAPI specification for Finicity APIs.


    Open Finance (formerly Open Banking) solutions in the US are provided by

    Finicity, a Mastercard company.'
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/open-finance-us/documentation/support/
  version: 1.43.0
servers:
- url: https://api.finicity.com
  description: Production
security:
- FinicityAppKey: []
  FinicityAppToken: []
tags:
- name: Accounts (Simple)
  description: Fetch simple customer accounts
paths:
  /aggregation/v1/customers/{customerId}/institutions/{institutionId}/accounts/simple:
    get:
      tags:
      - Accounts (Simple)
      summary: Get Customer Accounts by Institution ID (Simple)
      description: 'This API is a lighter version of Get Customer Accounts by Institution ID, returning only basic information of active accounts owned by the given customer at the given institution.


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      operationId: GetCustomerAccountsByInstitutionSimple
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/InstitutionIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomerAccountsSimpleResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
  /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts/simple:
    get:
      tags:
      - Accounts (Simple)
      summary: Get Customer Accounts by Institution Login ID (Simple)
      description: 'This API is a lighter version of Get Customer Accounts by Institution Login ID, returning only basic information of all active accounts owned by the given customer at the given institution login ID.


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      operationId: GetCustomerAccountsByInstitutionLoginSimple
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/InstitutionLoginIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomerAccountsSimpleResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
  /aggregation/v1/customers/{customerId}/accounts/{accountId}/simple:
    get:
      tags:
      - Accounts (Simple)
      summary: Get Customer Account by ID (Simple)
      description: 'This API is a lighter version of Get Customer Accounts by ID, returning only basic information of a customer account.


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      operationId: GetCustomerAccountSimple
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      - $ref: '#/components/parameters/AccountIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomerAccountSimpleResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
  /aggregation/v1/customers/{customerId}/accounts/simple:
    get:
      tags:
      - Accounts (Simple)
      summary: Get Customer Accounts (Simple)
      description: 'This API is a lighter version of Get Customer Accounts, returning only basic information of all active customer accounts.


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      operationId: GetCustomerAccountsSimple
      parameters:
      - $ref: '#/components/parameters/CustomerIdParameter'
      responses:
        '200':
          $ref: '#/components/responses/GetCustomerAccountsSimpleResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/ResourceNotFoundErrorResponse'
components:
  examples:
    MissingFinicityAppKeyExample:
      value:
        code: '10026'
        message: Missing parameter (Finicity-App-Key)
    InvalidForesightReportRequestExample:
      value:
        code: '10100'
        message: At least one of customerId or externalCustomerId must be provided; both are also allowed.
    ResellerInvalidDateRangeGreaterThan31DaysExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - It is more than 31 days'
    ResellerNoReportForPartnerExample:
      value:
        code: '10100'
        message: Cannot find resellerBilling reports with id 2445581559892.
    ResellerInvalidDateRangeGreaterThanEndDateExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - startDate is greaterThan endDate'
    BothCraAndFtcPurposeTrueExample:
      value:
        code: '10100'
        status: '400'
        message: forCRAPurpose and forFTCPurpose may not both be TRUE.
    ResellerPartnerNotAuthorizedExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Partner is not authorized to access resellerBilling reports for partnerId 2445583947903'
    InvalidConsumerPhoneExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.phone.
    MissingFieldExample:
      value:
        code: '10005'
        message: Missing parameter (partnerId)
    NoRegisteredApplicationExample:
      value:
        code: '50051'
        message: No registered partner applications found.
    ExpiredFinicityAppTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    InvalidFieldExample:
      value:
        code: '10010'
        status: '400'
        message: Customer ID does not exist or does not belong to this partner
        user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data.
        tags: ''
    InvalidValueExample:
      value:
        code: '1618'
        message: Negative or invalid value entered. Please use positive numbers only.
    InvalidConsumerSSNExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.ssn.  Required format is 9 digits.
    InvalidFinicityAppTokenExample:
      value:
        code: '10022'
        message: Invalid (Finicity-App-Token)
    ResellerInvalidDateRangeLessThanZeroExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date less than or equal to zero'
    CustomerReportLimitExceedExample:
      value:
        code: '20400'
        message: The max report generation limit was exceeded for this customer.
    NoAccountForInstitutionLoginIdExample:
      value:
        code: '38007'
        message: Customer does not have any accounts associated with institutionLoginId.
    CustomerNotFoundExample:
      value:
        code: '14001'
        message: Customer not found.
    ResellerNoDataForPartnerExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Reports not found 2445583947903 resellerBilling reports'
    InvalidConsumerEmailExample:
      value:
        code: '10100'
        message: Invalid format for field consumer.email.
    ResellerInvalidDateRangeExample:
      value:
        code: '10100'
        message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date is empty or null'
    ExpiredTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    AccountTypeNotSupportedExample:
      value:
        code: '14020'
        message: Bad request. (Account type not supported).
    PermissiblePurposeCodeExample:
      value:
        code: '10100'
        status: '400'
        message: Permissible Purpose Code is required
    ResourceNotFoundExample:
      value:
        code: '14001'
        message: Resource not found.
    ConsumerNotFoundExample:
      value:
        code: '10100'
        message: Cannot find consumer with id 1234.
    InvalidExperienceFieldExample:
      value:
        code: '10010'
        status: '400'
        message: '"experience" must be a valid GUID'
        user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data.
        tags: ''
    GenericBadRequestExample:
      value:
        code: '14020'
        message: Bad request.
    BadCredentialsExample:
      value:
        code: '24302'
        message: Bad credentials
    NoConsumerForCustomerExample:
      value:
        code: '10100'
        message: Cannot find consumer for customer with id 5011115315."
    MissingFinicityAppTokenExample:
      value:
        code: '10024'
        message: Missing parameter (Finicity-App-Token)
  schemas:
    LinkedAccountDate:
      type: integer
      description: 'A timestamp showing when the customer first linked the account via Data Connect. A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/).'
      format: int64
      example: 1607450357
    Currency:
      type: string
      description: A currency code
      example: USD
    AuthorizationExpires:
      type: boolean
      description: A Boolean flag that indicates whether the customer’s authorization period has a defined authorization end date.
      example: true
      default: false
    AuthorizationEndDate:
      type: integer
      format: int64
      description: Authorization end date and time in epoch format (not used if AuthorizationExpires is false).
      example: 1641030399
    ErrorMessage:
      required:
      - code
      type: object
      properties:
        code:
          type: object
          description: 'An error code (can be returned as a number or a string). Useful links: [Common API Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/#common-api-status-codes), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes).'
          example: '10001'
        status:
          type: string
          description: A status code
          example: '401'
        title:
          type: string
          description: A title for the error
          example: Connecting accounts error
        level:
          type: string
          description: An error level
          example: error
        message:
          type: string
          description: An error message
          example: Invalid authorization credentials
        user_message:
          type: string
          description: Some more details about the error
          example: The session has expired or is invalid
        assetId:
          $ref: '#/components/schemas/AssetId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        externalTransactionId:
          type: string
          description: A unique identifier for the transaction that assists in linking data back to your systems.
          example: MAC1005061234
          minLength: 1
          maxLength: 100
        tags:
          type: string
          description: Categories that the error belongs to
          example: AGG
    AccountId:
      type: string
      description: An account ID
      example: '5011648377'
    CustomerAccountSimple:
      description: An account represents a bank account such as a checking or savings that the customer has added via the Connect interface.
      required:
      - id
      - accountNumberDisplay
      - name
      - type
      - status
      - customerId
      - institutionId
      - createdDate
      - currency
      - institutionLoginId
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AccountId'
        accountNumberDisplay:
          $ref: '#/components/schemas/AccountNumberDisplay'
        name:
          $ref: '#/components/schemas/Name'
        type:
          $ref: '#/components/schemas/AccountType'
        aggregationStatusCode:
          $ref: '#/components/schemas/AggregationStatusCode'
        status:
          $ref: '#/components/schemas/AggregationStatus'
        customerId:
          $ref: '#/components/schemas/CustomerId'
        institutionId:
          $ref: '#/components/schemas/InstitutionId'
        aggregationSuccessDate:
          $ref: '#/components/schemas/UnixDate'
        aggregationAttemptDate:
          $ref: '#/components/schemas/UnixDate'
        createdDate:
          $ref: '#/components/schemas/UnixDate'
        currency:
          $ref: '#/components/schemas/Currency'
        institutionLoginId:
          $ref: '#/components/schemas/NumericInstitutionLoginId'
        authorizationStartDate:
          $ref: '#/components/schemas/AuthorizationStartDate'
        authorizationEndDate:
          $ref: '#/components/schemas/AuthorizationEndDate'
        authorizationExpires:
          $ref: '#/components/schemas/AuthorizationExpires'
        displayPosition:
          $ref: '#/components/schemas/DisplayPosition'
        parentAccount:
          $ref: '#/components/schemas/AccountId'
        linkedAccountDate:
          $ref: '#/components/schemas/LinkedAccountDate'
    NumericInstitutionId:
      description: The ID of a financial institution, represented as a number
      type: integer
      format: int64
      example: 4222
    NumericInstitutionLoginId:
      type: integer
      format: int64
      description: An institution login ID (from the account record), represented as a number
      example: 1007302745
    CustomerAccountsSimple:
      description: A list of accounts with basic information of a customer
      required:
      - accounts
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAccountSimple'
          description: A list of accounts with basic information of a customer
    InstitutionId:
      description: The ID of a financial institution
      type: string
      example: '4222'
    AggregationStatus:
      type: string
      description: "\"pending\" during account discovery, always \"active\" following\n  successful account activation"
      example: active
    Name:
      type: string
      description: The account name from the institution
      example: Super Checking
    AssetId:
      type: string
      description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API.
      example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178
    AggregationStatusCode:
      type: integer
      description: The status of the most recent aggregation attempt (see [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes)). Won't be present until you have run your first aggregation for the account.
    CustomerId:
      type: string
      description: A customer ID. See Add Customer API for how to create a customer ID.
      example: '1005061234'
    UnixDate:
      type: integer
      description: 'A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/).'
      format: int64
      example: 1607450357
    AuthorizationStartDate:
      type: integer
      format: int64
      description: Authorization start date and time in epoch format.
      example: 1541030399
    InstitutionLoginId:
      type: string
      description: An institution login ID (from the account record)
      example: '1007302745'
    DisplayPosition:
      type: integer
      description: "Display position of the account at the financial institution, \"1\"\n    being the top listed account"
      format: int32
      example: 2
    AccountType:
      type: string
      description: 'The list of supported account types.

        * "checking": Standard checking

        * "savings": Standard savings

        * "cd": Certificates of deposit

        * "moneyMarket": Money Market

        * "creditCard": Standard credit cards

        * "lineOfCredit": Home equity, line of credit

        * "investment": Generic investment (no details)

        * "investmentTaxDeferred": Generic tax-advantaged investment (no details)

        * "employeeStockPurchasePlan": ESPP, Employee Stock Ownership Plans (ESOP), Stock Purchase Plans

        * "ira": Individual Retirement Account (not Rollover or Roth)

        * "401k": 401K Plan

        * "roth": Roth IRA, Roth 401K

        * "403b": 403B Plan

        * "529plan": 529 Plan (True value is 529)

        * "rollover": Rollover IRA

        * "ugma": Uniform Gifts to Minors Act

        * "utma": Uniform Transfers to Minors Act

        * "keogh": Keogh Plan

        * "457plan": 457 Plan (True value is 457)

        * "401a": 401A Plan

        * "brokerageAccount": Brokerage Account

        * "educationSavings": Education Savings Account that is not a 529

        * "healthSavingsAccount": HSA (Health Savings Accounts)

        * "pension": Pension

        * "profitSharingPlan": Profit Sharing Plan

        * "roth401k": Roth 401K

        * "sepIRA": Simplified Employee Pension IRA

        * "simpleIRA": Simple IRA

        * "thriftSavingsPlan": Thrift Savings Plan

        * "variableAnnuity": Variable Annuity

        * "cryptocurrency": Cryptocurrency Wallet, Cryptocurrency Account

        * "mortgage": Standard Mortgages

        * "loan": Auto loans, equity loans, other loans

        * "studentLoan": Student Loan

        * "studentLoanGroup": Student Loan Group

        * "studentLoanAccount": Student Loan Account'
      example: checking
    AccountNumberDisplay:
      type: string
      description: 'Account identifier derived by Mastercard from the account number provided by the financial institution. The format varies depending on the institution. We recommend using this to identify accounts if available.

        Below is a non-exhaustive list of examples for the `accountNumberDisplay` field.

        * 5720

        * 3539-259

        * 1500-1

        * 0824-S0050'
      example: '7528'
  parameters:
    CustomerIdParameter:
      description: A customer ID
      name: customerId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/CustomerId'
      example: '1005061234'
    InstitutionIdParameter:
      description: The institution ID
      name: institutionId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/NumericInstitutionId'
      example: 4222
    InstitutionLoginIdParameter:
      description: The institution login ID
      name: institutionLoginId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/InstitutionLoginId'
      example: '1007302745'
    AccountIdParameter:
      description: The account ID
      name: accountId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/AccountId'
      example: '5011648377'
  responses:
    BadRequestErrorResponse:
      description: The request was rejected
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            PermissiblePurposeCodeExample:
              $ref: '#/components/examples/PermissiblePurposeCodeExample'
            InvalidForesightReportRequestExample:
              $ref: '#/components/examples/InvalidForesightReportRequestExample'
            BothCraAndFtcPurposeTrueExample:
              $ref: '#/components/examples/BothCraAndFtcPurposeTrueExample'
            MissingFieldExample:
              $ref: '#/components/examples/MissingFieldExample'
            InvalidFieldExample:
              $ref: '#/components/examples/InvalidFieldExample'
            InvalidExperienceFieldExample:
              $ref: '#/components/examples/InvalidExperienceFieldExample'
            GenericBadRequestExample:
              $ref: '#/components/examples/GenericBadRequestExample'
            AccountTypeNotSupportedExample:
              $ref: '#/components/examples/AccountTypeNotSupportedExample'
            ResellerPartnerNotAuthorizedExample:
              $ref: '#/components/examples/ResellerPartnerNotAuthorizedExample'
            ResellerInvalidDateRangeExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeExample'
            ResellerInvalidDateRangeLessThanZeroExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeLessThanZeroExample'
            ResellerInvalidDateRangeGreaterThanEndDateExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThanEndDateExample'
            ResellerInvalidDateRangeGreaterThan31DaysExample:
              $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThan31DaysExample'
            CustomerReportLimitExceedExample:
              $ref: '#/components/examples/CustomerReportLimitExceedExample'
            InvalidConsumerSSNExample:
              $ref: '#/components/examples/InvalidConsumerSSNExample'
            InvalidConsumerPhoneExample:
              $ref: '#/components/examples/InvalidConsumerPhoneExample'
            InvalidConsumerEmailExample:
              $ref: '#/components/examples/InvalidConsumerEmailExample'
            InvalidValue:
              $ref: '#/components/examples/InvalidValueExample'
    GetCustomerAccountsSimpleResponse:
      description: The account list was successfully retrieved
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerAccountsSimple'
    GetCustomerAccountSimpleResponse:
      description: The account was successfully retrieved
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerAccountSimple'
    ResourceNotFoundErrorResponse:
      description: The resource doesn't exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ConsumerNotFoundExample:
              $ref: '#/components/examples/ConsumerNotFoundExample'
            NoAccountForInstitutionLoginIdExample:
              $ref: '#/components/examples/NoAccountForInstitutionLoginIdExample'
            CustomerNotFoundExample:
              $ref: '#/components/examples/CustomerNotFoundExample'
            NoConsumerForCustomerExample:
              $ref: '#/components/examples/NoConsumerForCustomerExample'
            ResourceNotFoundExample:
              $ref: '#/components/examples/ResourceNotFoundExample'
            NoRegisteredApplicationExample:
              $ref: '#/components/examples/NoRegisteredApplicationExample'
            ResellerNoDataForPartnerExample:
              $ref: '#/components/examples/ResellerNoDataForPartnerExample'
            ResellerNoReportForPartnerExample:
              $ref: '#/components/examples/ResellerNoReportForPartnerExample'
    UnauthorizedErrorResponse:
      description: The request lacks valid authentication credentials. Check "Finicity-App-Key" or "Finicity-App-Token".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ExpiredTokenExample:
              $ref: '#/components/examples/ExpiredTokenExample'
            MissingFinicityAppKeyExample:
              $ref: '#/components/examples/MissingFinicityAppKeyExample'
            MissingFinicityAppTokenExample:
              $ref: '#/components/examples/MissingFinicityAppTokenExample'
            InvalidFinicityAppTokenExample:
              $ref: '#/components/examples/InvalidFinicityAppTokenExample'
            ExpiredFinicityAppTokenExample:
              $ref: '#/components/examples/ExpiredFinicityAppTokenExample'
            BadCredentialsExample:
              $ref: '#/components/examples/BadCredentialsExample'
        text/plain:
          schema:
            type: string
            example: Invalid (Finicity-App-Key)
  securitySchemes:
    FinicityAppKey:
      name: Finicity-App-Key
      type: apiKey
      in: header
      description: The "Finicity-App-Key" from the developer dashboard
    FinicityAppToken:
      name: Finicity-App-Token
      type: apiKey
      in: header
      description: A token returned by the `/authentication` API