Item

As we've introduced before, an Item is the representation of a connection with a specific Connector of an Institution, and serves as the entry point to access the set of products recovered from the user that gave his consent to collect his/her data.

Creating an Item: Institution authentication flow

To create an Item, the easiest, most polished, battle-tested, and least error-prone way for a user, is interacting with our Pluggy Connect Widget, where they can provide consent, follow through the Institution authentication steps, and quickly have their products available in our API.

Otherwise, you can develop an application that implements the Item creation flow yourself, although this can be a daunting, complex task, and difficult to get right; so it's not the preferred choice we recommend.

When an Item is created and the institution sync finishes successfully, we'll retrieve all the latest financial products data, for up to the last 365 days.

Updating an Item

The process to update an Item is quite similar to the creation one. The recommended way to do it, is also using our Pluggy Connect widget, as explained here. It can also be done via API: Update an Item (also review: Item Send MFA).

When an Item update is successful, we retrieve all the products data since the last time we did a data collection, and merge it with the previously collected data.

Also, data for up to 4 days before the last successful update date will be collected and merged too, to make up for any possible changes or additions that could have occurred in the institution data and not lose track of them.

Accessing Item collected data

To access the data of the Item collected products, you'll have to interact with our API using the related endpoints. To help reduce development times, we provide several Server side SDKs (if none suits you please let's us know! We'll be happy to help.)

Products

When Pluggy creates an Item, it automatically collects all the products requested as a step-by-step execution, pulling the information from the FI and storing it on our DB.

When recovering an item you will find the list of products enabled for this item, and you can specify this value as well on creation.

Auto-sync

Once created, an Item will have a reference to the stored user parameters and credentials needed to execute the data collection from the institution.
Note that all credentials are encrypted, and can never be retrieved from the API.

This enables Pluggy to run our auto-sync process, which implies once every 24/12/8 hours (based on your subscription), we'll be collecting the transaction data of the last few days, and automatically adding it on top of the existing collected data.

This way, you'll always have up-to-date access to the product data of the connected Institution, and you won't require to set up any batch process to update your connections, just listen to webhook notifications of new updates.

When there is an error in an auto-sync update, two things can happen:

• If it was a LOGIN_ERROR (for example, when the credentials are invalid), the update will not be retried and the Item will no longer be updated by auto-sync. Auto-syncing will only resume when the client connects the Item successfully again.
• If it was a different error, we retry the update every 1 hour up to 5 attempts, after that, the Item is also dropped from auto-sync.

The nextAutoSyncAt in the GET /items/{id} endpoint indicates when is the next auto-sync update for the Item, or null if it does not have auto-sync. Remember that this is the minimum date at which the next auto-sync update will run: it can be slightly delayed depending on the load of the institution's connector at the time.

📘

Premium Feature

The auto-sync feature is only available for Production applications. It can be configured to run every 24, 12, or 8 hours based on your subscription.

If you require to maintain the connections in sync, the only way would be using our Auto-Sync, batch update process will be mitigated and should never be created.

Webhook Notifications

It's possible to listen to Webhook Notifications to recover all events related to a created Item. For this, you'll only need to provide a valid URL in the webhookUrl parameter, either when creating a Connect Token, or in the Item creation request itself.

You can find more information in the Webhook section.