Fetch Data

You can fetch data with the following methods:

• UCW data endpoints. Requests may use our optional bearer tokens for authentication. Responses are in JSON format.
• Verifiable Crendential (VC) endpoints. Requests may use our optional bearer tokens for authentication. Responses are encoded in a JSON Web Token (JWT) and use signed data. Only some aggregators support VCs. For more information on using VCs and decoding the results, please reference our Verifiable Credential Data guide.
• Using the member information retrieved in the widget, you may have the option to request data directly from the aggregator.

warning

The userId required in data calls must be the same as the userId configured in the widget.

Data and Verifiable Credential (VC) endpoints require the parameters userId, aggregator, and connectionId (where applicable) as documented below.

Data Availability

Not all aggregators are available for fetching data

Reference the aggregator table to determine availability.

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

Supported functionality by aggregator

Account Data

Make a GET request to the /accounts endpoint. Only data that is aggregated for the defined job is returned. If the job types requested in the widget don't retrieve accounts data, then data may be limited.

This request requires a connectionId, aggregator, and userId.

info

The connectionId is the member_guid you retrieved from the postMessage metadata.

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

The following steps explain how to define jobs and fetch transaction data.

warning

To use the transaction data endpoint, you must have already fetched and decoded account data. You'll need the accountId to fetch transaction data.

Be sure your widget was configured for jobTypes:

• transactions for basic, recent history
• transactionHistory for a set of transactions that cover a longer timeframe.

Fetch Transaction Data

Make a GET request to the /transactions endpoint. Only data that is aggregated for the defined job is returned.

This request requires the accountId, aggregator, and userId parameters.

startDate and endDate are optional parameters. If they are used they 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

The following steps explain how to define jobs and fetch identity data.

Be sure your widget is configured for jobTypes=accountOwner.

Fetch Identity Data

Make a GET request to the /identity endpoint. Only data that is aggregated for the defined job is returned.

This request requires a connectionId, aggregator, and userId.

note

The connectionId is the member_guid you retrieved from the postMessage metadata.

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"
  }