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 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 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. By default will collect all the products enabled on your team's subscription.

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.

To customize which products you want to collect for a specific item you can send the products parameter (using the product type in uppercase) when creatingAPI the item (if you integrate through api) or the widget's configuration using the products property.

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 ItemAPI (also review: Item Send MFAAPI).

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: on a schedule agreed with you, we'll collect the transaction data of the last few days and automatically add 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.

Choosing a schedule#

Auto-sync can follow one of two schedules. Both are configured by Pluggy on your application — reach out to your account manager to set one up or change it.

• Every N hours. Syncs run at a fixed interval, counted from the end of the previous sync. Available intervals are 6, 8, 12, 24, 30, 48 and 96 hours. Optionally, we can anchor the daily cycle to a starting hour, so the first sync of each day lands close to a time you choose. Because each sync is counted from when the previous one finished, the exact time of day drifts. If you need syncs to land at predictable times, use the option below.
• At specific times of day. Syncs run at up to 4 fixed times a day — for example 09:00, 11:00, 13:00 and 18:00. This is the better fit when your product depends on data being fresh at particular moments — for example, reconciling during business hours, or checking for incoming transfers before a daily cut-off. Within each window, individual syncs are spread across the hour rather than all firing at the exact minute. On an account with many connections, expect them to complete progressively through the window rather than all at once.

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}API 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.

Meu Pluggy connections are a separate case#

Meu Pluggy is a standalone service for end users connecting their own accounts, and it has its own rules. Connections made inside Meu Pluggy are refreshed automatically every 24 hours, for free -- that cadence belongs to the service itself and does not depend on any application's subscription.

This matters when your application connects through the MeuPluggy connector, because there are then two distinct Items:

So both of these statements are true at the same time, and they are not in conflict: "Meu Pluggy connections are updated daily" (the original Item) and "MeuPluggy proxy Items are not auto-synced" (the proxy Item). They are different objects.

For any other connector, the Item in your application follows the auto-sync rules described above.

Reading nextAutoSyncAt

nextAutoSyncAt is only returned when the application has auto-sync enabled. A null there means "this application has no auto-sync configured", not "the connection is broken".

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 TokenAPI, or in the Item creation requestAPI 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 receive 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 tokenAPI 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 itemAPI with the same option in the payload.

When creating an item that already exists will recover a 400 HTTP error.

{
  "code": 400,
  "codeDescription": "ITEM_USER_ALREADY_EXISTS",
  "message": "There are other items with the same credentials, you can't create a new one",
  "data": {
    "items": [
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d93",
      "d0f8a8c0-e8e3-11e9-b210-d663bd873d94"
    ]
  }
}

The data.items array holds the ids of the existing items that already use those credentials, so you can point your user at the connection they already have instead of asking them to try again. Note the ids are nested under data — they are not returned at the root of the response body.

These connectors support the Avoid duplicates feature:

• Pluggy direct connectors: all
• Open Finance connectors:
  • Nubank

Referencing your user#

When you create an Item you can use the clientUserId as an external identifier from your systems. This will help you identify an item with your user.

You can setup this up in two ways:

• Using our Pluggy Connect widget, you can create a connectToken with the value for clientUserId. All items created with that connect token will have that value.
• When creating Items through our API, the payload has an clientUserId parameter to receive this reference.

Searching and listing items#

You can retrieve the connections that belong to your account with GET /v2/itemsAPI, most recently created first. Results can be narrowed with clientUserId — the external identifier you assigned when creating the Item — or with connectorId, to list only the connections to a given institution.

This endpoint is opt-in and disabled by default. Listing lets an API key enumerate every connection you hold, which is a wider level of access than retrieving a known Item by its id, so it is enabled per agreement: contact support if you want it for your team. Until then the endpoint responds 403 with LIST_ITEMS_FEATURE_NOT_ENABLED.

Responses are cursor-paginated. Instead of a page number, each response carries a next value pointing at the following page: append it as-is to the endpoint path, and stop once it comes back null. Any filters you sent are already part of next, so there is no need to repeat them.

let next = ''
const items = []
 
do {
  const response = await fetch(`https://api.pluggy.ai/v2/items${next}`, {
    headers: { 'X-API-KEY': apiKey },
  })
  const page = await response.json()
 
  items.push(...page.results)
  next = page.next
} while (next !== null)

The after parameter takes only the cursor value. Sending the whole next string as after is rejected with INVALID_CURSOR.

Listing is a convenience, not a replacement for your own bookkeeping: we still recommend tracking your connections in your datasource by their itemId, and keeping those references in sync.