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 who 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 to interact 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.

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.

📘

Avoid reinventing the wheel, use our SDKs!

We strongly recommend that if there is an existing SDK for your language, that you use it, since its fully supported by our development team and error proof.

If you end up creating your own integration, we won't be providing support for that specific implementation.

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.

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.

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 be required 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 specific 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.

📘

Multiple webhooks

If you create multiple webhooks for an item using the webhookUrl and the client-level Webhook configuration, you will receive multiple notifications.

Avoiding duplicates

To avoid a user from connecting more than once his account at Pluggy, we provide a configuration while creating your connection, that will validate if the credentials already exist before going through the authentication process.

Using this configuration, the user will reveive an error from the API specifying that there is already an Item created for those credentials.

You can set it up in two ways:

• If you are using Pluggy Connect you can create the token with the item options for avoidDuplicates in true, and all items generated with that connectToken will be validated.
• If you are connected directly through API, you can create the item with the same option in the payload.