Items

When recovering items a list of products is returned depending on the connector's category. Currently, we are supporting full banking data, so a list of accounts, credit cards, identity, and investments are provided.

{
  "accounts": [{}],
  "investments": [{}],
  "identity": {}
}

Items

An Item represents the link between a User and an Institution that will be using our Connectors to access their data and sync that item daily. It could be a bank account, a fintech app user, or any other supported connector.

An Item contains a set of parameters or credentials that are needed to execute the synchronization with the institution. These credentials are encrypted and can never be retrieved from the API.

An item can configure its webhooks notifications to recover all events related to that specific item, providing a valid URL in the webhookUrl parameter. For more information review the Webhook section.

Item Status

To understand the current status of an item we must review his status field for a first overview of the health of the connection.

Value

Description

Meaning

UPDATING

The connection is syncing with the provider.

An update process is in progress and will be updated soon.

LOGIN_ERROR

The connection is syncing with the provider.

The connection must be updated to execute again, it won't trigger updates until the parameters are updated.

OUTDATED

The sync process finished with errors.

The parameters were correctly validated but there was an error in the last execution. It can be retried.

WAITING_USER_INPUT

The sync process needs user's input to continue.

The connection requires user's input to continue the sync process, this is common for MFA authentication connectors.

UPDATED

The sync process finished successfully.

The last sync process has completed successfully and all new data is available to collect.

As mentioned above when we trigger an update the connection will be indicating UPDATING as its status. This is an in-progress status and will mean that you will have to recheck in a couple of seconds.

If the credentials sent were invalid, you will encounter a LOGIN_ERROR status and will be required to update it.

In case there was an error you will encounter the OUTDATED status, and you will have to review the executionStatus for further details.

And the most common scenario you will see the UPDATED status, which means that the connection was successfully synced with the institution.

Execution Status

As we mentioned the sync process has a status that indicates the step or states the execution is at. Some of the statuses mark the progress or step it's in, and others mark the status or state the execution ended.

Value

Description

SUCCESS

The execution was completed successfully.

ERROR

There was an unexpected error in the connection.

INVALID_CREDENTIALS

The connection couldn't access the institution due to invalid input.

ALREADY_LOGGED_IN

The connection couldn't be established right now because there is an active session.

SITE_NOT_AVAILABLE

The connector didn't get a response from the institution you are trying to connect.

CREATED

The connection was successfully initiated.

WAITING_USER_INPUT

The connection needs the user's input to continue the execution.

Item parameters validations

Validations in Pluggy API are very important, there are used to avoid executing connectors with invalid parameters and to create item connections that won't be sync due to invalid credentials or parameters. When creating or updating an item, validations will be executed for that item based on the connector's Credentials.

Error codes could be:

  • 001: Missing parameter
  • 002: Not valid parameter, based on length or type validations.

This is an example of a validation response when creating an item:

{
  "message": "Connector parameters do not match validation rules",
  "errors": [
    {
      "code": "002",
      "message": "user parameter length must be at least 6.",
      "parameter": "user"
    },
    {
      "code": "002",
      "message": "password parameter length must be at least 6.",
      "parameter": "password"
    }
  ]
}

📘

See Items in our API reference for more information.