UCW Data Endpoints

Objectives

• Detect when a connection between a user and their financial institution is established
• Retrieve account, transaction, or identity data from that connection

You can fetch data using the UCW data endpoints for a streamlined experience. The JSON responses have consistent formating, unlike the responses you would get from calling each aggregtor's API separately.

Prerequisite

These endpoints are disabled by default. See Enable UCW Data Endpoints.

UCW Data Endpoint Availability

We have optional standardized data endpoints that return a standardized data format for most aggregators.

Supported aggregators are in the table below.

For aggregators that don't support the standardized API, you can call their API directly.

Aggregator	Connection	Data Endpoints	VC Endpoints
Akoya	✔	✘	✘
Finicity	✔	✔	✘
MX	✔	✔	✔
Sophtron	✔	✔	✔

Supported functionality by aggregator

Account Data

Make a GET request to the /accounts endpoint, setting these required fields:

• aggregator
• connectionId (the member_guid you retrieved from the postMessage metadata)
• userId (must be the same as the userId configured in the widget)

Only data for the jobs defined in the widget URL is returned.

Example Request

curl -i -X GET 'https://your-widget-url.com/api/data/aggregator/{aggregator}/user/{userId}/connection/{connectionId}/accounts' \
-H 'Accept: your header here' \
-H 'Content-Type: application/json' \

Example Account Data

{
      "accounts": [
        {
          "locAccount": {
            "accountId": "ACT-848-57d0-4a24-a0c1-e72ad24a0126096bd",
            "accountType": "CREDITCARD",
            "accountNumber": "324453974",
            "accountNumberDisplay": "****5344",
            "productName": null,
            "nickname": null,
            "status": "OPEN",
            "accountOpenDate": "2022-07-11T15:40:40Z",
            "accountClosedDate": null,
            "currency": {
              "currencyRate": null,
              "currencyCode": null,
              "originalCurrencyCode": null
            },
            "fiAttributes": [
              {
                "name": "member_guid",
                "value": "MBR-f1a3285d-63d9-498f-8772-8ae775c0e0e9"
              },
              {
                "name": "institution_guid",
                "value": "INS-f7e87eff-e855-b68f-68a7-e5192784ccb6"
              },
              {
                "name": "external_guid",
                "value": "account-cc5145bf-06c0-46a1-b800-3ef3241621a9"
              }
            ],
            "routingTransitNumber": null,
            "balanceType": "LIABILITY",
            "interestRate": null,
            "lastActivityDate": "2022-07-11T15:40:40Z",
            "balanceAsOf": "2022-07-11T15:40:40Z",
            "creditLine": null,
            "availableCredit": 13000,
            "nextPaymentDate": null,
            "principalBalance": null,
            "currentBalance": 1000,
            "minimumPaymentAmount": null,
            "purchasesApr": null
          }
        },
        {
          "depositAccount": {
            "accountId": "ACT-96f3fdas3-1e05-4a4b-9fd5-571f32fdad95c",
            "accountType": "CHECKING",
            "accountNumber": "898735161",
            "accountNumberDisplay": "****5161",
            "productName": null,
            "nickname": null,
            "status": "OPEN",
            "accountOpenDate": "2022-07-11T15:40:40Z",
            "accountClosedDate": null,
            "currency": {
              "currencyRate": null,
              "currencyCode": null,
              "originalCurrencyCode": null
            },
            "fiAttributes": [
              {
                "name": "member_guid",
                "value": "MBR-cc5dsa5f-63d9-498f-8772-e4ey9841ccb6"
              },
              {
                "name": "institution_guid",
                "value": "INS-f1r5685d-e855-p98f-6aa7-8eu8470e0e9"
              },
              {
                "name": "external_guid",
                "value": "account-c6e98564-8860-0000-9d85-650dsd8fjusfe"              }
            ],
            "routingTransitNumber": null,
            "balanceType": "ASSET",
            "interestRate": null,
            "lastActivityDate": "2022-07-11T15:40:40Z",
            "balanceAsOf": "2022-07-11T15:40:40Z",
            "currentBalance": 1000,
            "openingDayBalance": null,
            "availableBalance": 1000,
            "annualPercentageYield": null,
            "maturityDate": null
          }
        },
      ]
}

