NAV
cURL JavaScript C# Net

Introduction

Welcome to Pluggy!

In this page you will find easy and intuitive documentation to speed up your integration process with us.
You can use our API to access Pluggy endpoints, which can connect, manage and delete connections or items.
To understand how Pluggy API works, it's important to familiarize with some concepts.

Concepts

Before you start working with our API there are some important concepts that we will let you know as a Glosary:

To use this entities you will interact with our API using the endpoints or our SDK, this terms will be reference in both scenarios:

Security Protocols

Pluggy's API enforces the use of HTTPS TLSv1.2 or upper versions for security reasons. Other TLS version request will be rejected. All communication require to be in HTTPS.

API verbs and Protocols

Pluggy's API is a RESTful API based on JSON requests and responses, so all requests must have set the header Content-Type of application/json.
We follow the RESTful standards and all verbs match their specific action for the resource you will be communicating.

Environment

Our production environment is accepting requests in the following host:

https://api.pluggy.ai

Sandbox

Using our production service you can access to Live and Sandbox connections.
For testign porpouses you can review your implementation using Pluggy Bank connector that will provide you with everyday updated transactions and all the available flows for you to test.

You can use the following credentials when required:

User - user-ok Correct user name. - user-bad Incorrect user name. - user-mfa user that requires a second step of authentication.

Password - password-ok Correct user name. - password-bad Incorrect password.

Token / SMS - 123456 Correct MFA parameter.

Run in Postman

You can access our Postman Collection with the following button to test all our endpoints.

Run in Postman

Client Libraries / SDKs

Currently we have client libraries available for the following languages:

Let us know if you want (or are interested in contributing) a library for a language not represented here!

To install the client library, use the following command:

# We don't need any client library for the shell
npm install --save pluggy-sdk
nuget install Pluggy

Changelog

Currently we have client libraries available for the following languages:

Let us know if you want (or are interested in contributing) a library for a language not represented here!

To install the client library, use the following command:

# We don't need any client library for the shell
npm install --save pluggy-sdk
nuget install Pluggy

Authentication

Create an API key

curl --location --request POST "https://api.pluggy.ai/auth" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "nonExpiring": false
  }'

HTTP Request

POST https://api.pluggy.ai/auth

Body Parameters

Parameter Description
clientId The provided CLIENT_ID
clientSecret The corresponding CLIENT_SECRET that matches with the CLIENT_ID
nonExpiring Flag indicating that token is non-expiring (default false, with a 2-hour expiration)

To authenticate, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.pluggy.ai/your_resource_here" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

// By just creating the client all the request are authenticated
var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});
// By just creating the client all the request are authenticated
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

Make sure to replace YOUR_PLUGGY_API_KEY with your API key or for SDKs YOUR_CLIENT_ID & YOUR_CLIENT_SECRET with your credentials.

Connectors

A connector represents a worker that retrieves information from an institution. This institution could represent an entity from any industry such as Bank or any fintech application like MercadoPago or Nubank.
By default, we provide real connectors for supported institutions, for testing you can recover sandbox connectors providing the sandbox=true in the request.

Search Connectors

curl "https://api.pluggy.ai/connectors" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.fetchConnectors().then(({ results: connectors }) => {
  console.log(connectors);
});
PluggyClient pluggyClient = new PluggyClient('YOUR_PLUGGY_API_KEY');
List<Connector> connectors = await pluggyClient.FetchConnectors();

The above command returns a JSON structured like this:

{
  "results": [
   {
      "id": 201,
      "name": "Itaú",
      "primaryColor": "EC7000",
      "institutionUrl": "https://www.itau.com.br",
      "country": "BR",
      "type": "PERSONAL_BANK",
      "credentials": [
        {
          "label": "Agência",
          "name": "agency",
          "type": "number",
          "placeholder": "Agência",
          "validation": "^\\d{4}$",
          "validationMessage": "O agencia deve ter 4 dígito"
        },
        {
          "label": "Conta",
          "name": "account",
          "type": "number",
          "placeholder": "Conta",
          "validation": "^\\d{4,6}$",
          "validationMessage": "O conta deve ter 6 dígito"
        },
        {
          "label": "Senha",
          "name": "password",
          "type": "number",
          "placeholder": "Senha",
          "validation": "^\\d{6}$",
          "validationMessage": "O senha deve ter 6 dígito"
        }
      ],
      "imageUrl": "https://res.cloudinary.com/dkr0vihmp/image/upload/v1588853552/connectors-logos/itau_ntodvn.png",
      "hasMFA": false
    }
  ]
}

This endpoint retrieves all available connectors.

HTTP Request

GET https://api.pluggy.ai/connectors

URL Parameters

Parameter Description
Name Name alike look up of the connector
Types A list of types of connectors to filter. Details in the Connectors Type
Countries A list of countries of connectors to fitler.
Sandbox Include sandbox connectors if set to true (default: false).

Get a Specific Connector

