Yodlee PHP API Client Documentation

Everything you need to know about using the Tectalic Yodlee PHP API Client.

Introduction

The Tectalic Yodlee Core REST API Client is a package that provides a convenient and straightforward way to interact with the Yodlee Core API from your PHP application.

You can purchase this package from https://tectalic.com/apis/yodlee-core.

Installation

System Requirements

  • PHP version 7.2.5 or newer (including PHP 8.0 and 8.1)
  • PHP JSON extension installed if using PHP 7.x. As of PHP 8.0, this extension became a core PHP extension so is always enabled.
  • A PSR-18 compatible HTTP client such as ‘Guzzle’ or the ‘Symfony HTTP Client’.

Composer Installation

To install this package into your PHP project, we recommend using Composer.

Please see the detailed instructions on configuring your project to access the Tectalic Composer repository.

You will need to log into the Tectalic account that purchased the Tectalic Yodlee Core REST API Client package to access these instructions.

Once you have followed the above instructions, install the package into your project:

composer require tectalic/yodlee-core

Manual Installation

If you aren’t using Composer in your PHP project, you can choose to Download the latest release and install it into your PHP project manually.

If doing this, you will need to ensure that all dependencies listed in the package’s composer.json file are also installed.

Usage

After installing the Tectalic Yodlee Core REST API Client package into your project, ensure you also have a compatible PSR-18 HTTP client such as ‘Guzzle’ or the Symfony ‘HTTP Client’.

You can use the following code sample and customize it to suit your application.

// Load your project's composer autoloader (if you aren't already doing so).
require_once(__DIR__ . '/vendor/autoload.php');
use Symfony\Component\HttpClient\Psr18Client;
use Tectalic\YodleeCore\Client;
use Tectalic\YodleeCore\Manager;
 
// Build a Tectalic Yodlee Core REST API Client globally.
$httpClient = new Psr18Client();
Manager::build($httpClient);
 
// or
 
// Build a Tectalic Yodlee Core REST API Client manually.
$httpClient = new Psr18Client();
$client = new Client($httpClient, Manager::BASE_URI);

Client Class

The primary class you will interact with is the Client class (Tectalic\YodleeCore\Client).

This Client class also contains the helper methods that let you quickly access the 40 API Handlers.

Please see below for a complete list of supported handlers and methods.

Supported API Handlers and Methods

This package supports 70 API Methods, which are grouped into 40 API Handlers.

See the table below for a full list of API Handlers and Methods.

