> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pluggy as a data source

> Bring Open Finance data collected by Pluggy to your Lakehouse.

Pluggy is a Brazilian Open Finance data aggregator. Through Pluggy, a person or a company connects their bank accounts, credit cards, investments and loans, and Pluggy keeps collecting that data from the institutions with the user's consent. The connector reads, from your own Pluggy application, what Pluggy collected for your connections: accounts and credit cards, transactions, credit card bills, investments and their movements, loans, identity data and consents, plus the list of categories and institutions.

## Configuring Pluggy as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Pluggy option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector uses the **Client ID** and **Client Secret** of your Pluggy application. Open the [Pluggy Dashboard](https://dashboard.pluggy.ai), go to **Applications** and copy both from the application that holds the connections you want to sync. Use the production application: development applications are limited and do not refresh connections automatically. Nekt uses these credentials only to create the temporary API key that reads your data; it never creates, updates or deletes connections.

In Pluggy, each connection to a bank or institution is an **item**, identified by an item id such as `0b8d4b2a-1c3e-4f5a-9b6c-7d8e9f0a1b2c`. Your application receives the item id when a connection is created (in the Pluggy Connect `onSuccess` callback and in the `item/created` webhook), and the Pluggy Dashboard shows it for connections made there.

The following configurations are available:

* **Client ID**: the Client ID of your Pluggy application. Required.

* **Client Secret**: the Client Secret of the same application. Required.

* **Item IDs**: the item ids of the connections to sync. Leave it empty to sync every item of the application.

<Warning>Listing every item of an application is a Pluggy feature that is disabled by default. If you leave **Item IDs** empty and Pluggy has not enabled item listing for your team, the sync stops with a message asking you to fill in the item ids. Ask Pluggy support to enable it, or list the items to sync.</Warning>

* **Start Date**: the earliest transaction date to sync. Leave it empty to sync every transaction Pluggy holds. It only applies to transactions; the other tables always bring the current state.

