# SCR — Credit Information System

The **SCR** (_Sistema de Informações de Crédito_) is the Banco Central do Brasil's official registry of credit operations. Every financial institution in the country reports to it: loans, financing, limits, guarantees and co-obligations. It is the source itself, not a score inferred from it.

Pluggy exposes the SCR behind a connected Open Finance item. The item supplies the CPF or CNPJ and stands as the evidence of the account holder's consent.

<Callout variant="info" title="Available on request">
  The SCR is available on request. Talk to us to have it enabled on your
  subscription — without it the endpoint returns `SCR_FEATURE_NOT_ENABLED`.
</Callout>

<Callout variant="warning" title="Consent is your responsibility">
  Any SCR consultation depends on prior authorization from the credit operations
  holder. Your institution is responsible for requesting that authorization, and
  for meeting the consultation prerequisites, clarification messages, and the
  registration and storage of authorizations set out in current regulation — see
  [Resolução CMN n°
  5.037](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=RESOLU%C3%87%C3%83O%20CMN&numero=5037).
</Callout>

## Requirements

Before the first call:

1. The **SCR feature** enabled on your subscription.
2. A connected **Open Finance** item — a [sandbox one](#testing-in-the-sandbox) works too. Direct connectors are not eligible.
3. That item's **CPF or CNPJ** known to us — it is what we query Bacen with.

An item that fails either of the last two returns `SCR_ITEM_NOT_SUPPORTED`.

## Consult the SCR

```
GET /items/{id}/scr
```

| Parameter | In    | Description                                       |
| --------- | ----- | ------------------------------------------------- |
| `id`      | path  | The item whose account holder you want to consult |
| `from`    | query | First base date, as `YYYYMM`. Optional            |
| `to`      | query | Last base date, as `YYYYMM`. Optional             |

```bash
curl --request GET \
  --url 'https://api.pluggy.ai/items/d0e8448e-0156-4b4a-ae6c-3e2a6d9bff5c/scr?from=202604&to=202607' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

Full parameter and schema detail lives in the [API reference](/reference/scr/items-retrieve-scr).

## Base dates are months, and they lag

The SCR does not work in days. Bacen consolidates one **base date** (_data-base_) per month, and each one only becomes complete a few months later — institutions are still delivering their reports in the meantime.

Two consequences worth designing around:

- **Asking for the current month returns nothing.** Bacen has not closed it yet.
- **When you omit `from` and `to`**, Pluggy consults the last 4 base dates, ending 2 months back from today. In September 2026 that is `202604` to `202607`.

If you send only one bound, the window anchors on it: `?to=202501` returns `202410` through `202501`.

Each base date carries `docProc` and `volProc` — the percentage of expected documents and volume already incorporated. A recent base date with low coverage is a partial picture, not an empty one.

## Response

The response is Bacen's own payload, forwarded unchanged. Field names, codes and structure are the SCR's, so a value you read here is the same value an institution reads at the source.

```json
{
  "dtbConsult": "202604 a 202607",
  "cdCli": "11222333",
  "tpCli": "2",
  "lsDtb": [
    {
      "dtb": 202607,
      "docProc": "99.8",
      "volProc": "99.9",
      "qtdIfs": 4,
      "qtdCongFinc": 3,
      "dtbIniRel": "201803",
      "coobAss": 0,
      "coobRec": 0,
      "lsOp": [
        {
          "mod": "0203",
          "oriRec": "0101",
          "indx": "01",
          "varCamb": "00",
          "resVenc": { "v20": 12500.0, "v40": 12500.0, "v110": 37500.0 },
          "lsGar": [{ "tp": "0501", "qtd": 1 }]
        }
      ]
    }
  ]
}
```

### Top level

| Field                         | Type   | Description                                                                                   |
| ----------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `dtbConsult`                  | string | The base dates consulted                                                                      |
| `cdCli`                       | string | The consulted document: the CPF for an individual, or the **8-digit CNPJ root** for a company |
| `tpCli`                       | string | `"1"` for an individual, `"2"` for a legal entity                                             |
| `lsDtb`                       | array  | One entry per consulted base date. A base date with no data is still listed                   |
| `listaDeMensagensDeValidacao` | array  | Validation messages raised by Bacen for the request, each with a `codigo` and a `mensagem`    |

### Inside a base date (`lsDtb[]`)

| Field         | Type   | Description                                                                                                         |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `dtb`         | number | The base date, as `YYYYMM`. Numeric, not a string                                                                   |
| `msg`         | string | Bacen's message for this base date, when it has one                                                                 |
| `docProc`     | string | Percentage of the expected 3040 documents already incorporated by Bacen, excluding exempted institutions            |
| `volProc`     | string | Percentage of the expected operation volume already accepted for the base date                                      |
| `qtdIfs`      | number | Number of financial institutions where the holder has operations                                                    |
| `qtdCongFinc` | number | Number of financial conglomerates. Compare against `qtdIfs` to tell real counterparty diversification from apparent |
| `dtbIniRel`   | string | Start of the holder's relationship with the national financial system                                               |
| `coobAss`     | number | Co-obligation assumed by the holder in credit assignments, in BRL                                                   |
| `coobRec`     | number | Co-obligation received in credit assignments, in BRL                                                                |
| `lsOp`        | array  | Operation groups                                                                                                    |

### Inside an operation group (`lsOp[]`)

The SCR does not return contracts one by one. Operations are **aggregated** by the combination of modality, source of funds, index and exchange variation, so one entry can represent several contracts of the same nature.

| Field      | Type   | Description                                                                                    |
| ---------- | ------ | ---------------------------------------------------------------------------------------------- |
| `mod`      | string | Modality code — what kind of credit it is                                                      |
| `oriRec`   | string | Source-of-funds code                                                                           |
| `indx`     | string | Reference rate or index code                                                                   |
| `varCamb`  | string | Exchange rate variation code                                                                   |
| `subJDisc` | string | Present when the operation is under dispute: `"D"` disagreement, `"J"` sub judice, `"JD"` both |
| `resVenc`  | object | Balances split by maturity vertex — see below                                                  |
| `lsGar`    | array  | Guarantees backing the group, by type (`tp`) and count (`qtd`)                                 |
| `lsInfAd`  | array  | Complementary information reported for the group, by type (`tp`), code (`cd`) and count (`qtd`) |

The codes behind `mod`, `oriRec`, `indx`, `varCamb` and `tp` are Bacen's own. Their meaning is published in the **DOC3040** reference — read them there rather than inferring them.

### Maturity vertices (`resVenc`)

`resVenc` distributes the group's balance across 30 vertices, in BRL. Each key is a Bacen maturity code — `v20`, `v40`, `v60`, `v80`, `v110`, `v120`, `v130`, `v140`, `v150`, `v160`, `v165`, `v170`, `v175`, `v180`, `v190`, `v199`, `v205`, `v210`, `v220`, `v230`, `v240`, `v245`, `v250`, `v255`, `v260`, `v270`, `v280`, `v290`, `v310` and `v320` — and only the vertices that carry a value are present. They fall into three families:

| Family                 | What it means                                                                                                                                                                                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Not yet due**        | Payments whose date has not arrived. The boundary is generous — a payment up to **14 days** late still counts here, so short operational delays are not read as default. Measures commitment, not trouble: what matters is the shape of the curve over time                                         |
| **Overdue**            | Payments more than 14 days late, graded into progressively older buckets. Two debts of the same value, one 20 days late and one 200, are opposite situations. Read the **migration between buckets** month over month: value moving down the ladder is recovery, moving up is a default in progress |
| **Special categories** | A few vertices are not time windows at all; they represent states or commitments that do not fit the maturity ruler                                                                                                                                                                                 |

The exact window behind each individual code is defined in the DOC3040 layout, in its maturity code table (_Código de Vencimento_). Read it there: the number in the key is a code, not a count of days, so do not infer a window from it. Without that table you can still add up total exposure and split not-yet-due from overdue balances; building an aging curve needs the code-by-code windows.

## Testing in the sandbox

You can integrate the SCR without a real account. Create an item with the
**Sandbox Open Finance** connector (`600`) using one of the
[sandbox CPFs](/docs/guides/sandbox#7--open-finance-flow), then call `GET /items/{id}/scr` as usual.

A sandbox item returns a **synthetic** payload with the same schema as production. `cdCli` is
the item's document, `tpCli` follows it, and `lsDtb` has one entry per base date in the
requested window — the default window applies when `from` and `to` are omitted. Each base date
carries a few operation groups, with guarantees and balances in `resVenc`, and is marked with
`msg: "Synthetic data - Pluggy sandbox"` so a synthetic payload can never be mistaken for a
real one.

<Callout variant="info" title="Deterministic, not billed">
  The sandbox response is generated, not consulted: no request reaches Bacen and the call is
  not charged. The same item and window always return the same values, so you can assert
  against them in automated tests.
</Callout>

The checks are the ones you will meet in production. The SCR feature must be enabled on your
subscription (`SCR_FEATURE_NOT_ENABLED` otherwise), the item must be Open Finance — the Pluggy
Bank sandbox connectors return `SCR_ITEM_NOT_SUPPORTED` — and an inverted range returns
`SCR_INVALID_REQUEST`. One sandbox-only limit: a window longer than **60 base dates** is also
rejected with `SCR_INVALID_REQUEST`.

## Errors

| Status | Code                      | What it means                                                                                               |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| 400    | `SCR_INVALID_REQUEST`     | The base date range was rejected. Check that `from` and `to` are `YYYYMM` and that `from` is not after `to`. The error message may refer to them as `databaseIni` and `databaseFim` |
| 403    | `SCR_FEATURE_NOT_ENABLED` | The SCR is not enabled on your subscription                                                                 |
| 404    | `ITEM_NOT_FOUND`          | No such item, or its authorization has been revoked                                                         |
| 422    | `SCR_ITEM_NOT_SUPPORTED`  | The item is not an Open Finance connection, or its CPF/CNPJ is missing or malformed                         |
| 500    | `SCR_FETCH_ERROR`         | We could not complete the consultation                                                                      |
| 502    | `SCR_SERVICE_UNAVAILABLE` | Bacen's SCR service is unavailable. Retry later                                                             |

A `502` carries a `correlationId` under `data`. Quote it when you report the failure to us — it is what lets us trace the exact consultation.

```json
{
  "code": 502,
  "codeDescription": "SCR_SERVICE_UNAVAILABLE",
  "message": "Bacen's SCR service is temporarily unavailable. Please try again later.",
  "data": { "correlationId": "8047f6e9-bb9e-4b04-8515-e2210dc4c544" }
}
```

<Callout variant="warning" title="Design for outages">
  Bacen's SCR service has extended outages. Design for `502` — retry with
  backoff, and do not treat an unavailable consultation as an absence of credit
  history.
</Callout>