curl "https://api.pluggy.ai/connectors/100"
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.fetchConnector(100).then((connector) => {
  console.log(connector);
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Connector connector = await pluggyClient.FetchConnector(100);

The above command returns JSON structured like this:

{
  "id": 201,
  "name": "Itaú",
  "primaryColor": "EC7000",
  "institutionUrl": "https://www.itau.com.br",
  "country": "BR",
  "type": "PERSONAL_BANK",
  "credentials": [
    {
      "label": "Agência",
      "name": "agency",
      "type": "number",
      "placeholder": "Agência",
      "validation": "^\\d{4}$",
      "validationMessage": "O agencia deve ter 4 dígito"
    },
    {
      "label": "Conta",
      "name": "account",
      "type": "number",
      "placeholder": "Conta",
      "validation": "^\\d{4,6}$",
      "validationMessage": "O conta deve ter 6 dígito"
    },
    {
      "label": "Senha",
      "name": "password",
      "type": "number",
      "placeholder": "Senha",
      "validation": "^\\d{6}$",
      "validationMessage": "O senha deve ter 6 dígito"
    }
  ],
  "imageUrl": "https://res.cloudinary.com/dkr0vihmp/image/upload/v1588853552/connectors-logos/itau_ntodvn.png",
  "hasMFA": false
}

This endpoint retrieves a specific connector.

HTTP Request

GET https://api.pluggy.ai/connectors/<ID>

URL Parameters

Parameter Description
ID The ID of the connector to retrieve

Items

An Item represents the link between a User and a 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 syncronization with the institution. This 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 sync process encounter invalid credentials. 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.
UPDATED The sync process finished succesfully. The last sync process has completed succesfully and all new data is available to collect.

As mentioned above when we trigger an update the connection will be indicating UPDATING as it's 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, this means that the connection was successfully synced with the institution.

Execution Status

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

Value Description
SUCCESS The execution was completed succesfully.
ERROR There was an unexpected error in the connection.
INVALID_CREDENTIALS The connection couldn't access the institution due to an 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 got a response from the institution you are trying to connect.
CREATED The connection was successfully initiated.
WAITING_USER_INPUT The connection needs user's input to continue the execution.

Create an Item

curl --location --request POST "https://api.pluggy.ai/items" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>" \
  -d '{
    "connectorId": 100,
    "parameters": {
        "user": "myuser",
        "password": "mypassword"
    },
    "webhookUrl": "https://www.myapi.com/notifications"
}'
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .createItem({
    parameters: {
      user: "myuser",
      password: "mypassword",
    },
    connectorId: 100,
    webhookUrl: "https://www.myapi.com/notifications",
  })
  .then((item) => {
    console.log(item);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

ItemRequest parameters = new List<ItemParameters>()
{
  new ExecuteParameter("user", "user-ok"),
  new ExecuteParameter("password", "password-ok"),
};

ItemRequestOptions options = new ItemRequestOptions()
{
  WebhookUrl = "https://www.myapi.com/notifications"
};
Item item = await pluggyClient.CreateItem(100, parameters, options);

The above command returns JSON structured like this:

{
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "connector": {
    "id": 201,
    "name": "Itaú",
    "primaryColor": "EC7000",
    "institutionUrl": "https://www.itau.com.br",
    "country": "BR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "label": "Agência",
        "name": "agency",
        "type": "number",
        "placeholder": "Agência",
        "validation": "^\\d{4}$",
        "validationMessage": "O agencia deve ter 4 dígito"
      },
      {
        "label": "Conta",
        "name": "account",
        "type": "number",
        "placeholder": "Conta",
        "validation": "^\\d{4,6}$",
        "validationMessage": "O conta deve ter 6 dígito"
      },
      {
        "label": "Senha",
        "name": "password",
        "type": "number",
        "placeholder": "Senha",
        "validation": "^\\d{6}$",
        "validationMessage": "O senha deve ter 6 dígito"
      }
    ],
    "imageUrl": "https://res.cloudinary.com/dkr0vihmp/image/upload/v1588853552/connectors-logos/itau_ntodvn.png",
    "hasMFA": false
  },
  "status": "UPDATING",
  "executionStatus": "CREATED",
  "createdAt": "2020-06-24T21:29:40.300Z",
  "updatedAt": "2020-06-24T21:29:40.300Z",
  "webhookUrl": "https://www.myapi.com/notifications",
  "lastUpdatedAt": "2020-06-24T21:29:40.300Z"
}

This endpoint creates an item with the specified parameters & options.

HTTP Request

POST https://api.pluggy.ai/items

Body Parameters

Parameter Description
connectorId* The ID of the connector to link
parameters* An object with each key as the name and the value as the user's input
webhookUrl Url where notifications will be sent at any item's event

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:

This is an example for 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"
    }
  ]
}

Multi-Factor Authentication

Some connectors require a second step of verification when linking the account. This is a requirement from the institution to provide access to their data.
These type of connectors can be easily identified since they contain an attribute named hasMFA with value true, you can review this in the GET /connectors response.

Based on our experience we have split connectors - that require MFA - into two different flows.

MFA Independent

This flow is available when the required parameter can be provided before submitting the credentials, since its unrelated to the user session. (ie. Mobile token)

The first time you are linking an MFA connection you will receive in the credentials list the extra parameter. This is a one-use parameter and can't be reused for other collections.

If at some point you want to update the connection, you will be requested to send the MFA Credential as a parameter in the update item request. This means that you must provide the MFA parameter for the connector to start collecting data.

MFA User-Triggered

In the case, the additional parameter will be requested once the user has successfully logged in since it's triggered when the user accesses the institution (ie. coordinates card).
The first time you are linking the connector, you will be requested with the base credentials required to access the institution. After a couple seconds of submitting the credentials, an extra parameter will be requested and you will need to provide it in less than a minute. Once the MFA was provided and the execution restarted, no user interaction will be needed and the flow will continue as non MFA connectors.

If at some point you want to update the connection, you will be experiencing a similar flow. You won't neeed to send any MFA parameter to start the execution but the execution will require at some point the MFA parameter, that can be provided same as in the creation flow.

