# Bank Lookup (FDIC) (`bank.lookup`)

Look up an FDIC-insured US bank by certificate number or name: status, charter, regulator, branches, assets, deposits and holding company.

Docs: https://primaryapi.com/docs/api-reference/bank/lookup

- Endpoint: `POST https://api.primaryapi.com/v1/run/bank.lookup`
- Category: Knowledge & Data · Platform: `bank` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=bank.lookup`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `cert` | string | no |  | pattern: ^\d{1,6}$ | FDIC certificate number (1-6 digits), for example "3511". Wins over `name` when both are given. |
| `name` | string | no |  | max 100 chars | Bank name to search, for example "Wells Fargo" (fuzzy: matches the leading letters of each word). |
| `state` | string | no |  | pattern: ^[A-Za-z]{2}$ | Two-letter US state or territory code that narrows a name search, for example "SD". |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `fdicCert` | integer | FDIC certificate number (CERT) |
| `name` | string | Legal name of the institution |
| `status` | enum | inactive = closed, merged or no longer FDIC-insured |
| `active` | boolean |  |
| `endDate` | string \| null | Date the institution ended (closed or merged), YYYY-MM-DD; null while active |
| `address` | string \| null |  |
| `city` | string \| null |  |
| `state` | string \| null | Two-letter state of the main office |
| `stateName` | string \| null |  |
| `zip` | string \| null |  |
| `county` | string \| null |  |
| `website` | string \| null |  |
| `charterClass` | string \| null | Charter class, decoded from BKCLASS |
| `charterClassCode` | string \| null | Raw BKCLASS code (N, NM, SM, SB, SA, OI) |
| `regulator` | string \| null | Primary federal regulator (OCC, FDIC or FRS) |
| `branchCount` | integer \| null | Number of offices (FDIC omits it for inactive institutions) |
| `totalAssetsUsd` | number \| null | Total assets in US dollars at reportDate (FDIC reports thousands) |
| `totalDepositsUsd` | number \| null | Total deposits in US dollars at reportDate |
| `netIncomeUsd` | number \| null | Year-to-date net income in US dollars at reportDate |
| `holdingCompany` | string \| null | Regulatory high holder (top holding company) name |
| `establishedDate` | string \| null | YYYY-MM-DD |
| `insuredSince` | string \| null | Date FDIC insurance began, YYYY-MM-DD |
| `reportDate` | string \| null | Date of the latest call report behind the financial figures, YYYY-MM-DD |
| `lei` | string \| null |  |
| `fedRssdId` | string \| null | Federal Reserve RSSD id |
| `nameSearch` | string \| null | The name searched (null for a certificate lookup) |
| `matchCount` | integer | Institutions matching the query (1 for a certificate lookup) |
| `otherMatches` | object[] | Further name-search matches, active institutions first |
| `otherMatches[].fdicCert` | integer |  |
| `otherMatches[].name` | string |  |
| `otherMatches[].active` | boolean |  |
| `otherMatches[].city` | string \| null |  |
| `otherMatches[].state` | string \| null |  |
| `coverage` | string |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/bank.lookup" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cert":"3511"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "fdicCert": 0,
      "name": "string",
      "status": "active",
      "active": true,
      "endDate": "string",
      "address": "string",
      "city": "string",
      "state": "string",
      "stateName": "string",
      "zip": "string",
      "county": "string",
      "website": "string",
      "charterClass": "string",
      "charterClassCode": "string",
      "regulator": "string",
      "branchCount": 0,
      "totalAssetsUsd": 0,
      "totalDepositsUsd": 0,
      "netIncomeUsd": 0,
      "holdingCompany": "string",
      "establishedDate": "string",
      "insuredSince": "string",
      "reportDate": "string",
      "lei": "string",
      "fedRssdId": "string",
      "nameSearch": "string",
      "matchCount": 0,
      "otherMatches": [
        {
          "fdicCert": 0,
          "name": "string",
          "active": true,
          "city": "string",
          "state": "string"
        }
      ],
      "coverage": "string"
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=bank.lookup`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Free FDIC BankFind API. Amounts are converted from FDIC thousands to dollars. Credit unions are not covered.