API Handler Class and Method Name Description API Verb and URL
Accounts::list() Get Accounts GET /accounts
Accounts::createManual() Add Manual Account POST /accounts
Accounts::get() Get Account Details GET /accounts/{accountId}
Accounts::update() Update Account PUT /accounts/{accountId}
Accounts::delete() Delete Account DELETE /accounts/{accountId}
AccountsEvaluateAddress::evaluateAddress() Evaluate Address POST /accounts/evaluateAddress
AccountsHistoricalBalances::get() Get Historical Balances GET /accounts/historicalBalances
AuthApiKey::list() Get API Keys GET /auth/apiKey
AuthApiKey::generate() Generate API Key POST /auth/apiKey
AuthApiKey::delete() Delete API Key DELETE /auth/apiKey/{key}
AuthToken::generateAccess() Generate Access Token POST /auth/token
AuthToken::delete() Delete Token DELETE /auth/token
CobrandConfigNotificationsEvents::list() Get Subscribed Events GET /cobrand/config/notifications/events
CobrandConfigNotificationsEvents::updateSubscribed() Update Subscription PUT /cobrand/config/notifications/events/{eventName}
CobrandConfigNotificationsEvents::createSubscription() Subscribe Event POST /cobrand/config/notifications/events/{eventName}
CobrandConfigNotificationsEvents::deleteSubscribed() Delete Subscription DELETE /cobrand/config/notifications/events/{eventName}
CobrandLogin::cobrandLogin() Cobrand Login POST /cobrand/login
CobrandLogout::cobrandLogout() Cobrand Logout POST /cobrand/logout
CobrandPublicKey::get() Get Public Key GET /cobrand/publicKey
ConfigsNotificationsEvents::list() Get Subscribed Notification Events GET /configs/notifications/events
ConfigsNotificationsEvents::updateSubscribedNotification() Update Notification Subscription PUT /configs/notifications/events/{eventName}
ConfigsNotificationsEvents::createSubscriptionNotification() Subscribe For Notification Event POST /configs/notifications/events/{eventName}
ConfigsNotificationsEvents::deleteSubscribedNotification() Delete Notification Subscription DELETE /configs/notifications/events/{eventName}
ConfigsPublicKey::getPublicEncryptionKey() Get Public Key GET /configs/publicKey
DataExtractsEvents::list() Get Events GET /dataExtracts/events
DataExtractsUserData::list() Get userData GET /dataExtracts/userData
DerivedHoldingSummary::get() Get Holding Summary GET /derived/holdingSummary
DerivedNetworth::get() Get Networth Summary GET /derived/networth
DerivedTransactionSummary::get() Get Transaction Summary GET /derived/transactionSummary
Documents::list() Get Documents GET /documents
Documents::download() Download a Document GET /documents/{documentId}
Documents::delete() Delete Document DELETE /documents/{documentId}
Holdings::list() Get Holdings GET /holdings
HoldingsAssetClassificationList::get() Get Asset Classification List GET /holdings/assetClassificationList
HoldingsHoldingTypeList::get() Get Holding Type List GET /holdings/holdingTypeList
HoldingsSecurities::list() Get Security Details GET /holdings/securities
ProviderAccounts::list() Get Provider Accounts GET /providerAccounts
ProviderAccounts::editCredentialsOrRefresh() Update Account PUT /providerAccounts
ProviderAccounts::get() Get Provider Account Details GET /providerAccounts/{providerAccountId}
ProviderAccounts::delete() Delete Provider Account DELETE /providerAccounts/{providerAccountId}
ProviderAccountsPreferences::update() Update Preferences PUT /providerAccounts/{providerAccountId}/preferences
ProviderAccountsProfile::getProviderAccount() Get User Profile Details GET /providerAccounts/profile
Providers::list() Get Providers GET /providers
Providers::get() Get Provider Details GET /providers/{providerId}
ProvidersCount::get() Get Providers Count GET /providers/count
Statements::list() Get Statements GET /statements
Transactions::list() Get Transactions GET /transactions
Transactions::update() Update Transaction PUT /transactions/{transactionId}
TransactionsCategories::list() Get Transaction Category List GET /transactions/categories
TransactionsCategories::updateTransactionCategory() Update Category PUT /transactions/categories
TransactionsCategories::createTransactionCategory() Create Category POST /transactions/categories
TransactionsCategories::deleteTransactionCategory() Delete Category DELETE /transactions/categories/{categoryId}
TransactionsCategoriesRules::getTransactionCategorizationRulesDeprecated() Get Transaction Categorization Rules GET /transactions/categories/rules
TransactionsCategoriesRules::createOrRunTransactionCategorization() Create or Run Transaction Categorization Rule POST /transactions/categories/rules
TransactionsCategoriesRules::updateTransactionCategorization() Update Transaction Categorization Rule PUT /transactions/categories/rules/{ruleId}
TransactionsCategoriesRules::runTransactionCategorization() Run Transaction Categorization Rule POST /transactions/categories/rules/{ruleId}
TransactionsCategoriesRules::deleteTransactionCategorization() Delete Transaction Categorization Rule DELETE /transactions/categories/rules/{ruleId}
TransactionsCategoriesTxnRules::getTransactionCategorizationRules() Get Transaction Categorization Rules GET /transactions/categories/txnRules
TransactionsCount::get() Get Transactions Count GET /transactions/count
User::get() Get User Details GET /user
User::update() Update User Details PUT /user
UserAccessTokens::list() Get Access Tokens GET /user/accessTokens
UserLogout::userLogout() User Logout POST /user/logout
UserRegister::registerUser() Register User POST /user/register
UserSamlLogin::samlLogin() Saml Login POST /user/samlLogin
UserUnregister::unregister() Delete User DELETE /user/unregister
Verification::list() Get Verification Status GET /verification
Verification::verifyChallengeDeposit() Verify Challenge Deposit PUT /verification
Verification::initiateMatchingOrChallengeDeposite() Initiaite Matching Service and Challenge Deposit POST /verification
VerifyAccount::initiateAccountVerification() Verify Accounts Using Transactions POST /verifyAccount/{providerAccountId}

Making a Request

There are two ways to make a request to the nominated API Handler and API Method:

If you built the client to be accessible globally, you can use the relevant API Handler Class directly:

use Tectalic\YodleeCore\Handlers\Accounts;
 
(new Accounts())->list();

Alternatively, you can access all API Handlers from the client class using the Client class:

$client->accounts()->list();

Retrieving the Response

Once you have made a request using one of the two methods outlined above, the next step is to access the response.

You can access the response in different ways. Please choose your preferred one.

Model Responses

Model responses are Data Transfer Object (DTO) style PHP classes, with public properties for each API property.

They offer a structured way of retrieving the response from an API request.

All Response Models are an instance of Tectalic\YodleeCore\Models\AbstractModel' or Tectalic\YodleeCore\Models\AbstractModelCollection.

After performing the request, use the ->toModel() fluent method to the API Method:

use Tectalic\YodleeCore\Handlers\Accounts;
 
$model = (new Accounts())->list()->toModel();

Each API Method’s toModel() call will return the appropriate Model class type for the API Method you have just called.

Associative Array Responses

After performing the request, use the ->toArray() fluent method to the API Method:

use Tectalic\YodleeCore\Handlers\Accounts;
 
$array = (new Accounts())->list()->toArray();

