Version: 2.0.0

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	✔	✔	✔
Plaid	✔	✔	✘
Sophtron	✔	✔	✔

Supported functionality by aggregator

Account Data

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

aggregator (query parameter) — The aggregator to use
UCW-Connection-Id (HTTP header) — The connectionId you retrieved from the postMessage metadata
userId (query parameter) — Must be the same as the userId configured in the widget. Note: For userless aggregators (currently plaid and plaid_sandbox), this parameter is optional.

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/accounts?aggregator=mx&userId=user123' \
-H 'UCW-Connection-Id: conn456' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Example Request (Userless Aggregator - Plaid)

curl -i -X GET 'https://your-widget-url.com/api/data/accounts?aggregator=plaid' \
-H 'UCW-Connection-Id: access-sandbox-111111-22222-33333-44444-555555' \
-H 'Accept: application/json' \
-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:

You must have already fetched and decoded account data. You'll need the accountId to fetch transaction data.
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
Make a GET request to the /api/data/transactions endpoint, setting these required fields:
- aggregator (query parameter) — The aggregator to use
- accountId (query parameter) — The account ID from which to fetch transactions
- userId (query parameter) — Must be the same as the userId configured in the widget
- UCW-Connection-Id (HTTP header) — The connection ID

startDate and endDate are optional query 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 'https://your-widget-url.com/api/data/transactions?aggregator=mx&userId=user123&accountId=acc789&startDate=2025-01-01&endDate=2025-12-31' \
-H 'UCW-Connection-Id: conn456' \
-H 'Accept: application/json' \
-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:

The widget must've been configured for jobTypes=accountOwner when the connection was created.
Make a GET request to the /api/data/identity endpoint, setting these required fields:
- aggregator (query parameter) — The aggregator to use
- UCW-Connection-Id (HTTP header) — The connectionId you retrieved from the postMessage metadata
- userId (query parameter) — Must be the same as the userId configured in the widget. Note: For userless aggregators (currently plaid and plaid_sandbox), this parameter is optional.

Example Request

curl -i -X GET 'https://your-widget-url.com/api/data/identity?aggregator=mx&userId=user123' \
-H 'UCW-Connection-Id: conn456' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' 

Example Identity Data

{
  "customers": [
    {
      "addresses": [
        {
          "line1": "3401 N Thanksgiving Way #500",
          "city": "Lehi",
          "state": "Utah",
          "postalCode": "84034"
        }
      ],
      "customerId": "ACO-7815105a-2bea-4e23-a847-60b418b31950",
      "name": {
        "first": "MX",
        "last": "Test"
      },
      "email": [
        "mxuser@mx.com"
      ],
      "telephones": [
        {
          "number": "555-555-5555"
        }
      ],
      "accounts": [
        {
          "accountId": "act-23445745"
        }
      ],
      "id": "USR-2565451b-0053-4423-8505-b1e3a649a956"
    }
  ]
}

UCW Data Endpoint Availability​

Account Data​

Transaction Data​

Identity Data​

UCW Data Endpoint Availability

Account Data

Transaction Data

Identity Data