# Item resources

When a product comes back empty, there are two very different reasons behind it, and they lead to
opposite next steps:

- **the institution never shared it** — the consent does not cover it, the user still has to
  authorise it, or the bank reports it as unavailable. The end user can fix this at their bank;
- **we do not hold the record** — the consent covers it, but the sync has not brought it in. That
  is ours to look at.

`GET /items/{id}/resources` answers the first one. It lists the resources the financial institution
declared for this item's consent, exactly as the institution reported them — nothing inferred,
nothing merged with our own data.

<Callout variant="info" title="Open Finance only">
Only Open Finance institutions report a resource list. An item on a direct connector returns an
empty page rather than an error, so it is safe to call for any item.
</Callout>

## The response

The endpoint is paged (`page`, `pageSize`, default 500 per page):

```json
{
  "page": 1,
  "total": 3,
  "totalPages": 1,
  "results": [
    { "resourceId": "92792126-fa1e-4e1c-a2b2-5b7b0d4a0b11", "type": "ACCOUNT", "status": "AVAILABLE" },
    { "resourceId": "0d1e2f34-55aa-4b0c-9f3d-77c1a0e2b345", "type": "CREDIT_CARD_ACCOUNT", "status": "PENDING_AUTHORISATION" },
    { "resourceId": "5f6a7b89-1122-4c33-8d44-99e0f1a2b3c4", "type": "FUND", "status": "UNAVAILABLE" }
  ]
}
```

Each entry has three fields:

| Field | What it is |
| :-- | :-- |
| `resourceId` | The **institution's** identifier for the resource. It matches the `providerId` of the corresponding account, credit card, loan or investment — not a Pluggy id. |
| `type` | The Open Finance resource type, as declared. |
| `status` | What the institution reports about this resource. |

### Filtering by status

Pass `status` to get only the resources in one state, for example
`GET /items/{id}/resources?status=PENDING_AUTHORISATION`. Accepted values: `AVAILABLE`,
`PENDING_AUTHORISATION`, `UNAVAILABLE`, `TEMPORARILY_UNAVAILABLE`. Paging works the same way, and
`total` counts only the matching resources.

## Status

| Status | What it means | Who acts |
| :-- | :-- | :-- |
| `AVAILABLE` | The institution shares this resource under the consent. | Nobody — if data is still missing, it is a collection question, not a consent one. |
| `PENDING_AUTHORISATION` | The consent reaches this resource, but the user has not authorised it yet at their institution. | The end user, in their bank's app. |
| `UNAVAILABLE` | The institution reports it as not available. | The end user, or nobody — the institution decides. |
| `TEMPORARILY_UNAVAILABLE` | The institution reports it as unavailable for now. | Retry later. |

`PENDING_AUTHORISATION` keeps Open Finance's British spelling. It is the regulation's, not a typo.

## Types

| Type | Product it belongs to |
| :-- | :-- |
| `ACCOUNT` | Accounts |
| `CREDIT_CARD_ACCOUNT` | Credit cards |
| `LOAN`, `FINANCING`, `INVOICE_FINANCING`, `UNARRANGED_ACCOUNT_OVERDRAFT` | Loans — the same four families the Loan's [`kind`](/docs/products/loans) uses |
| `BANK_FIXED_INCOME`, `CREDIT_FIXED_INCOME`, `VARIABLE_INCOME`, `TREASURE_TITLE`, `FUND` | Investments |

## How fresh the list is

The list is a snapshot from the last execution that actually reached the institution, so it can be
older than the item itself. The Item's **`resourcesCollectedAt`** says when it was taken.

That field is also what makes an empty list readable:

- `resourcesCollectedAt` set, empty list → the institution shared **nothing** under this consent;
- `resourcesCollectedAt` `null` → the list has **never been obtained**. An empty response says
  nothing about the consent.

## Resources pending authorization

The Item's **`hasResourcesPendingAuthorization`** tells you whether anything in this list is waiting
on the user, without paging through it. It is read from this same list, so the two always agree.

| Value | What it means |
| :-- | :-- |
| `true` | The institution declares at least one resource `PENDING_AUTHORISATION`. |
| `false` | The list was read and nothing in it is pending. |
| `null` | The list has not been read yet (`resourcesCollectedAt` is `null`), for example while the item's first execution is still running. Always `null` for connectors other than Open Finance. |

<Callout variant="info" title="When to read it">
The list is stored before the `item/created` and `item/updated` webhooks are sent, so reading the
Item when the webhook arrives gives you the value for that execution. Read it earlier, while the
first execution is still running, and it is `null`.
</Callout>

A typical way to handle it:

1. On `item/created` or `item/updated`, call `GET /items/{id}`.
2. If `hasResourcesPendingAuthorization` is `true`, call
   `GET /items/{id}/resources?status=PENDING_AUTHORISATION` to see which resources are waiting.
3. Tell your user what they still have to authorise in their bank's app — `type` says which product
   each resource belongs to. For business accounts this is often the approval of a second signer.
4. Once the user authorises them, the next update of the item brings their data in, and the
   following `item/updated` arrives with `hasResourcesPendingAuthorization` set to `false`.

## What it does not answer

Whether Pluggy holds the matching record is a separate question. A resource can be `AVAILABLE` and
still have no data on our side, and the reverse also happens — we keep records across executions,
so data can be there from an earlier sync of a resource the institution no longer declares.

For that side, use the product endpoints (`/accounts`, `/investments`, `/loans`) and the Item's
`statusDetail`, which reports per-product collection outcomes. See
[Item](/docs/connections/item) and [Warnings & Status Codes](/docs/connections/warnings-status-codes).

## A worked triage

A customer reports that an item connected to an Open Finance bank returns no investments.

1. `GET /items/{id}` — is `status` `UPDATED`? What does `statusDetail.investments` say? If it
   reports an error, the problem is collection and stops here. `INV_002` warnings list the
   investments still pending authorization at the bank (up to 100), and
   `hasResourcesPendingAuthorization: true` says some resource, in any product, is waiting on the
   user; step 2 has the full list.
2. `GET /items/{id}/resources` — are there investment types in the list at all? Add
   `?status=PENDING_AUTHORISATION` to see only the ones waiting on the user.
   - none, and `resourcesCollectedAt` is set → the institution does not share investments under
     this consent. Nothing to fix on our side;
   - present as `PENDING_AUTHORISATION` → the user has to authorise that resource at their bank;
   - present as `AVAILABLE` → the consent covers it and we should have it. That is a collection
     issue worth [reporting](/docs/connections/reporting-issues), with the item id and the
     `resourceId` in hand.

Per-connector coverage tables answer a different question — what a connector supports in general —
and live in [Connectors coverage](/docs/connections/connectors-coverage). This endpoint answers it
for **one** consent, as the institution declared it today.