Skip to main content

Fetch Data

To retrieve data for an end user in the Universal Connect Widget, you'll need to establish a connection using the following workflow:

  1. Configure the widget URL with job type and user id information.
  2. Load the widget for the end user to search for an institution, select that institution, and provide their credentials.
  3. Listen for the memberConnected postMessage.
  4. Fetch account data.

Assumptions

The following guides assume that you've already:

  • Installed, configured, and deployed your self-hosted Universal Connect Widget, and have access to the URL for your self-hosted UCW instance.
  • Although optional, we encourage you to add security to restrict usage of your hosted UCW outside of your application.
  • The user has already been created on your platform

Steps to retrieve data

1. Configure the Widget​

To setup the widget to accept data, you'll need to insert the widget URL into an embedded iframe.

The widget iframe must include the following required parameters in the URL:

  • job_type: This is the job used to gather data. Options include aggregation, all, fullhistory, verification, identity.
  • user_id: The unique identifier of the user to make or refresh a connection with. Other configurations are optional.

Job types​

  • aggregate: Aggregated accounts and recent transaction data.
  • fullhistory: A set timeframe of transaction history for an account.
  • verification: Account numbers and routing/transit number information.
  • identity: Available customer data.
  • all: Includes aggregate, verification, and identity data. Does not include a full history of transactions.
tip

The job_type parameters required for specific data are defined by the type of data requested (listed below). job_type also filters search to only include institutions that support that job.

For more information on other parameters, view our OAS specification.

Example Usage <iframe src="www.ucw-widget.com/widget?job_type=identity&user_id=test-user-id" />

Authentication​

If you have enabled authentication in your environment configuration, the widget will require authorization.

Use the token endpoint to retrieve a one-time-use token to pass into the widget URL in the iframe. The server will set an authorization cookie that the widget will pass to the server for all requests.

For more information, see the /api/token endpoint in our OAS specification.

2. Load the Widget in Your Application​

Load the URL in your application or website. Then, the end user will interact with the widget. The widget handles the creation of a member with the selected aggregator. At this point the UCW facilitates the connection of that member with the aggregator and completes the job defined in the widget URL.

3. Listen for postMessage​

When a member has successfully been connected and the job is completed, the UCW will trigger a memberConnected postMessage. When your application identifies this postMessage, the widget is done and data is available for retrieval.

An example of this event:

{
  "type": "vcs/connect/memberConnected",
  "metadata": {
    "aggregator": "sophtron",
    "member_guid": "MBR-345"
  }
}

4. Get Data​

Requests may be made with the following methods:

  1. UCW data endpoints. Requests may use our optional bearer tokens for authentication. Responses are in JSON format.

  2. 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.

  3. Using the member information retrieved in the widget, you may have the option to request data directly from the aggregator.

All Data and Verifiable Credential (VC) endpoints require the parameters user_id, aggregator, job_type, and connection_id (where applicable) as documented below.

Account data​

Make a GET request to the /accounts endpoint using job_type=aggregate, job_type=verification, or job_type=all. Only data that is aggregated for the defined job is returned. If the widget URL isn't configured for your account data may be limited.

This request requires a connection_id, aggregator, and user_id.

info

The connection_id 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/{user_id}/connection/{connection_id}/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 account_id to fetch transaction data.

Both the job_type and user_id are required. When you plan on requesting account data, set the job_type to aggregate or fullhistory (fullhistory provides extended transaction history beyond recent transaction history and typically within a set timeframe), or all.

Fetch Transaction Data​

Make a GET request to the /transactions endpoint. This endpoint returns a JWT object. Only data that is aggregated for the defined job is assigned to the VC. In this case, if you don't configure the widget URL for the job_type=aggregate, job_type=all, or job_type=fullhistory, your transaction data may be limited.

Additionally, if you plan to ask for transaction data further in the past than what the aggregator considers to be basic aggregation, you'll need to use fullhistory.

This request requires the account_id, aggregator, and user_id parameters.

warning

If the aggregator is Sophtron, both start_time and end_time are required. Both of these parameters may only be used with Sophtron as the aggregator and no others. Used together the parameters indicate the period of time in which transactions returned occurred.

Example Request

curl -i -X GET 'www.your-widget-url.com/api/data/aggregator/{aggregator}/user/{user_id}/account/{account_id}/transactions&start_time=2024-01-01&end_time=2022-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.

When you plan on requesting identity data, set the job_type to identity or all.

Fetch Identity Data​

Make a GET request to the /identity endpoint. Only data that is aggregated for the defined job is returned. If you don't configure the widget URL for the job_type=identity or job_type=all, your identity data may be limited.

This request requires a connection_id, aggregator, and user_id.

note

The connection_id 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/{user_id}/connection/{connection_id}/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"
  }