The upSWOT API is a tool that allows you to access the latest account and transaction information from your SMB customers' banks. There are multiple ways that you can receive this data, including:

Banking Aggregators integration. Example: Mastercard (Finicity) and Yodlee.
Integration with Core Banking Systems. Example: Alkami, Q2, Banno.
Direct integrations with selected banks. Example: Capital One, Sunwest.

Regardless of how the data is connected to the upSWOT system, you can be assured that all banking-related data will be presented in a structured and normalized form.

Banking Aggregators

Banking aggregators are third-party providers of open banking services that support many institutions across Canada and the USA.

This method of accessing banking data is particularly useful when you are unsure which banks use the SMB.

📘
Supported Finansial Intitutions
You will automatically gain access to any new financial institutions that each aggregator adds to their platform. Note: some specific FIs will need to request manualy

How to get banking data from Banking Aggregators

The process requires taking these simple steps:

Get aggregator parent serviceId.
Generate service connection link using aggregator parent serviceId.
Track connection status using API and Webhooks events.
Call banking Normalized API to access all the latest account and transaction information.

Step 1. Get serviceId

For this example, we want to get all SMBs' bank accounts of the company using the Finicity aggregator service.

Use the GET All services endpoint to get all services.

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/services \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc...'

The response will return the list of all available services. In the response, search for service with "name": "Finicity"and "parentId": null.

{
    "pageNumber": 1,
    "pageSize": 100,
    "count": 90,
    "data": [
				{
            "id": "fe7fec89-51ce-11ec-bd4e-0242ac120007",
            "isEnabled": true,
            "logoUrl": "https://app.upswot.com/admin/api/DataService/GetImage?dbSource=SysService&id=fe7fec89-51ce-11ec-bd4e-0242ac120007",
            "name": "Finicity",
            "title": "Other Banks",
            "parentId": null,
            "parentName": null,
            "description": "{\"en-US\": \"Finicity helps individuals and organizations make smarter financial decisions through safe access to high-quality data.\"}",
            "categoryId": "22afb716-4814-4fad-a685-a43fa2694266",
            "category": "Banking",
            "supportedEntities": [
                "Transactions",
                "Accounts"
            ]
        },
      ...
      ]
 }

Step 2. Generate connection link

To create the service connection link, by calling the Service connection link endpoint, use your companyId and Banking Aggregator serviceId to generate the link. Your API call must include the access token we have just generated using the Authorization header as follows:

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/{companyId}/accountancy/accounts/fe7fec89-51ce-11ec-bd4e-0242ac120007 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc...'

API will return the following JSON response. Share this link with the end user, who will connect the banking accounts.

{
    "link": "https://app.upswot.com/admin/api/Data/Auth?serviceId=fe7fec89-51ce-11ec-bd4e-0242ac120007&instanceId=08d9b3f3-0c1f-431d-87df-182030fabc41&accountId=ed30fe06-fd84-42d9-9437-825e37aeee69"
}

The user will see the connection flow based on the selected banking aggregator by opening the link. Here is an example of end-user flow for connecting banking accounts using Finicity:

Note: The user flow could differ based on the developer account configuration.

Step 3. Track connection status

How do we understand when the data is ready to be used?

To understand what is the status of each connection related to the company, we propose two main options:

Call GET List connections, check for a new connection with "categoryId"="22afb716-4814-4fad-a685-a43fa2694266" and wait for "statusCode"= 15 or 18 or 19, status (learn more about data connection statuses) to start obtaining Normalized Banking Data.

Endpoint response example:

{
    "pageNumber": 1,
    "pageSize": 100,
    "count": 1,
    "data": [

        {
            "sessionId": "ac10feb6-8c30-4f0a-8401-0394ec5fa4f7",
            "statusName": "Synced",
            "statusCode": 19,
            "serviceName": "FinBankFinicity",
            "serviceId": "08db04f5-5400-4f5e-8636-829bd265bbdd",
            "categoryId": "c157853d-a6a6-45e4-be65-78ec7f05e16d",
            "category": "Banking",
            "createdOn": "2024-04-02T05:51:02.142151",
            "updateScheduledOn": "2024-04-05T05:53:02"
        }
    ]
}