{
  "id": "ef3cad5e-db16-4a34-9453-5ed101a470f4",
  "connector": {
    "id": 1,
    "name": "Pluggy Bank AR with MFA",
    "primaryColor": "FFFFFF",
    "institutionUrl": "https://pluggy.ai",
    "country": "AR",
    "type": "PERSONAL_BANK",
    "credentials": [
      {
        "label": "User",
        "name": "user",
        "type": "text",
        "placeholder": "User",
        "validation": "^user-.{2,20}$",
        "validationMessage": "The user provided its invalid, should start with \"user-\"."
      },
      {
        "label": "Password",
        "name": "password",
        "type": "password",
        "placeholder": "************",
        "validation": "^password-.{2,20}$",
        "validationMessage": "The password provided its invalid, should start with \"password-\"."
      },
      {
        "name": "token",
        "label": "Mobile Token",
        "type": "number",
        "placeholder": "Example: 123456",
        "validation": "^\\d{6}$",
        "validationMessage": "Token must be 6 digits",
        "mfa": true
      }
    ],
    "imageUrl": "https://res.cloudinary.com/dkr0vihmp/image/upload/v1588853552/connectors-logos/plugg-sandbox_m2w5bd.png",
    "hasMFA": true
  },
  "createdAt": "2020-09-30T14:37:33.723Z",
  "updatedAt": "2020-09-30T14:37:37.172Z",
  "status": "WAITING_USER_INPUT",
  "executionStatus": "WAITING_USER_INPUT",
  "lastUpdatedAt": null,
  "webhookUrl": "",
  "error": null,
  "parameter": {
    "name": "sms",
    "label": "SMS Token",
    "type": "number",
    "placeholder": "Example: 123456",
    "validation": "^\\d{6}$",
    "validationMessage": "Token must be 6 digits"
  }
}

Send MFA Parameter