In the resulting associative array, the array keys will match the names of the public properties in the relevant Model class.

PSR 7 Response Objects

If you need to access the raw response or inspect the HTTP headers, use the ->getResponse() fluent method to the API Method. It will return a Psr\Http\Message\ResponseInterface:

use Tectalic\YodleeCore\Handlers\Accounts;
 
$response = (new Accounts())->list()->getResponse();

Errors

When performing requests with Tectalic Yodlee Core REST API Client, specific scenarios will cause a Tectalic\YodleeCore\Exception\ClientException to be thrown. Please see below for details.

Invalid Usage of the Manager Class

A \LogicException will be thrown if the Manager::build() function is called multiple times, or if Manager::access() is called before calling Manager::build().

Unsuccessful HTTP Response Codes

The Tectalic Yodlee Core REST API Client depends on a PSR-18 compatible HTTP client, and that HTTP client should not throw an exception for unsuccessful HTTP response codes.

An unsuccessful response code is classified as one that is not in the range 200-299 (inclusive). Examples of unsuccessful response codes include:

  • Informational responses (100-199)
  • Redirection responses (300-399)
  • Client error responses (400-499)
  • Server error responses (500-599)

If an unsuccessful response code does occur:

  • your HTTP Client will not throw an Exception.
  • the API Handler’s toModel() method will throw a ClientException.
  • the API Handler’s toArray() method will return the response body and not throw a ClientException.
  • The API Handler’s getResponse() method will return the raw response and not throw a ClientException.

Below is an example of how you may wish to use a try/catch block when performing a request so that you can detect and handle unexpected errors.

use Tectalic\YodleeCore\Client;
use Tectalic\YodleeCore\ClientException;
use Tectalic\YodleeCore\Manager;
 
// Build a Tectalic Yodlee Core REST API Client globally.
 
Manager::build($httpClient, $auth);
$handler = new Accounts();
 
// Perform a request
try {
$model = $handler->list()->toModel();
// Do something with the response model...
} catch (ClientException $e) {
// Error response received. Retrieve the HTTP response code and response body.
$responseBody = $handler->toArray();
$rawResponse = $handler->getResponse()->getResponse();
$responseCode = $handler->getResponse()->getStatusCode();
// Handle the error...
}

HTTP Client Exceptions

If your HTTP client of choice throws an exception other than ClientException, the Tectalic Yodlee Core REST API Client Client and its API Handler classes will let these exceptions bubble up.

Consult your HTTP client’s documentation for more details on exception handling.

Tests

The Tectalic Yodlee Core REST API Client package includes several types of automated PHPUnit tests to verify the correct operation:

  • Unit Tests
  • Integration Tests

To run these tests, you will need to have installed the Tectalic Yodlee Core REST API Client package with its dev dependencies (i.e. not using the --no-dev flag when running composer).

Unit Tests

These PHPUnit tests are designed to:

  • confirm that each API Method assembles a valid request that matches the Yodlee Core API OpenAPI specification.
  • verify the behaviour of other parts of the package, such as the Client and Manager classes.

The unit tests can be run using the following command, which needs to be run from this package’s root directory.

composer test:unit

Unit tests do not perform any real requests against the Yodlee Core API.

Unit tests are located in the tests/Unit directory.

Integration Tests

Integration tests are located in the tests/Integration directory.

These PHPUnit tests are designed to confirm that each API Method parses a valid response, according to the Yodlee Core API OpenAPI specification. Out of the box the integration tests are designed to work with the Prism Mock Server.

Using Prism as the Target

Make sure Prism is installed. Please see the Prism documentation for details on how to install Prism.

Once Prism is installed, you can run prism and the integration tests side by side in separate terminal windows, or using the following command, which need to be run from this package’s root directory.

echo "> Starting Prism server"
prism mock tests/openapi.json >/dev/null 2>&1 &
PRISM_PID=$!
sleep 2
echo " => Started"
composer test:integration
kill $PRISM_PID

Those commands will start the Prism mock server, then run the integration tests, and then stop the Prism mock server when the tests are completed.

In this case the integration tests do not perform any real requests against the Yodlee Core API.

Using a Different Target

By setting the YODLEE_CORE_CLIENT_TEST_BASE_URI environment variable, you can set a different API endpoint target for the integration tests.

For example, instead of using Prism, you can use a different mocking/staging/test server of your choice, or you can use the Yodlee Core API’s live endpoints.

After your setup is complete simply run the following command.

composer test:integration

We do not recommend running integration tests against the live Yodlee Core API endpoints. This is because the tests will send example data to all endpoints, which can result in new data being created, or existing data being deleted.

Support

If you have any questions or feedback, you can submit a support request to the Tectalic developers by going to https://tectalic.com/support/yodlee-core.

License

This software is copyright (c) Tectalic.

For the full copyright and license information, please view the ‘LICENSE’ file distributed with the source code.

Last updated 27 Oct 2022

Tectalic Yodlee PHP API Client