* **Transactions lookback (days)**: (Default: 30) transactions dated within this many days are read again on every sync, to pick up changes of status (pending to posted), category or description. Pending transactions older than that are followed one by one until they settle (see [How transactions are kept up to date](#how-transactions-are-kept-up-to-date)).

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: use INCREMENTAL for Transactions, which reads only what changed on each sync. Every other stream is FULL\_TABLE: Pluggy has no "changed since" filter for them, so each sync reads their current state. Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. Pluggy refreshes each connection with the institution on its own schedule (usually once a day, as agreed with Pluggy), so syncing more often than that brings little new data.

Optionally, you can define some additional settings:

* Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. Transactions do not need it: incremental syncs already mark the transactions Pluggy removed (see [Data Quality Considerations](#data-quality-considerations)). If you schedule one, read the warning in that section first.

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

<Warning>For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.</Warning>

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Description |
| - | - | - |
| Items | `items` | Connections of your Pluggy application, one per institution, with sync status and consent expiry. |
| Accounts | `accounts` | Bank accounts and credit cards of each item. |
| Transactions | `transactions` | Bank statement lines and credit card transactions. Incremental. |
| Credit Card Bills | `credit_card_bills` | Bills of each credit card. |
| Investments | `investments` | Investment positions of each item. |
| Investment Transactions | `investment_transactions` | Movements of each investment. |
| Loans | `loans` | Loans and financings of each item. |
| Identities | `identities` | Registration data of the holder of each item. |
| Consents | `consents` | Consents given for each item. |
| Categories | `categories` | Transaction categories. |
| Connectors | `connectors` | Institutions available in Pluggy. |

## Fields by stream

Nested structures (payment data, credit card details, bank and credit card details, loan terms, contacts) are JSON strings; the most used values are also available as their own columns, such as `credit_limit`, `bill_id`, `installment_number` and `payment_method`. Fields Pluggy adds in the future land in `additional_fields` until they get a column of their own. Dates are in UTC.

<AccordionGroup>
  <Accordion title="Items">
    One row per Pluggy item: the connection between your Pluggy application and one bank or institution, with its sync status and consent expiry.

    Table: `items` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the item: one connection between your Pluggy application and an institution. |
    | `status` | String | Connection status: UPDATED, UPDATING, LOGIN\_ERROR, OUTDATED or WAITING\_USER\_INPUT. |
    | `execution_status` | String | Step or result of the item's last sync with the institution (e.g. SUCCESS, PARTIAL\_SUCCESS, ERROR, USER\_AUTHORIZATION\_REVOKED). |
    | `connector_id` | Integer | Identifier of the Pluggy connector (institution) of the item; joins with connectors.id. |
    | `connector_name` | String | Name of the institution of the item. |
    | `connector_type` | String | Type of the institution (e.g. PERSONAL\_BANK, BUSINESS\_BANK, INVESTMENT). |
    | `connector_is_open_finance` | Boolean | Whether the item uses the regulated Open Finance connector of the institution. |
    | `connector` | String (JSON) | Connector (institution) details as returned by Pluggy (JSON object). |
    | `client_user_id` | String | Identifier your application assigned to the end user when the item was created. |
    | `products` | Array of strings | Products collected by the item (ACCOUNTS, CREDIT\_CARDS, TRANSACTIONS, INVESTMENTS, IDENTITY, LOANS...). |
    | `error_code` | String | Error code of the last failed sync, when there is one. |
    | `error_message` | String | Error message of the last failed sync, when there is one. |
    | `error_provider_message` | String | Message from the institution about the last failed sync, usually an action the user must take. |
    | `user_action_type` | String | Kind of action the user must take to continue the sync (scan a QR code, authorize in the institution's app), when one is pending. |
    | `user_action_instructions` | String | Instructions for the pending user action. |
    | `user_action_expires_at` | Datetime | When the pending user action expires. |
    | `status_detail` | String (JSON) | Per-product sync status of the last execution, with warnings (JSON object). |
    | `consecutive_failed_login_attempts` | Integer | Consecutive executions that ended in LOGIN\_ERROR. |
    | `consent_expires_at` | Datetime | When the consent given by the user expires; after it, Pluggy returns no data for this item until it is reconnected. |
    | `next_auto_sync_at` | Datetime | When Pluggy will sync the item again automatically (null when the application has no auto-sync). |
    | `resources_collected_at` | Datetime | Open Finance only: when the list of resources declared by the institution was last read. |
    | `has_resources_pending_authorization` | Boolean | Open Finance only: whether some resource of the consent still waits for the user's authorization at the institution. |
    | `created_at` | Datetime | When the item was created. |
    | `updated_at` | Datetime | When the item was last modified. |
    | `last_updated_at` | Datetime | When the item last finished a sync with the institution. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Accounts">
    Bank accounts (checking, savings) and credit cards of each item, with balances, limits and due dates.

    Table: `accounts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the account in Pluggy. |
    | `item_id` | String | Item (connection) the account belongs to; joins with items.id. |
    | `type` | String | Account category: BANK (checking, savings) or CREDIT (credit card). |
    | `subtype` | String | Account subtype: CHECKING\_ACCOUNT, SAVINGS\_ACCOUNT or CREDIT\_CARD. |
    | `number` | String | Account number at the institution (or the masked card number). |
    | `name` | String | Descriptive name of the account. |
    | `marketing_name` | String | Name of the account as the institution markets it. |
    | `owner` | String | Name of the account holder. |
    | `tax_number` | String | Tax ID (CPF or CNPJ) of the account holder. |
    | `balance` | Number | Current balance of the account; for credit cards, the amount owed on the card. |
    | `currency_code` | String | ISO currency code of the balance (e.g. BRL). |
    | `bank_transfer_number` | String | Bank accounts: full account number for transfers (branch / account). |
    | `bank_closing_balance` | Number | Bank accounts: balance including transactions not posted yet. |
    | `bank_automatically_invested_balance` | Number | Bank accounts: balance automatically invested by the institution. |
    | `bank_overdraft_contracted_limit` | Number | Bank accounts: contracted overdraft limit. |
    | `bank_overdraft_used_limit` | Number | Bank accounts: overdraft limit in use. |
    | `bank_unarranged_overdraft_amount` | Number | Bank accounts: emergency credit used to cover a negative balance beyond the contracted limit. |
    | `bank_data` | String (JSON) | All bank account details returned by Pluggy, reserved balances included (JSON object). |
    | `credit_level` | String | Credit cards: card level (e.g. Black, Signature). |
    | `credit_brand` | String | Credit cards: card brand (e.g. Visa, Mastercard, Elo). |
    | `credit_status` | String | Credit cards: card status (ACTIVE, BLOCKED, CANCELLED). |
    | `credit_holder_type` | String | Credit cards: MAIN or ADDITIONAL holder. |
    | `credit_balance_close_date` | Datetime | Credit cards: closing date of the current bill. |
    | `credit_balance_due_date` | Datetime | Credit cards: due date of the current bill. |
    | `credit_limit` | Number | Credit cards: total credit limit. |
    | `credit_available_limit` | Number | Credit cards: credit limit still available. |
    | `credit_minimum_payment` | Number | Credit cards: minimum payment of the current bill. |
    | `credit_balance_foreign_currency` | Number | Credit cards: balance in foreign currency (USD). |
    | `credit_data` | String (JSON) | All credit card details returned by Pluggy, limits and additional cards included (JSON object). |
    | `created_at` | Datetime | When the account was first collected by Pluggy. |
    | `updated_at` | Datetime | When the account data was last updated. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Transactions">
    Statement lines of bank accounts and purchases, payments and installments of credit cards, with category, payment data and merchant.

    Table: `transactions` · Primary key: `id` · Sync: Incremental (replication key `updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the transaction in Pluggy. Pluggy may delete a transaction and create it again with a new id when its date, amount or description changes. |
    | `account_id` | String | Account of the transaction; joins with accounts.id. |
    | `item_id` | String | Item (connection) of the account; joins with items.id. |
    | `date` | Datetime | Date of the transaction (UTC). For PENDING scheduled payments and future installments it can be in the future. |
    | `description` | String | Description of the transaction, cleaned up by Pluggy. |
    | `description_raw` | String | Description exactly as the institution returned it. |
    | `amount` | Number | Amount of the transaction. On credit cards a positive amount is a charge and a negative amount a payment or credit. |
    | `amount_in_account_currency` | Number | Amount in the account's currency, for transactions made in another currency. |
    | `currency_code` | String | ISO currency code of the amount (e.g. BRL). |
    | `balance` | Number | Account balance right after the transaction, when the institution provides it. |
    | `type` | String | Direction of the money for the account holder: CREDIT (inflow) or DEBIT (outflow). |
    | `status` | String | POSTED (settled) or PENDING (open credit card bill, future installment, blocked or scheduled transaction). |
    | `category` | String | Category assigned by Pluggy's categorization (e.g. Restaurants, Transfer); requires the feature in the Pluggy subscription. |
    | `category_id` | String | Identifier of the category; joins with categories.id. |
    | `operation_type` | String | Type of operation reported by the institution (e.g. PIX, TED, BOLETO, PAGAMENTO\_FATURA). |
    | `operation_type_additional_info` | String | Additional information about the operation type, as the institution reports it. |
    | `provider_code` | String | Code of the transaction at the institution (e.g. NSU), when available. |
    | `provider_id` | String | Identifier of the transaction at the institution; Open Finance connectors only. Stable across Pluggy re-creations. |
    | `transaction_order` | Integer | Position of the transaction among transactions of the same date (Pluggy's `order` field). |
    | `payment_method` | String | Payment rail of a payment or transfer (PIX, TED, DOC, BOLETO...), from the payment data. |
    | `payment_data` | String (JSON) | Payer, receiver, reference numbers and boleto data of a payment or transfer (JSON object). |
    | `bill_id` | String | Credit cards: bill the transaction belongs to; joins with credit\_card\_bills.id. |
    | `installment_number` | Integer | Credit cards: number of this installment of the purchase. |
    | `total_installments` | Integer | Credit cards: total number of installments of the purchase. |
    | `credit_card_metadata` | String (JSON) | Credit card details of the transaction: installments, card number, bill, purchase date (JSON object). |
    | `merchant_name` | String | Name of the merchant, when Pluggy identifies it. |
    | `merchant_cnpj` | String | CNPJ of the merchant, when Pluggy identifies it. |
    | `merchant` | String (JSON) | Merchant details: name, legal name, CNPJ, CNAE and category (JSON object). |
    | `created_at` | Datetime | When Pluggy first ingested the transaction. |
    | `updated_at` | Datetime | When the transaction was last updated in Pluggy (for a removed row, when Nekt detected the removal); the incremental replication key. |
    | `removed_at` | Datetime | When Nekt found that Pluggy no longer has this transaction (cancelled, or recreated by Pluggy with a new id). Null while it exists; removed rows keep only id, account, date and this column. Filter removed\_at IS NULL for totals. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Credit Card Bills">
    Bills (faturas) of each credit card account, with charges and payments.

    Table: `credit_card_bills` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the bill in Pluggy. |
    | `account_id` | String | Credit card account of the bill; joins with accounts.id. |
    | `item_id` | String | Item (connection) of the account; joins with items.id. |
    | `due_date` | Datetime | Due date of the bill. |
    | `bill_closing_date` | Datetime | Date the bill was closed. |
    | `total_amount` | Number | Total amount of the bill. |
    | `total_amount_currency_code` | String | ISO currency code of the total amount. |
    | `minimum_payment_amount` | Number | Minimum payment of the bill. |
    | `allows_installments` | Boolean | Whether the bill can be paid in installments. |
    | `finance_charges` | String (JSON) | Charges of the bill: late payment interest and fees, IOF and others (JSON array of objects). |
    | `payments` | String (JSON) | Payments made against the bill (JSON array of objects). |
    | `created_at` | Datetime | When the bill was first collected by Pluggy. |
    | `updated_at` | Datetime | When the bill data was last updated. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Investments">
    Investment positions of each item: funds, fixed income, stocks, treasury bonds and others.

    Table: `investments` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the investment in Pluggy. |
    | `item_id` | String | Item (connection) the investment belongs to; joins with items.id. |
    | `type` | String | Asset class: COE, EQUITY, ETF, FIXED\_INCOME, MUTUAL\_FUND, SECURITY or OTHER. |
    | `subtype` | String | Instrument within the asset class (e.g. CDB, LCI, LCA, TREASURY, STOCK, REAL\_ESTATE\_FUND). |
    | `name` | String | Name of the investment at the institution. |
    | `number` | String | Reference number of the holder's asset. |
    | `code` | String | Code of the investment (for a mutual fund, its CNPJ; for a stock, its ticker). |
    | `isin` | String | 12-character ISIN of the asset. |
    | `status` | String | Lifecycle status: ACTIVE, PENDING or TOTAL\_WITHDRAWAL. |
    | `balance` | Number | Current net balance of the investment. |
    | `amount` | Number | Gross amount of the investment. |
    | `amount_original` | Number | Amount originally invested. |
    | `amount_profit` | Number | Profit or loss to date. |
    | `amount_withdrawal` | Number | Amount available to withdraw. |
    | `value` | Number | Value of one quota at the quota date. |
    | `quantity` | Number | Number of quotas held. |
    | `taxes` | Number | Income tax applied to the investment. |
    | `taxes2` | Number | Financial tax (IOF) applied to the investment. |
    | `currency_code` | String | ISO currency code of the amounts. |
    | `date` | Datetime | Date of the quota value. |
    | `due_date` | Datetime | Maturity date. |
    | `issue_date` | Datetime | Date the investment was issued. |
    | `purchase_date` | Datetime | Date the investment was purchased. |
    | `grace_period_date` | Datetime | End of the grace period (fixed income only). |
    | `issuer` | String | Entity that issued the investment. |
    | `issuer_cnpj` | String | CNPJ of the issuer. |
    | `owner` | String | Owner or beneficiary of the investment. |
    | `last_month_rate` | Number | Performance rate over the last month. |
    | `last_twelve_months_rate` | Number | Performance rate over the last 12 months. |
    | `annual_rate` | Number | Performance rate over the last year. |
    | `rate` | Number | Fixed rate percentage of the investment. |
    | `rate_type` | String | Type of the fixed rate (indexer, e.g. CDI, IPCA). |
    | `fixed_annual_rate` | Number | Fixed income annual rate. |
    | `rate_periodicity` | String | Periodicity of the remuneration rate (DAILY, MONTHLY, SEMESTERLY, YEARLY). |
    | `indexer_additional_info` | String | Description of a non-standard indexer. |
    | `tax_exempt` | Boolean | Whether the product is tax-exempt (LCI, LCA, CRI, CRA, incentivized debentures). |
    | `price_factor` | Number | B3 lot/price conversion factor (variable income). |
    | `institution` | String (JSON) | Financial institution holding the investment: name and number (JSON object). |
    | `metadata` | String (JSON) | Additional details, such as security portability (JSON object). |
    | `debtor` | String (JSON) | Underlying debtor of receivables-backed paper, CRI and CRA (JSON object). |
    | `coupon_payment` | String (JSON) | Coupon payment schedule of coupon-bearing bonds (JSON object). |
    | `created_at` | Datetime | When the investment was first collected by Pluggy. |
    | `updated_at` | Datetime | When the investment data was last updated. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Investment Transactions">
    Movements of each investment: purchases, redemptions, taxes, interest and amortizations.

    Table: `investment_transactions` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the investment transaction in Pluggy. |
    | `investment_id` | String | Investment of the movement; joins with investments.id. |
    | `item_id` | String | Item (connection) of the investment; joins with items.id. |
    | `type` | String | Operation: BUY, SELL, TAX, TRANSFER, INTEREST or AMORTIZATION. |
    | `movement_type` | String | Cash-flow direction for the holder: CREDIT or DEBIT. |
    | `date` | Datetime | Date of the operation. |
    | `trade_date` | Datetime | Date the operation was confirmed. |
    | `description` | String | Description of the operation as reported by the institution. |
    | `quantity` | Number | Quantity of quotas of the operation. |
    | `value` | Number | Quota value on the operation date. |
    | `amount` | Number | Gross amount of the operation. |
    | `net_amount` | Number | Amount of the operation after expenses and taxes. |
    | `agreed_rate` | Number | Agreed rate of treasury applications. |
    | `indexer_percentage` | Number | Percentage of the indexer agreed at contracting (e.g. 110 for 110% of CDI). |
    | `price_factor` | Number | B3 lot/price conversion factor (variable income). |
    | `brokerage_number` | String | Brokerage note number of the operation. |
    | `expenses` | String (JSON) | Fees and taxes of the operation: brokerage, custody, IR, IOF and others (JSON object). |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Loans">
    Loans, financings, invoice financings and overdraft contracts of each item.

    Table: `loans` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the loan in Pluggy. |
    | `item_id` | String | Item (connection) the loan belongs to; joins with items.id. |
    | `contract_number` | String | Contract number given by the institution. |
    | `ipoc_code` | String | Standard contract number (IPOC) of the credit operation. |
    | `product_name` | String | Name of the credit product disclosed to the customer. |
    | `kind` | String | Credit operation family: LOAN, FINANCING, INVOICE\_FINANCING or UNARRANGED\_ACCOUNT\_OVERDRAFT. |
    | `type` | String | Loan subtype as defined by Open Finance Brasil. |
    | `date` | Datetime | When the loan data was collected. |
    | `contract_date` | Datetime | When the loan was contracted. |
    | `disbursement_dates` | Array of strings | Dates the contracted amount was disbursed (YYYY-MM-DD). |
    | `settlement_date` | Datetime | Settlement date of the loan. |
    | `due_date` | Datetime | Final due date of the loan. |
    | `first_installment_due_date` | Datetime | Due date of the first installment. |
    | `contract_amount` | Number | Contracted amount. |
    | `currency_code` | String | ISO currency code of the loan. |
    | `installment_periodicity` | String | Regular frequency of the installments (MONTHLY, QUARTERLY...). |
    | `installment_periodicity_additional_info` | String | Details of the installment frequency when it is OTHERS. |
    | `cet` | Number | Total effective cost (CET), as an annual percentage rate. |
    | `amortization_scheduled` | String | Amortization system: SAC, PRICE, SAM, WITHOUT\_AMORTIZATION\_SYSTEM or OTHERS. |
    | `amortization_scheduled_additional_info` | String | Details of the amortization system when it is OTHERS. |
    | `cnpj_consignee` | String | CNPJ of the consignor, for payroll-deducted loans. |
    | `interest_rates` | String (JSON) | Interest rates of the contract (JSON array of objects). |
    | `contracted_fees` | String (JSON) | Fees agreed in the contract (JSON array of objects). |
    | `contracted_finance_charges` | String (JSON) | Finance charges agreed in the contract (JSON array of objects). |
    | `warranties` | String (JSON) | Warranties of the contract (JSON array of objects). |
    | `installments` | String (JSON) | Installment terms: totals, paid, due and overdue installments, balloon payments (JSON object). |
    | `payments` | String (JSON) | Payments made on the contract (JSON). |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Identities">
    Registration data of the holder of each item: name, documents, contacts, addresses and, for businesses, partners. Items whose institution does not provide it have no row.

    Table: `identities` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the identity in Pluggy. |
    | `item_id` | String | Item (connection) of the identity; joins with items.id. |
    | `full_name` | String | Name of the account holder. |
    | `company_name` | String | Business name, for business connections. |
    | `social_name` | String | Social name of the person, if any (individuals only). |
    | `document` | String | Primary document of the holder (CPF or CNPJ). |
    | `document_type` | String | Type of the primary document. |
    | `tax_number` | String | Tax ID (CNPJ) of the business account. |
    | `birth_date` | Datetime | Date of birth (individuals). |
    | `incorporation_date` | Datetime | Date the business was incorporated (businesses). |
    | `job_title` | String | Profession or job of the holder. |
    | `investor_profile` | String | Investor profile: Conservative, Moderate or Aggressive. |
    | `sex` | String | Sex of the person (individuals only). |
    | `establishment_code` | String | Establishment code (payment account connectors only). |
    | `establishment_name` | String | Establishment name (payment account connectors only). |
    | `phone_numbers` | String (JSON) | Phone numbers of the holder (JSON array of objects). |
    | `emails` | String (JSON) | E-mail addresses of the holder (JSON array of objects). |
    | `addresses` | String (JSON) | Addresses of the holder (JSON array of objects). |
    | `relations` | String (JSON) | People related to the account (JSON array of objects). |
    | `qualifications` | String (JSON) | Since when the holder is a client and the products and income declared to the institution (JSON object). |
    | `financial_relationships` | String (JSON) | Financial relationship of the holder with the institution: accounts, representatives, start date (JSON object). |
    | `marital_status` | String (JSON) | Marital status of the person (JSON). |
    | `nationality` | String (JSON) | Nationality of the person (JSON). |
    | `other_documents` | String (JSON) | Other identification documents of the person (JSON array of objects). |
    | `passport` | String (JSON) | Passport of the person (JSON object). |
    | `parties` | String (JSON) | Partners and administrators of the business (JSON array of objects). |
    | `business_other_documents` | String (JSON) | Additional documents of businesses headquartered abroad (JSON array of objects). |
    | `companies_cnpj` | Array of strings | CNPJs of the institutions responsible for the customer registration. |
    | `created_at` | Datetime | When the identity was first collected by Pluggy. |
    | `updated_at` | Datetime | When the identity data was last updated. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Consents">
    Consents the user gave for each item: authorized products and permissions, and when they expire or were revoked.

    Table: `consents` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Unique identifier of the consent in Pluggy. |
    | `item_id` | String | Item (connection) of the consent; joins with items.id. |
    | `products` | Array of strings | Products the consent allows Pluggy to collect. |
    | `open_finance_permissions_granted` | Array of strings | Open Finance permissions granted by the user. |
    | `created_at` | Datetime | When the consent was given. |
    | `expires_at` | Datetime | When the consent expires (null when it does not expire). |
    | `revoked_at` | Datetime | When the consent was revoked, if it was. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Categories">
    Transaction categories of Pluggy's categorization, with their parents and Portuguese names.

    Table: `categories` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | String | Identifier of the category; joins with transactions.category\_id. |
    | `description` | String | Name of the category (English). |
    | `description_translated` | String | Name of the category in Portuguese. |
    | `parent_id` | String | Identifier of the parent category. |
    | `parent_description` | String | Name of the parent category. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>

  <Accordion title="Connectors">
    Institutions Pluggy connects to, sandbox ones included, with the products each one supports.

    Table: `connectors` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Identifier of the connector; joins with items.connector\_id. |
    | `name` | String | Name of the institution. |
    | `type` | String | Type of institution: PERSONAL\_BANK, BUSINESS\_BANK, INVESTMENT, INVOICE, TELECOMMUNICATION or OTHER. |
    | `country` | String | Country of the institution. |
    | `institution_url` | String | Website of the institution. |
    | `image_url` | String | Logo of the institution hosted by Pluggy. |
    | `primary_color` | String | Primary brand color of the institution. |
    | `is_open_finance` | Boolean | Whether the connector uses the regulated Open Finance APIs. |
    | `is_sandbox` | Boolean | Whether it is a sandbox connector for testing rather than a real institution. |
    | `has_mfa` | Boolean | Whether connecting requires a second authentication factor. |
    | `oauth` | Boolean | Whether connecting goes through the institution's OAuth flow. |
    | `oauth_url` | String | URL of the institution's OAuth flow. |
    | `reset_password_url` | String | URL at the institution to reset the password. |
    | `products` | Array of strings | Products the connector supports. |
    | `product_coverage` | Array of strings | Sub-products the institution serves, in Open Finance vocabulary (e.g. INVESTMENTS:TREASURE\_TITLES). |
    | `supports_payment_initiation` | Boolean | Whether the connector supports payment initiation. |
    | `supports_scheduled_payments` | Boolean | Whether the connector supports scheduled payments. |
    | `supports_smart_transfers` | Boolean | Whether the connector supports smart transfers. |
    | `supports_boleto_management` | Boolean | Whether the connector supports boleto management. |
    | `supports_automatic_pix` | Boolean | Whether the connector supports automatic Pix. |
    | `credentials` | String (JSON) | Fields a user fills to connect (definitions only, no values) (JSON array of objects). |
    | `health` | String (JSON) | Health of the connector: status, stage and open incidents (JSON object). |
    | `created_at` | Datetime | When the connector was created. |
    | `updated_at` | Datetime | When the connector was last modified. |
    | `additional_fields` | String (JSON) | Fields Pluggy returned that have no column of their own (JSON object). |
  </Accordion>
</AccordionGroup>

## How transactions are kept up to date

Pluggy does not offer a "changed since" filter for transactions, and a transaction can change long after its date: a credit card purchase stays pending until its bill closes, installments and scheduled payments are dated in the future, and categories can be updated. On every incremental sync the connector reads, for each account:

1. every transaction Pluggy received since the previous sync, whatever its date;
2. every transaction dated within the **Transactions lookback (days)** window, to update status, category and description;
3. every transaction that was pending on an earlier sync and is now older than the window, until Pluggy reports it as posted or removes it.

A transaction that was dated inside the window (or pending) on the previous sync and is not returned this time is asked for by its id, because Pluggy can update a transaction in place and move its date. If Pluggy still has it, the row is simply updated, with its new date. Only if Pluggy no longer has it is it sent once more with `removed_at` filled in, so its row in your table is marked as removed instead of staying as a duplicate. If an account returns no transactions at all while earlier syncs saw recent or pending ones (which is what a lost consent or permission looks like), nothing is marked as removed and the sync log tells you which connection to check.

Each account keeps its own sync point, which only moves forward when the whole sync completes.

## Data Quality Considerations

* **Use `removed_at IS NULL` for totals.** When an institution restates a transaction (its date, amount or description changes, mostly on credit cards around the bill closing), Pluggy deletes it and creates a new one with a new `id`; a cancelled scheduled payment is deleted too. The connector keeps the old row and fills in `removed_at` with the time it noticed the removal. A removed row keeps only `id`, `account_id`, `item_id`, `date`, `updated_at` and `removed_at`, so it also drops out of sums by itself. Filter `removed_at IS NULL` to see only the transactions that exist in Pluggy today. The same filter also hides the rows that hold only `id`, `date` and `removed_at` with every other column empty: they can appear after a full sync of Transactions, when the next incremental sync marks a transaction that the full sync had already left out:

```sql theme={null}
SELECT *
FROM transactions
WHERE removed_at IS NULL
```

* **Removals are detected within the lookback window.** A transaction removed after it left the **Transactions lookback (days)** window (and that was not pending) cannot be noticed by an incremental sync. A full sync of Transactions rebuilds the table from what Pluggy holds; read the warning below first.

* **`provider_id` is the institution's own transaction id.** It does not change when Pluggy recreates a transaction, but Pluggy only returns it for Open Finance connections; for direct connections it is always empty, and transactions can only be matched by `date`, `amount` and `description`.

* **Reconnecting creates a new item.** When a user revokes a consent and connects the same bank again, Pluggy creates a new item, with new account and transaction ids, and does not deduplicate it against the old one. The old item's transactions stay in your table, so the same purchase can appear under two `account_id` values. Remove the old item from **Item IDs** (or delete it in Pluggy) and reconcile with `provider_id` (Open Finance) or with `date`, `amount` and `description`.

* **Expired or revoked consents return no data.** When the consent of a connection expires or is revoked, Pluggy keeps the item but returns no accounts, transactions or other data for it until the user connects again. The sync log lists those connections, and tables synced as FULL\_TABLE lose that connection's rows on the next sync; Transactions synced incrementally keep what was already loaded. The sync stops instead, before writing any table and with the list of connections to reconnect, when the consent of every connection expired or was revoked, and when Transactions is set to be fully replaced while a connection is expired.

<Warning>A full sync of Transactions replaces the table with what Pluggy holds at that moment. Pluggy keeps transactions from about 12 months before each connection was created, and returns nothing for deleted connections: their transactions, and the rows already marked with `removed_at`, are removed from the table.</Warning>

* **Connections that Pluggy could not refresh.** Items with status `LOGIN_ERROR`, `OUTDATED` or `WAITING_USER_INPUT` keep serving the data of their last successful sync until the user updates the connection, so the sync goes on (even when every connection is in that state). The sync log lists them, and the `items` table shows their status and error.

* **Availability depends on the institution and your Pluggy plan.** Investments, loans, identity and credit card bills exist only for institutions that provide them. Transaction categories and merchant data require those features in your Pluggy subscription; without them the columns are empty.

* **Amounts and signs.** Amounts keep the precision Pluggy returns. On credit cards, a positive amount is a charge and a negative amount is a payment or credit; on bank accounts, `type` tells inflows (`CREDIT`) from outflows (`DEBIT`).

* **Errors stop the sync.** If Pluggy keeps failing, returns an unexpected answer or a list changes while it is being read, the sync stops with a message instead of loading incomplete data; the next sync tries again. Rate limits are handled automatically by waiting.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.