curl -X POST "https://api.pluggy.ai/items/d619cfde-a8d7-4fe0-a10d-6de488bde4e0/mfa" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>" \
  -d '{
    "token": "123456"
  }'
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .updateItemMFA("d619cfde-a8d7-4fe0-a10d-6de488bde4e0", {
    token: "123456"
  })
  .then((item) => {
    console.log(item);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Item item = await pluggyClient.UpdateItemMFA('d619cfde-a8d7-4fe0-a10d-6de488bde4e0', new ExecuteParameter("token", "123456"));

The above command returns JSON structured like this:

{
  "id": "ef3cad5e-db16-4a34-9453-5ed101a470f4",
  "connector": {},
  "createdAt": "2020-09-30T14:37:33.723Z",
  "updatedAt": "2020-09-30T14:37:37.172Z",
  "status": "UPDATING",
  "executionStatus": "WAITING_USER_INPUT",
  "parameter": null
}

This endpoint updates the parameter needed to continue the execution of the connector. Once provided the Item will be reflecting that is updating and the execution will resume in the short-term.

If the connection didn't receive the MFA response in less than a minute, it will timeout and update the item status to OUTDATED.

HTTP Request

POST https://api.pluggy.ai/items/<ID>/mfa

URL Parameters

Parameter Description
ID The ID of the item to provide MFA

Body Parameters

Parameter Description
[key] Value of the MFA parameter provided by the user.

The key attribute is the name of the parameter requested to the user to provide MFA.

Update an Item

curl -X PATCH "https://api.pluggy.ai/items/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>" \
  -d '{
    "parameters": {
        "user": "myuser",
        "password": "mypassword",
    },
    "webhookUrl": "https://www.myapi.com/notifications"
}'
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .updateItem("d619cfde-a8d7-4fe0-a10d-6de488bde4e0", {
    parameters: {
      user: "myuser",
      password: "mypassword",
    },
    webhookUrl: "https://www.myapi.com/notifications",
  })
  .then((item) => {
    console.log(item);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

ItemRequest parameters = new List<ItemParameters>()
{
  new ExecuteParameter("user", "user-ok"),
  new ExecuteParameter("password", "password-ok"),
};

ItemRequestOptions options = new ItemRequestOptions()
{
  WebhookUrl = "https://www.myapi.com/notifications"
};
Item item = await pluggyClient.UpdateItem('d619cfde-a8d7-4fe0-a10d-6de488bde4e0', parameters, options);

The above command returns JSON structured like this:

{
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "connectorId": 100,
  "status": "UPDATING",
  "executionStatus": "CREATED",
  "createdAt": "2020-06-24T21:29:40.300Z",
  "updatedAt": "2020-06-24T21:29:40.300Z",
  "webhookUrl": "https://www.myapi.com/notifications",
  "lastUpdatedAt": "2020-06-24T21:29:40.300Z"
}

This endpoint updates an item with the specified parameters & options. This will also trigger a sync of the user's data with the corresponding connector.

If the Item's status is LOGIN_ERROR the parameters are required to run a succesful sync of user's data.

If an empty body is sent, it will just refresh the connection with a new sync.

HTTP Request

PATCH https://api.pluggy.ai/items/<ID>

URL Parameters

Parameter Description
ID The ID of the item to update

Body Parameters

Parameter Description
parameters An object with each key as the name and the value as the user's input
webhookUrl Url where notifications will be sent at any item's event

All body parameters are optional and are only meant to be used if the item parameters need to be updated.

Get a Specific Item

curl "https://api.pluggy.ai/items/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.fetchItem("d619cfde-a8d7-4fe0-a10d-6de488bde4e0").then((item) => {
  console.log(item);
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Item item = await pluggyClient.FetchItem('d619cfde-a8d7-4fe0-a10d-6de488bde4e0');

The above command returns JSON structured like this:

{
  "connector": {
    "id": 0,
    "name": "string",
    "institutionUrl": "string"
  },
  "error": {},
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "status": "UPDATED",
  "executionStatus": "SUCCESS",
  "createdAt": "2020-06-24T21:45:22.850Z",
  "updatedAt": "2020-06-24T21:45:22.850Z",
  "webhookUrl": "https://www.myapi.com/notifications",
  "lastUpdatedAt": "2020-06-24T21:45:22.850Z"
}

This endpoint retrieves a specific item.

HTTP Request

GET https://api.pluggy.ai/items/<ID>

URL Parameters

Parameter Description
ID The ID of the item to retrieve

Delete a Specific Item

curl -X DELETE "https://api.pluggy.ai/items/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.deleteItem("d619cfde-a8d7-4fe0-a10d-6de488bde4e0").then(() => {
  console.log("deleted!");
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
await pluggyClient.DeleteItem('d619cfde-a8d7-4fe0-a10d-6de488bde4e0');

This endpoint deletes a specific item. This will also erase the parameters attached & all it's data.

The response for this request is an empty body

HTTP Request

DELETE https://api.pluggy.ai/items/<ID>

URL Parameters

Parameter Description
ID The ID of the item to delete

Accounts

Each item has a set of Accounts related to the user's connection with that specific institution. This accounts represent in Pluggy a Product that can be collected and updated in daily syncs.

This accounts have a set of fields that identifies that uniquely to the user's data in their corresponding institution and group his Transactions that were done by that account.

For more information visit the Products section for detailed explanation on what each field represents and it's occurrency.

Get Accounts of an Item

curl "https://api.pluggy.ai/accounts?itemId=d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchAccounts("d619cfde-a8d7-4fe0-a10d-6de488bde4e0")
  .then(({ results: accounts }) => {
    console.log(accounts);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
List<Account> accounts = await pluggyClient.FetchAccounts("d619cfde-a8d7-4fe0-a10d-6de488bde4e0");

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "4f61bd6d-e6fc-44b2-9c4b-5609058de7ab",
      "type": "CREDIT",
      "subtype": "CREDIT_CARD",
      "name": "Itau Uniclass 2.0 Mastercard Platinum",
      "marketingName": "Itau Uniclass 2.0 Mastercard Platinum",
      "taxNumber": "***.***.123-22",
      "owner": "FEDERICO MIRAS",
      "number": "1234",
      "balance": 142.41,
      "itemId": "fc214524-4725-4974-9f7a-0f1b50ea39e0",
      "currencyCode": "BRL",
      "creditData": {
        "level": "PLATINUM",
        "brand": "MASTERCARD",
        "balanceCloseDate": "2020-07-08",
        "balanceDueDate": "2020-07-17",
        "availableCreditLimit": 51300,
        "balanceForeignCurrency": 500,
        "minimumPayment": 100
      }
    }
  ]
}

This endpoint retrieves all accounts associated with the search of accounts for that specific Item.

HTTP Request

GET https://api.pluggy.ai/accounts

Query Parameters

Parameter Description
ItemId* ID of the item to retrieve the accounts
Type Type of the account to filter, BANK or CREDIT

Get a Specific Account

curl "https://api.pluggy.ai/accounts/4f61bd6d-e6fc-44b2-9c4b-5609058de7ab" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.fetchAccount("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab").then((account) => {
  console.log(account);
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Account account = await pluggyClient.FetchAccount("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab")

The above command returns JSON structured like this:

{
  "id": "4f61bd6d-e6fc-44b2-9c4b-5609058de7ab",
  "type": "CREDIT",
  "subtype": "CREDIT_CARD",
  "name": "Itau Uniclass 2.0 Mastercard Platinum",
  "marketingName": "Itau Uniclass 2.0 Mastercard Platinum",
  "taxNumber": "***.***.123-22",
  "owner": "FEDERICO MIRAS",
  "number": "1234",
  "balance": 142.41,
  "itemId": "fc214524-4725-4974-9f7a-0f1b50ea39e0",
  "currencyCode": "BRL",
  "creditData": {
    "level": null,
    "brand": "MASTERCARD",
    "balanceCloseDate": "2020-07-08",
    "balanceDueDate": "2020-07-17",
    "availableCreditLimit": 51300,
    "balanceForeignCurrency": 500,
    "minimumPayment": 100
  }
}

This endpoint retrieves a specific account.

HTTP Request

GET https://api.pluggy.ai/accounts/<ID>

URL Parameters

Parameter Description
ID The ID of the account to retrieve

Transactions

Each acccount contains a list of transactions that are updated on each item sync. Transactions represent in Pluggy a Product, that can be collected and updated in daily syncs. Each account is linked to a single Account thats the owner of that transaction.

For more information visit the Products section for detailed explanation on what each field represents.

Get Transactions of an Account

curl "https://api.pluggy.ai/transactions?accountId=d619cfde-a8d7-4fe0-a10d-6de488bde4e0&from=2020-01-01&to=2020-02-01&page=1&pageSize=50" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchTransactions(
    "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
    {
      from: "2020-01-01",
      to: "2020-05-01",
      page: 1,
      pageSize: 50
    }
  )
  .then(({ results: transactions }) => {
    console.log(transactions);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
List<Transaction> transactions = await pluggyClient.FetchTransactions("d619cfde-a8d7-4fe0-a10d-6de488bde4e0", "2020-01-01", "2020-05-01");

The above command returns JSON structured like this:

{
  "total": 2,
  "totalPages": 1,
  "page": 1,
  "results": [
    {
      "id": "443948f9-fcf2-4c97-90d4-aa573dd1c1ae",
      "description": "Mercpago*pacmansh 07/12",
      "currencyCode": "BRL",
      "amount": 16.86,
      "date": "2019-12-13T00:00:00.000Z",
      "balance": 16.86,
      "category": "Online Shopping"
    },
    {
      "id": "5d6b9f9a-06aa-491f-926a-15ba46c6366d",
      "description": "Rappi",
      "currencyCode": "BRL",
      "amount": 41.58,
      "date": "2020-06-08T00:00:00.000Z",
      "balance": 41.58,
      "category": "Online Payment"
    }
  ]
}

This endpoint retrieves all transactions associated with an accounts, filtered by dates.

HTTP Request

GET https://api.pluggy.ai/transactions

Query Parameters

Parameter Description
accountId* ID of the item to retrieve the accounts
from Transaction date filter start date
to Transaction date filter end date
pageSize The number of transactions to fetch. Default: 20, max: 500
page The page number to retrieve. Default: 1, paging starts at: 1

Get a Specific Transaction

curl "https://api.pluggy.ai/transactions/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchTransaction("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab")
  .then((account) => {
    console.log(account);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Transaction transaction = await pluggyClient.FetchTransaction("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab");

The above command returns JSON structured like this:

{
  "id": "5d6b9f9a-06aa-491f-926a-15ba46c6366d",
  "description": "Rappi",
  "currencyCode": "BRL",
  "amount": 41.58,
  "date": "2020-06-08T00:00:00.000Z",
  "balance": 41.58,
  "category": "Online Payment"
}

This endpoint retrieves a specific transaction.

HTTP Request

GET https://api.pluggy.ai/transactions/<ID>

URL Parameters

Parameter Description
ID The ID of the transaction to retrieve

Investments

Each item has a set of Investments related to the user's connection with that specific institution. This investment represent in Pluggy a Product that can be collected and updated in daily syncs.

This investments have a set of fields that identifies that uniquely to the user's data in their corresponding institution in detail its status and balances.

For more information visit the Products section for detailed explanation on what each field represents and it's occurrency.

Get Invesments of an Item

curl "https://api.pluggy.ai/investments?itemId=d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchInvestments("d619cfde-a8d7-4fe0-a10d-6de488bde4e0")
  .then(({ results: investments }) => {
    console.log(investments);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
List<Investment> investments = await pluggyClient.FetchInvestments("d619cfde-a8d7-4fe0-a10d-6de488bde4e0");

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
      "number": null,
      "name": "Fondo de Investimento Premium",
      "balance": 1359.39,
      "currencyCode": "BRL",
      "type": "MUTUAL_FUND",
      "annualRate": 3.24,
      "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
      "code": "12.345.678/0001-00",
      "value": 500,
      "quantity": 3,
      "amount": 1500,
      "taxes": 40.61,
      "taxes2": 100,
      "date": "2020-07-19T18:27:41.802Z",
      "owner": "John Doe",
      "amountProfit": null,
      "amountWithdrawal": 1310.5
    }
  ]
}

This endpoint retrieves all entities associated with the search of invesments for that specific Item.

HTTP Request

GET https://api.pluggy.ai/investments

Query Parameters

Parameter Description
ItemId* ID of the item to retrieve the accounts
Type Type of the account to filter. For more info: Investments Type

Get a Specific Investment

curl "https://api.pluggy.ai/investments/4f61bd6d-e6fc-44b2-9c4b-5609058de7ab" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchInvestment("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab")
  .then((investment) => {
    console.log(investment);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Investment investment =
  await pluggyClient.FetchInvestment("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab");

The above command returns JSON structured like this:

{
  "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
  "number": null,
  "name": "Fondo de Investimento Premium",
  "balance": 1359.39,
  "currencyCode": "BRL",
  "type": "MUTUAL_FUND",
  "annualRate": 3.24,
  "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
  "code": "12.345.678/0001-00",
  "value": 500,
  "quantity": 3,
  "amount": 1500,
  "taxes": 40.61,
  "taxes2": 100,
  "date": "2020-07-19T18:27:41.802Z",
  "owner": "John Doe",
  "amountProfit": null,
  "amountWithdrawal": 1310.5
}

This endpoint retrieves a specific account.

HTTP Request

GET https://api.pluggy.ai/investments/<ID>

URL Parameters

Parameter Description
ID The ID of the investment to retrieve

Identity

Each item may have an Identity entity, which is a set of personal attributes such as names, phones or emails, that identifies the user in that specific institution. This identity represent in Pluggy a Product that can be collected and updated in daily syncs.

This identity has a set of fields that are available to verify the user identity and provide Know Your Customer tools. This can also be used for autocompleting account data or Fraud reduction.

For more information visit the Products section for detailed explanation on what each field represents and it's occurrency.

Get Identity of an Item

curl "https://api.pluggy.ai/identity?itemId=d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchIdentityByItemId("d619cfde-a8d7-4fe0-a10d-6de488bde4e0")
  .then((identity) => {
    console.log(identity);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Identity identity = await pluggyClient.FetchIdentityByItemId("d619cfde-a8d7-4fe0-a10d-6de488bde4e0");

The above command returns JSON structured like this:

{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "fullName": "Luis Gonzalez",
  "document": "11.111.111",
  "taxNumber": "20-11111111-2",
  "documentType": "DNI",
  "jobTitle": "Estudiante",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "addresses": [
    {
      "fullAddress": "Av. Cabildo 1234, Belgrano, CABA, Argentina",
      "country": "Argentina",
      "state": "CABA",
      "city": "Belgrano",
      "postalCode": "123456",
      "primaryAddress": "Av. Cabildo 1234",
      "type": "Personal"
    }
  ],
  "phoneNumbers": [
    {
      "type": "Personal",
      "value": "+54 911 12345678"
    }
  ],
  "emails": [
    {
      "type": "Personal",
      "value": "myemail@pluggy.ai"
    }
  ],
  "relations": [
    {
      "type": "Father",
      "name": "Juan Gonzalez"
    },
    {
      "type": "Spouse",
      "name": "Laura Garcia"
    }
  ],
  "createdAt": "2020-09-30T14:38:12.724Z",
  "updatedAt": "2020-09-30T14:38:12.724Z"
}

This endpoint retrieves the entity associated with the search of identity for that specific Item.

HTTP Request

GET https://api.pluggy.ai/identity

Query Parameters

Parameter Description
ItemId* ID of the item to retrieve the accounts

Get a Specific Identity

curl "https://api.pluggy.ai/identity/4f61bd6d-e6fc-44b2-9c4b-5609058de7ab" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchIdentity("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab")
  .then((identity) => {
    console.log(identity);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Identity identity =
  await pluggyClient.FetchIdentity("4f61bd6d-e6fc-44b2-9c4b-5609058de7ab");

The above command returns JSON structured like this:

{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "fullName": "Luis Gonzalez",
  "document": "11.111.111",
  "taxNumber": "20-11111111-2",
  "documentType": "DNI",
  "jobTitle": "Estudiante",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "addresses": [
    {
      "fullAddress": "Av. Cabildo 1234, Belgrano, CABA, Argentina",
      "country": "Argentina",
      "state": "CABA",
      "city": "Belgrano",
      "postalCode": "123456",
      "primaryAddress": "Av. Cabildo 1234",
      "type": "Personal"
    }
  ],
  "phoneNumbers": [
    {
      "type": "Personal",
      "value": "+54 911 12345678"
    }
  ],
  "emails": [
    {
      "type": "Personal",
      "value": "myemail@pluggy.ai"
    }
  ],
  "relations": [
    {
      "type": "Father",
      "name": "Juan Gonzalez"
    },
    {
      "type": "Spouse",
      "name": "Laura Garcia"
    }
  ],
  "createdAt": "2020-09-30T14:38:12.724Z",
  "updatedAt": "2020-09-30T14:38:12.724Z"
}

This endpoint retrieves a specific account.

HTTP Request

GET https://api.pluggy.ai/identity/<ID>

URL Parameters

Parameter Description
ID The ID of the identity to retrieve

Webhooks

A Webhook is a tool that allows you to receive a notification for a certain event. It allows you to setup an HTTPS url in our platform for certain events and you will received a JSON POST event in that url, with specific event data.

Currently we support registering for the following events

Event Description
item/created An item was created and its connecting to provider
item/updated An item was updated and synced succesfully.
item/error An item was encounter errors in its execution
item/waiting_user_input An item it's blocked waiting for user input to continue
all Receive all events

To register for an specific event you will have to send the desired on as the event to attach. There is also an option all to receive all events associated.

We only accept https urls. localhost url are not allowed to be used, you will have to provide an https url using ngrok or other tools to provide public secured urls.

Just to review the functionallity you can use RequestCatcher, which is a tool that will just receive our notification and show you the payload. You can easily create a catcher with just a name in seconds.

Payload parameters

When doing the POST request, all webhooks will send the following parameters in JSON format:

Retry policies

A webhook notification expects a 2XX status code in the response, if you need to do some work with the event you should process after replying back.

If there is a communication error (no response or an error) we will retry the notification 10 times along the next three days in incremental interval of time. Then the notification will be lost.

Create a Webhook

curl --location --request POST "https://api.pluggy.ai/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>" \
  -d '{
    "event": "item/updated",
    "url": "https://www.myapi.com/notifications"
}'
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .createWebhook({
    event: "item/updated",
    url: "https://www.myapi.com/notifications",
  })
  .then((item) => {
    console.log(item);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Webhook webhook = await pluggyClient.CreateWebhook("https://www.myapi.com/notifications", WebhookEvent.ItemCreated);

The above command returns JSON structured like this:

{
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "event": "item/updated",
  "url": "https://www.myapi.com/notifications",
  "createdAt": "2020-06-24T21:29:40.300Z",
  "updatedAt": "2020-06-24T21:29:40.300Z"
}

This endpoint creates a webhook attached to the specific event and provides the notification url.

HTTP Request

POST https://api.pluggy.ai/webhooks

Body Parameters

Parameter Description
event The type of event to attach for notifications
url A url to be notified of the events

Update a Webhook

curl -X PATCH "https://api.pluggy.ai/webhooks/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>" \
  -d '{
    "event": "all",
    "url": "https://www.myapi.com/notifications"
}'
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .updateWebhook("d619cfde-a8d7-4fe0-a10d-6de488bde4e0", {
    event: "all",
    url: "https://www.myapi.com/notifications",
  })
  .then((webhook) => {
    console.log(webhook);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Webhook webhook = await pluggyClient.UpdateWebhook('d619cfde-a8d7-4fe0-a10d-6de488bde4e0', "https://www.myapi.com/notifications", WebhookEvent.All);

The above command returns JSON structured like this:

{
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "event": "all",
  "url": "https://www.myapi.com/notifications",
  "createdAt": "2020-06-24T21:29:40.300Z",
  "updatedAt": "2020-06-24T21:29:40.300Z"
}

This endpoint updates a webhook event and/or url listener. Once updated all events that are triggered will replicate the updated logic.

HTTP Request

PATCH https://api.pluggy.ai/webhooks

URL Parameters

Parameter Description
ID The ID of the webhook to update

Body Parameters

Parameter Description
event The type of event to attach for notifications
url A url to be notified of the events

Get all Webhooks

curl "https://api.pluggy.ai/webhooks" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchWebhooks()
  .then(({ results: webhooks }) => {
    console.log(webhooks);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
List<Webhook> webhooks = await pluggyClient.FetchWebhooks();

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
      "event": "item/updated",
      "url": "https://www.myapi.com/notifications",
      "createdAt": "2020-06-24T21:29:40.300Z",
      "updatedAt": "2020-06-24T21:29:40.300Z"
    },
    {
      "id": "207f5bcd-312a-439c-abbe-166b6632c980",
      "event": "item/all",
      "url": "https://www.myapi.com/notifications",
      "createdAt": "2020-06-24T21:29:40.300Z",
      "updatedAt": "2020-06-24T21:29:40.300Z"
    }
  ]
}

This endpoint retrieves all Webhooks associated with your application.

HTTP Request

GET https://api.pluggy.ai/webhooks

Get a Specific Webhook

curl "https://api.pluggy.ai/webhooks/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.fetchWebhook("d619cfde-a8d7-4fe0-a10d-6de488bde4e0").then((webhook) => {
  console.log(webhook);
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Webhook webhook = await pluggyClient.FetchWebhook('d619cfde-a8d7-4fe0-a10d-6de488bde4e0');

The above command returns JSON structured like this:

{
  "id": "d619cfde-a8d7-4fe0-a10d-6de488bde4e0",
  "event": "item/updated",
  "url": "https://www.myapi.com/notifications",
  "createdAt": "2020-06-24T21:29:40.300Z",
  "updatedAt": "2020-06-24T21:29:40.300Z"
}

This endpoint retrieves a specific webhook.

HTTP Request

GET https://api.pluggy.ai/webhooks/<ID>

URL Parameters

Parameter Description
ID The ID of the item to retrieve

Delete a Specific Webhook

curl -X DELETE "https://api.pluggy.ai/webhooks/d619cfde-a8d7-4fe0-a10d-6de488bde4e0" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client.deleteWebhook("d619cfde-a8d7-4fe0-a10d-6de488bde4e0").then(() => {
  console.log("deleted!");
});
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
await pluggyClient.DeleteWebhook('d619cfde-a8d7-4fe0-a10d-6de488bde4e0')

This endpoint deletes a webhook listener.

The response for this request is an empty body

HTTP Request

DELETE https://api.pluggy.ai/webhooks/<ID>

URL Parameters

Parameter Description
ID The ID of the webhook to delete

Categories

Each account transaction is enhanced using our DataEnrichment API, that improves and adds value to the transactions recovered from the different institutions. One of the key features is Categorization, that matches the transaction using our Categorizator to one of our Categories that will provide extra information about the transaction.

Each category follows an hierachy, this means that each one has a Parent category that groups the categories that are for similar porpouses. IE. Transfer has multiple childs as Deposit, Check or ATM Withdrawal.

Get available categories

curl "https://api.pluggy.ai/categories" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchCategories()
  .then(({ results: categories }) => {
    console.log(categories);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
List<Category> categories = await pluggyClient.FetchCategories();

The above command returns JSON structured like this:

{
  "results": [
    {
      "id": "01000000",
      "description": "Transfer"
    },
    {
      "id": "01000001",
      "description": "ATM Withdrawal",
      "parentId": "01000000",
      "parentDescription": "Transfer"
    },
    {
      "id": "01000002",
      "description": "ATM Deposit",
      "parentId": "01000000",
      "parentDescription": "Transfer"
    }
  ]
}

This endpoint retrieves all available categories that our categorization uses.

HTTP Request

GET https://api.pluggy.ai/categories

Query Parameters

Parameter Description
parentId Category parent code (ID), to filter only child categories.

Get a Specific Category

curl "https://api.pluggy.ai/categories/01000000" \
  -H "X-API-KEY: <YOUR_PLUGGY_API_KEY>"
var pluggy = require("pluggy-sdk");

var client = new pluggy.PluggyClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

client
  .fetchCategory("01000001")
  .then((category) => {
    console.log(category);
  });
PluggyClient pluggyClient = new PluggyClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
Category category =
  await pluggyClient.FetchCategory("01000001");

The above command returns JSON structured like this:

{
  "id": "01000001",
  "description": "ATM Withdrawal",
  "parentId": "01000000",
  "parentDescription": "Transfer"
}

This endpoint retrieves a specific category.

HTTP Request

GET https://api.pluggy.ai/categories/<ID>

URL Parameters

Parameter Description
ID The ID of the category to retrieve

Products

When recovering items a list of products is returned depending 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": {}
}

Account

The account product is the list of bank account such as Checking or Savings Account and Credit Card, that were available in the selected connector.

The response will vary depending on the Accounts Type

JSON example, if the account's type is CREDIT.

{
  "id": "4f61bd6d-e6fc-44b2-9c4b-5609058de7ab",
  "type": "BANK",
  "subtype": "CREDIT_CARD",
  "name": "Itau Uniclass 2.0 Mastercard Platinum",
  "marketingName": "Itau Uniclass 2.0 Mastercard Platinum",
  "taxNumber": "***.***.123-22",
  "owner": "FEDERICO MIRAS",
  "number": "1234",
  "balance": 142.41,
  "itemId": "fc214524-4725-4974-9f7a-0f1b50ea39e0",
  "currencyCode": "BRL",
  "creditData": {
    "level": "PLATINUM",
    "brand": "MASTERCARD",
    "balanceCloseDate": "2020-07-08",
    "balanceDueDate": "2020-07-17",
    "availableCreditLimit": 51300,
    "balanceForeignCurrency": 500,
    "minimumPayment": 100
  }
}
Property Description
type Type of account. For more info: Accounts Type
subtype Subtype of account. For more info: Accounts Type
number Number of the account, ie xx-41234/02.
balance Current available balance of the account.
currencyCode Currency ISO code of the account, ie USD or EUR
name Name of the account, ie. Saving Account 1234 or Mastercard Gold.
marketingName Extra name provided for some accounts that are related to level of the account. Not always provided.
owner Name of the owner of the account.
taxNumber Tax number of the owner of the account.
transactions List of transactions of the account.
bankData Specific data for bank account types. For more info: Bank Data
creditData Specific data for credit account types. For more info: Credit Data

Bank Data

Property Description
transferNumber Unique account number for the country, IBAN / CBU / other.
closingBalance Current balance of the account.

Credit Data

Property Description
minimumPayment Balance minimum payment for the current period.
balanceForeignCurrency Balance in foreign currency for the current period.
availableCreditLimit Available credit limit for the account
balanceDueDate Due Date for the credit
balanceCloseDate Close date when the balance was calculated

Transaction

The Transaction entity applies for both Accounts & Credit Cards, and contains the financial transaction information for that movement.

{
  "date": "03/09/2019",
  "description": "COMPRA VENTA MON.EXTRANJERA",
  "value": -53631,
  "operationId": "201911012",
  "balance": 1270.2,
  "currencyCode": "ARS"
}
Property Description
date Posted date of the transaction, formatted in ISO8601
description Description of the transaction
value Amount of the transaction.
balance Balance after transaction
currencyCode Currency iso code of the transaction, ie USD
category Category of the transactions, that was matched by our DataEnrichment API

Investment

The Investment entity is recovered from institutions that support this product, and details an specific investment status independant of the type. ie. if there account has multiple investments for Mutual Funds you will receive one entity for each

[
  {
    "id": "f77eccf4-7714-498e-92a9-1bebe70335d9",
    "number": null,
    "name": "Fondo de Investimento Premium",
    "balance": 1359.39,
    "currencyCode": "BRL",
    "type": "MUTUAL_FUND",
    "annualRate": 3.24,
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": "12.345.678/0001-00",
    "value": 500,
    "quantity": 3,
    "amount": 1500,
    "taxes": 40.61,
    "taxes2": 100,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "amountProfit": null,
    "amountWithdrawal": 1310.5
  },
  {
    "id": "2a96b873-53bb-4d16-a3d8-385a57e78d7e",
    "number": null,
    "name": "CDR",
    "balance": 2000,
    "currencyCode": "BRL",
    "type": "FIXED_INCOME",
    "annualRate": null,
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": "0001-02",
    "value": null,
    "quantity": null,
    "amount": 2500,
    "taxes": null,
    "taxes2": null,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "amountProfit": null,
    "amountWithdrawal": 2000
  },
  {
    "id": "ded7d2f1-6b90-44a8-9ace-de747b9f5bfe",
    "number": "123456-2",
    "name": "Pluggy PREVIDENCIA",
    "balance": 1359.39,
    "currencyCode": "BRL",
    "type": "SECURITY",
    "annualRate": 3.24,
    "itemId": "207f5bcd-312a-439c-abbe-166b6632c980",
    "code": null,
    "value": 500,
    "quantity": 3,
    "amount": 1500,
    "taxes": 0,
    "taxes2": 0,
    "date": "2020-07-19T18:27:41.802Z",
    "owner": "John Doe",
    "amountProfit": 359.39,
    "amountWithdrawal": 1310.5
  }
]
Property Description
name Name of the Investment
code Investment associated code, specific fund number
number Investment number, not always provided.
owner Owner/benificiary associated to the investment
currencyCode Currency iso code of the transaction, ie USD
type Investment type. For more info: Investments Type
annualRate Annual interest for the last 12 months
date Value quota date
value Quota's current value at date
quantity Quantity of quota at disposal
amount Gross amount of the investment
taxes Taxes applied to the investment, BR: IR, AR: IVA
taxes2 Taxes applied to the investment, BR: IOF, AR: Ganancias
balance Current balance of the investment
amountProfit Profit to date over the investment.
amountWithdrawal Amount available to withdraw

Identity

The Identity entity is recovered from institutions that support this product, accessing details personal information related to the owner of the connection's account. Recovering this product helps you verify users' identity.

{
  "id": "42888436-62f5-49d2-8cf9-e312c7939509",
  "fullName": "Luis Gonzalez",
  "document": "11.111.111",
  "taxNumber": "20-11111111-2",
  "documentType": "DNI",
  "jobTitle": "Estudiante",
  "birthDate": "1991-05-01T00:00:00.000Z",
  "addresses": [
    {
      "fullAddress": "Av. Cabildo 1234, Belgrano, CABA, Argentina",
      "country": "Argentina",
      "state": "CABA",
      "city": "Belgrano",
      "postalCode": "123456",
      "primaryAddress": "Av. Cabildo 1234",
      "type": "Personal"
    }
  ],
  "phoneNumbers": [
    {
      "type": "Personal",
      "value": "+54 911 12345678"
    }
  ],
  "emails": [
    {
      "type": "Personal",
      "value": "hello@pluggy.ai"
    }
  ],
  "relations": [
    {
      "type": "Father",
      "name": "Juan Gonzalez"
    },
    {
      "type": "Spouse",
      "name": "Laura Garcia"
    }
  ],
  "createdAt": "2020-09-30T14:38:12.724Z",
  "updatedAt": "2020-09-30T14:38:12.724Z"
}
Property Description
fullName Name of the owner of the account
document Primary document that identifies the owner
documentType Type of document collected.
taxNumber Tax ID associated with the owner.
jobTitle Profession or Job information
birthDate Date of birth.
addresses List of addresses related to the account. Address schema
phoneNumbers List of phone numbers related to the account. Phone schema
emails List of email addresses related to the account. Email schema
relations List of names related to the account. Relation schema

Schemas

Address Schema

The address object contains data related to an specific owner's location.

{
  "fullAddress": "Av. Cabildo 1234, Belgrano, CABA, Argentina",
  "country": "Argentina",
  "state": "CABA",
  "city": "Belgrano",
  "postalCode": "123456",
  "primaryAddress": "Av. Cabildo 1234",
  "type": "Personal"
}
Property Description
fullAddress Full address using all components available.
country The complete country name
state The state or province.
city The complete city name
postalCode The Zip code
primaryAddress Primary address, stret name and street number
type Type of address, Personal or Work

Email Schema

The email object contains emails associated with the owner of the account

{
  "type": "Personal",
  "value": "hello@pluggy.ai"
}
Property Description
type Personal or Work.
value The full email of the person.

Phone Schema

The phone number object contains data related to contact information.

{
  "type": "Personal",
  "value": "+54 911 12345678"
}
Property Description
type Work, Personal or Residencial.
value The complete phone number.

Relation Schema

The relation object contains name and relation to the owner of the account.

{
  "type": "Father",
  "name": "Juan Gonzalez"
}
Property Description
type Father, Mother or Spouse.
value The full name of the person.

Types

All our products reference list types values,

Account Type

The following options are currently available:

Value Description Sub types
BANK Bank accounts SAVINGS_ACCOUNT, CHECKING_ACCOUNT
CREDIT Credit accounts CREDIT_CARD, MERCADOPAGO

Investment Type

The following options are currently available:

Value Description
MUTUAL_FUNDS Mutual funds
EQUITY Company equities or shares
SECURITY Private social securities
FIXED_INCOME Investments with fixed income as Bonds or CD

Connectors Type

The following options are currently available:

Value Description
PERSONAL_BANK Personal / retail bank accounts
BUSINESS_BANK Companies bank accounts
INVOICE Invoicing connections. ie Quickbooks
INVESTMENT Investment platforms. ie. XP, Balanz, etc

Errors

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource you are triying to access, you dont have permissions
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- The specific endpoint doens't support that method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You've exceed your quota limit.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.