Item lifecycle

Item Status

To understand the current status of an item, we must review its status field. This will give a first glance about the connection's health.

 
As mentioned above, when we trigger an update, the connection status will be set to UPDATING. This is an in-progress status which means you will need to check it again 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 while also providing new credentials.

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

Finally, the most common scenario, is the UPDATED status, which means that the connection was successfully synced with the institution.

 

Execution Status step by step

Each item is created or updated through an execution, which, like the item, goes through different states as it is executed.

Each Item status is associated to a set of possible executionStatus values, according to the following diagram.

These combinations of statuses give specific information not only about the steps that are being executed while the Item is updating, but also about the final result of the execution. Thus, for example, if the item status is OUTDATED, we can check the related executionStatus value to know the specific cause of it not having finished successfully.

You can review the detailed Item's current execution status through this field, executionStatus.

This value indicates the current step the execution is at, which can be a transitive (in-progress) state, or a final state.

Transitive states

The following states represent that the Item execution is still running, so it's likely it will continue to change by itself.

 

Final states

These states represent an Execution that has finished running.

We can distinguish two possible types of final states:

• A finished state, either with a success, or error result.
• An intermediate state, which means more input from the User is needed. In this case, a new Execution needs to be started by fulfilling the required actions.

 

Success states

 

Error state

 

Intermediate states

📘

See Items in our API reference for more information.

 

 

Synchronization flow

During the process of creating or updating an Item, it will go through different states until the data collection is finished.

When the process starts, the status will be set to UPDATING and from there, there are a few possible state values that we'll detail below, based on the Connector-specific login flow.

There are 3 Connector-specific login flow possibilities: when the connector doesn't require an MFA parameter, when the connector requires an MFA that is accessible by the user beforehand (ie. using Google Authenticator), or when the connector requires an MFA that is generated/requested to the user right after the initial login step has been completed.

1- Connectors without MFA parameter

This is the simplest case.
The login flow will proceed with just the user credentials.

A- If user credentials have been correct, then the connection will proceed and it will attempt to retrieve products data. Then:
1- if everything went well, the final Item status will be UPDATED, and the related executionStatus will be SUCCESS.
2- if something went wrong but at least some of the products data could be retrieved, the Item status will also be UPDATED, and the related executionStatus will be PARTIAL_SUCCESS. Further information about what has failed will be available in the Item executionReport field.
3- if something went fatally wrong with the connection, such as an unexpected error, and no data could be retrieved, the Item status will be OUTDATED and the related executionStatus will be ERROR.

📘

In the above cases, all items are considered updatable, since the initial credentials have been correct.
By default, updatable Items are automatically synced by us, once per day.

 
B- If user credentials have not been correct, then the Item status will be LOGIN_ERROR.

🚧

In this case the Item is not considered updatable. The user will have to manually trigger an update, and start over by providing a new set of credentials.

 

 

2- Connectors with 1-step verification step

This case of Connector can be identified by finding in one of the connector data credentials field values, a credential that has the mfa field set as true.

The same flow as in the previous step will occur.

🚧

Here Items are not updatable, since an extra input provided by the user is required for each connection execution.

Exceptions
There are a few exceptions, like Nuinvest, which allows us to continue syncing with the institution (with no more MFA requests), once the initial device authorization has been granted.

 
In cases in which MFA parameter is sent repeated between executions, API will return a bad request with the specific message without execute the connector.

3- Connectors with a 2-step verification step

This case of Connector can be identified by checking the base connector data mfa field, set as true.

So, after providing the initial user credentials, if they have been correct, then the Item will jump to a different state: WAITING_USER_INPUT.

In this state, the connection will be suspended, until the user submits the validation code. Once the user sends the new parameter, if the parameter submitted was correct, the execution will resume as in the previous scenarios until the item finishes the execution in one of the three possible final states UPDATED, OUTDATED or LOGIN_ERROR.

🚧

This case of Items are not updatable, since an extra input provided by the user is required for each connection execution.

The only exception is Nubank, which can be updated after an initial device authorization.

 

Summary

The following state diagram summarizes the Item connection flow.