Subscribe to the "NormalizedData" event to get a notification that the data is ready (Learn more about webhooks functionality).

Webhook payload example:

{
  "Class": "DataConnection",
  "MessageType": "NormalizedData",
  "Identifier": "NormalizedData.c341f6ba-1877-4f62-a25a-4f0e43208c06",
  "Data": {
    "SessionShareId": "ac10feb6-8c30-4f0a-8401-0394ec5fa4f7",
    "CompanyId": "c157853d-a6a6-45e4-be65-78ec7f05e16d",
    "AccountExternalId": null,
    "ApplicationId": null,
    "ServiceId": "08db04f5-5400-4f5e-8636-829bd265bbdd",
    "ServiceName": "FinBankFinicity",
    "CategoryName": "Banking",
    "CategoryId": "22afb716-4814-4fad-a685-a43fa2694266",
    "Email": "example@upswot.com",
    "IssuedAs": "Manual",
    "ModifiedOn": "2024-04-02T20:11:23.547998"
  },
  "Signature": "f64c5c221e8a7de4c093b0de51a512f0c529dc1d6a76214e23a7621de0c9c5be"
}

Note:

New child service will be created based in case that is the first time the bank was connected on the tenant.

To identify that the service is child, check the GET All services endpoint responce for "parentName" is not null.

Save "serviceId" value for the next step.

Step 4. Get your banking data

We can get all normalized data when the end user connects the bank accounts. Let's use GET Bank accounts by service to get all banking accounts from the connected aggregator.

Use companyId and bank serviceId obtained on the previous step in the URI:

curl --request GET \
     --url https://app.upswot.com/admin/api/v1/normalized-data/c157853d-a6a6-45e4-be65-78ec7f05e16d/banking/accounts/08db04f5-5400-4f5e-8636-829bd265bbdd \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbGc...'

If performed correctly, the API will return the following JSON response:

{
  "serviceId": "08db04f5-5400-4f5e-8636-829bd265bbdd",
  "serviceName": "FinBankFinicity",
  "lastUpdatedOn": "2024-04-02T20:11:23.547998",
  "data": [
    {
      "serviceId": "08db04f5-5400-4f5e-8636-829bd265bbdd",
      "serviceName": "FinBankFinicity",
      "lastUpdatedOn": "2024-04-02T20:11:23.547998",
      "origId": "7012345678",
      "providerName": "FinBank",
      "accountName": "Auto Loan",
      "accountNumber": "xxxxxx8888",
      "accountStatusSystem": "ACTIVE",
      "userAccountClassification": "Small business account",
      "typeSystem": "Loans",
      "subTypeSystem": "OtherLoan",
      "subTypeSystemDisplayName": "Other Loan",
      "interestRate": 1.55,
      "availableCredit": 0,
      "dueDate": "2024-03-25T12:00:00+00:00",
      "maturityAmount": 88.11,
      "maturityDate": null,
      "minimumAmountDue": 250,
      "totalCreditLine": 0,
      "originalLoanAmount": 0,
      "lender": "lender",
      "amountDue": 232,
      "principalBalance": 1099.22,
      "currency": "USD",
      "actualBalance": 309.77,
      "actualBalanceDate": "2024-03-07T08:59:18+00:00",
      "sourceUpdatedDate": "2024-03-07T08:59:18+00:00"
    }
  ],
  "pagination": {
    "pageNumber": 1,
    "pageSize": 100,
    "count": 100
  }
}

🎉Congratulations! You received the list of connected banking accounts using upSWOT API.

Banking Accounts for Sandbox

In the sandbox environment, only test banks are available for connection. Here is the list of test credentials to play with.

Aggregator Name	ServiceId	Bank Name	ClientId	Client Secret
Finicity	`fe7fec89-51ce-11ec-bd4e-0242ac120007`	Finbank	`profile_02`	`profile_02`
Yodlee	`de61da52-7b67-11eb-90e4-0242ac120006`	IQ Bank	`bank_463032`	`bank@iqb`

Note:

Only Mastercard(Finicity) and Yodlee are enabled in the sandbox environment.

The permanent data update is off in the sandbox environment. You could check whether the next update is planned by calling GET List connections statuses and checking "updateScheduledOn": null.