Transaction Data

To retrieve transaction data:

1. You must have already fetched and decoded account data. You'll need the accountId to fetch transaction data.
2. The widget's jobTypes must've been configured as follows when the connection was created.
   • transactions for basic, recent history
   • transactionHistory for a set of transactions that cover a longer timeframe
3. Make a GET request to the /transactions endpoint, setting these required fields:
   • aggregator
   • accountId
   • userId (must be the same as the userId configured in the widget)

startDate and endDate are optional parameters that must be in ISO 8601 format (YYYY-MM-DD). If they are not used then the default startDate is 120 days ago and the default end date is 5 days in the future.

Example Request

curl -i -X GET 'www.your-widget-url.com/api/data/aggregator/{aggregator}/user/{userId}/account/{accountId}/transactions&startDate=2021-01-01&endDate=2025-01-01' \
-H 'Accept: your header here' \
-H 'Content-Type: application/json' \

Example Transaction Data

{
    "transactions": [
      {
        "depositeTransaction": {
          "accountId": "882d7648-d467-43ca-a240-13b08e8b4caf",
          "amount": 0,
          "category": "Bank fee",
          "description": "Sophtron Fee",
          "fiAttributes": {
            "accountID": "882d7648-d467-43ca-a240-13b08e8b4caf",
            "customerID": "1d93d99e-e2f4-4dd0-b0d4-3bddd267b4c3"
          },
          "postedTimestamp": "2023-08-12T00:00:00",
          "transactionId": "a353d7fd-a642-4ad8-95c0-fdf02d40f126",
          "transactionTimestamp": "2023-08-12T00:00:00",
          "transactionType": "Debit"
        }
      },
      {
        "depositeTransaction": {
          "accountId": "882d7648-d467-43ca-a240-13b08e8b4caf",
          "amount": 10,
          "category": "Income",
          "description": "Customer Deposit",
          "fiAttributes": {
            "accountID": "882d7648-d467-43ca-a240-13b08e8b4caf",
            "customerID": "1d93d99e-e2f4-4dd0-b0d4-3bddd267b4c3"
          },
          "postedTimestamp": "2023-08-11T00:00:00",
          "transactionId": "3fcb4b61-ef54-4410-afcf-2762fb518e20",
          "transactionTimestamp": "2023-08-11T00:00:00",
          "transactionType": "Credit"
        }
      }
    ]
  }

Identity Data

To retrieve identity data:

1. The widget must've been configured for jobTypes=accountOwner when the connection was created.
2. Make a GET request to the /identity endpoint, setting these required fields:
   • aggregator
   • connectionId (the member_guid you retrieved from the postMessage metadata)
   • userId (must be the same as the userId configured in the widget)

Example Request

curl -i -X GET 'www.your-widget-url.com/api/data/aggregator/{aggregator}/user/{userId}/connection/{connectionId}/identity' \
-u '{client_id}:{api_key}' \
-H 'Accept: your header here' \
-H 'Content-Type: application/json' \

Example Identity Data

{
  
    "customer": {
      "accounts": [
        {
          "accountId": "882d7648-d467-43ca-a240-13b08e8b4caf",
          "relationship": "owner"
        },
        {
          "accountId": "a82c4910-b3c3-4b5d-a0c3-1c7eaaa81ce9",
          "relationship": "owner"
        },
        {
          "accountId": "5085a4bf-0879-4efa-9b4d-6c792be40aef",
          "relationship": "owner"
        },
        {
          "accountId": "23f4c684-60b8-4c8f-a368-a814cf30c8ca",
          "relationship": "owner"
        },
        {
          "accountId": "80e5c437-ba51-4020-8972-aef1ed0ea173",
          "relationship": "owner"
        }
      ],
      "addresses": [],
      "customerId": "5807965e-091a-4f01-ae2a-0fea158ff931",
      "fiAttributes": {
        "customerID": "1d93d99e-e2f4-4dd0-b0d4-3bddd267b4c3"
      },
      "name": {},
      "phone": []
    },
    "id": "did:example:request"
  }