# FDIC Bank Branch Finder: Locations and Change Monitoring (`ledgerstar/bank-branch-finder`) Actor

Find FDIC bank branches by state or bank certificate. Export office addresses, coordinates and source-linked records. Monitor unseen branch versions on a schedule with clear scan limits and per-result pricing.

- **URL**: https://apify.com/ledgerstar/bank-branch-finder.md
- **Developed by:** [Ledger Star](https://apify.com/ledgerstar) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.00 / 1,000 branch results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## FDIC Bank Branch Finder: Locations and Change Monitoring

Refresh bank territory lists each week with FDIC Bank Branch Finder, built for field-service teams and analysts who need usable branch addresses, stable identifiers and traceable source data.

![bank-branch-finder by Ledgerstar](https://raw.githubusercontent.com/ledgerstar/assets/main/bank-branch-finder/cover-v1.png)

### What you get

- Branch locations from the official FDIC locations dataset, filtered by state or bank certificate, with business addresses and available coordinates.
- A repeatable snapshot or optional monitoring mode that returns previously unseen versions of branches within your selected scope.
- Downloadable records and a run summary showing delivered results, source rows examined, duplicates and whether the scan finished.

### What data you get

Each successful row describes one bank office. Unknown source values stay null. An uncharged diagnostic contains status and provenance instead of an invalid branch. There are no contact-person fields or fuzzy matches between companies.

| Field | What it means |
|---|---|
| `branchId` | Stable FDIC office identifier (UNINUM). Use this to reconcile a branch across exports. |
| `bankCertificate` | FDIC certificate number identifying the bank that owns the office. |
| `businessName` | Source-reported bank name, rather than an individual contact. |
| `officeName` | FDIC office or branch name; it can differ from the owning bank name. |
| `address` | Business street address of the bank office, as published by FDIC. |
| `city` | Office city from the source record. |
| `state` | Two-letter office state code, such as TX. |
| `zip` | Source-reported office ZIP code, retained as text. |
| `serviceTypeCode` | FDIC numeric office service type. Consult FDIC definitions before categorizing services. |
| `mainOffice` | Whether FDIC identifies this office as the bank main office. |
| `establishedDate` | Office establishment date in the source format; not a newly opened branch alert. |
| `latitude` | Source-reported latitude, or null when unavailable. |
| `longitude` | Source-reported longitude, or null when unavailable. |
| `status` | ok for a usable branch; source\_error for an uncharged row diagnostic. |
| `error` | Plain explanation for a diagnostic, otherwise null. Raw rejected records are omitted. |
| `source` | Source label: FDIC locations. |
| `sourceUrl` | Official FDIC locations endpoint for verification. |
| `retrievedAt` | UTC timestamp when the Actor handled this record. |
| `scrapedAt` | UTC start timestamp for the run. |
| `sourceUpdatedAt` | Null: this endpoint provides no verified row-level revision timestamp. |
| `indexUpdatedAt` | Source index creation time, not the date this branch changed. |
| `freshnessDays` | Null because a meaningful branch revision date is unavailable. |
| `recordVersion` | Hash of normalized business fields, excluding retrieval and index timestamps. |
| `dedupeId` | Branch identifier plus content version, used to suppress retained alert duplicates. |

### Quick start

1. Click **Try for free** or **Start** in Apify Console and choose a state such as `TX`. Leave bank certificates empty for every bank in that territory.
2. Keep **Maximum results** at `20` and choose **Snapshot on every run**. Start the Actor and wait for its output dataset.
3. Review branch identifiers and source links, then export JSON, CSV or Excel. Check the run summary before treating an export as a complete territory list.

The Apify example captured on September 29, 2026 returned 20 Texas branch records from 20 source rows and recorded exactly 20 result events. At $0.003 per delivered result, 20 billable results cost $0.06. The example completed in 9.5 seconds; timing varies with source and platform conditions. A capped sample is not all branches in Texas.

### Who uses it

- **Field-service operations teams** refresh bank-office territories for equipment, facilities and commercial service planning.
- **Banking market researchers** compare source-reported branch footprints with stable office and institution identifiers.
- **Data operations teams** maintain structured branch reference tables and review changed versions before updating internal systems.

### Input

| Input | Purpose |
|---|---|
| `state` | Optional two-letter branch state. Omit for a nationwide scope. |
| `certificates` | Optional list of numeric FDIC bank certificates. These identify banks, not branches. |
| `maxItems` | Delivered-result cap, from 1 to 10,000; default 20. |
| `newSince` | `off` for repeat snapshots; `lastRun` for retained content-version monitoring. |

#### Tips for good input

- Good: `"state": "TX"`. Bad: `"state": "Texas"`; use the two-letter source code.
- Good: `"certificates": ["3066"]`. Bad: a bank name or website URL; this field accepts certificate numbers.
- Good: raise `maxRowsScanned` when many alert records are unchanged. Bad: assume `maxItems: 20` guarantees 20 changed branches exist.

<details><summary>Advanced options</summary>

`maxRowsScanned` caps source rows examined, from 1 to 10,000, with default 100. `maxPages` caps requests, from 1 to 500, with default 5. Each page requests at most 20 rows and respects the remaining scan budget. Result and scan caps are independent: duplicates consume scan capacity but do not create a charged result. Keep a scheduled monitoring input stable and avoid overlapping runs.

</details>

### Sample output

![FDIC branch sample table](https://raw.githubusercontent.com/ledgerstar/assets/main/bank-branch-finder/table.png)

Twenty Texas branches returned by Apify run YC08lRgzO8HUtL6nI on September 29, 2026; the table displays a readable subset. This is a bounded sample in source identifier order.

![Branch sample by city](https://raw.githubusercontent.com/ledgerstar/assets/main/bank-branch-finder/chart.png)

Counts by city within those same 20 records. This is sample composition, not statewide market share or a historical trend.

<details><summary>Full JSON example</summary>

```json
{
  "branchId": "10012",
  "bankCertificate": "3066",
  "businessName": "First Financial Bank",
  "officeName": "THE CITY STATE BANK OF PALACIOS BRANCH",
  "address": "459 Main St",
  "city": "Palacios",
  "state": "TX",
  "zip": "77465",
  "serviceTypeCode": 11,
  "mainOffice": false,
  "establishedDate": "08/26/1940",
  "latitude": 28.701226980751954,
  "longitude": -96.21648396189161,
  "status": "ok",
  "error": null,
  "source": "FDIC locations",
  "sourceUrl": "https://api.fdic.gov/banks/locations",
  "retrievedAt": "2026-09-29T18:22:35.030Z",
  "scrapedAt": "2026-09-29T18:22:33.828Z",
  "sourceUpdatedAt": null,
  "indexUpdatedAt": "2026-09-29T14:25:10Z",
  "freshnessDays": null,
  "recordVersion": "9f6acc19af749b38535d60716933024952aff20676f234941bf1b9c60c6d0f85",
  "dedupeId": "branch:10012:9f6acc19af749b38535d60716933024952aff20676f234941bf1b9c60c6d0f85"
}
```

</details>

### Alert mode: only new records

Set `newSince` to `lastRun` for a scheduled baseline and subsequent change checks. A branch is considered unseen when its identifier and normalized business values have not already been retained. An index rebuild alone does not create a new version. This mode scans the selected scope; it does not use an inferred branch-change date.

A partial monitoring scan saves its position for the next run. If FDIC rebuilds the index between runs, scanning restarts from the beginning and the retained version ledger suppresses known rows. A rebuild during pagination stops the run for a fresh retry. The default `off` mode starts a new snapshot each run; repeated snapshot rows are billable deliveries.

Monitoring retains up to 200,000 versions for 3,650 days. Pruned versions can reappear. Dataset and ledger writes are separate operations, so a crash between them can produce a repeat. Avoid overlapping runs on the same monitoring scope. A missing branch never proves closure.

### Pricing

**$3.00 per 1,000 results**, or $0.003 per saved usable branch row. Retained alert duplicates and diagnostic rows are not billable results. Snapshot mode charges for each delivered row, including branches present in earlier snapshots. Use the maximum total charge control in Apify Console to bound your run.

| Results | Cost |
|---|---|
| 100 | $0.30 |
| 1,000 | $3.00 |
| 10,000 | $30.00 |

These are result-price calculations. You pay for delivered results rather than the number requested. No result is promised when a filter has no matching branches or when monitoring finds no unseen versions.

### Use it through the API

Supply your Apify token through an environment variable. The Actor itself does not require an FDIC credential under the current public API access conditions.

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("ledgerstar/bank-branch-finder").call(
    run_input={"state": "TX", "maxItems": 20, "maxRowsScanned": 20, "maxPages": 1},
    max_total_charge_usd=2,
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('ledgerstar/bank-branch-finder').call(
    { state: 'TX', maxItems: 20, maxRowsScanned: 20, maxPages: 1 },
    { maxTotalChargeUsd: 2 },
);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Integrations

Export CSV for **Google Sheets**, or use the **Apify API** to maintain a branch reference table. **Zapier** and **Make** can process completed datasets. Send a **Slack** notification when an alert dataset contains usable new versions. Filter `status: ok`, retain provenance, and use `dedupeId` in downstream processing. Review the summary's `complete` and `truncated` values before replacing a full internal directory with a bounded export.

### Data source and compliance

The source is the [FDIC Bank Data API](https://api.fdic.gov/banks/docs/), specifically its locations dataset. [FDIC data downloads](https://www.fdic.gov/bank-data-guide/data-downloads) describe published coverage and update schedules. Location snapshots update weekly. FDIC index creation time is provided separately from record freshness; this Actor does not manufacture a row revision date.

Only official bank and office fields are returned. The Actor has no individual contact enrichment, customer accounts or officer records. Public access conditions can change, including future API key requirements; an access failure is surfaced rather than represented as an empty successful search. Ledgerstar is independent of FDIC. AI-assisted software development does not make these outputs financial advice. Verify source records before a client or financial decision.

### FAQ

**Is it legal to use this data?**
The Actor reads publicly available official business records. Your reuse must follow applicable source terms and your own obligations; public availability does not remove those responsibilities.

**How often is the data updated?**
FDIC location snapshots update weekly. Running more frequently does not create fresher branch facts.

**How do I get only new records?**
Select `lastRun`. The first scan establishes a baseline; later scans suppress retained identical versions within that monitoring scope.

**Does a missing branch mean it closed?**
No. Absence can result from filtering, incomplete scans or source changes. Verify any closure against primary records.

**Can I use a bank name as a filter?**
No. Use numeric FDIC certificates to identify banks, and state codes to select territory.

**Why are freshness fields null?**
The locations endpoint has no verified branch-level revision timestamp. The separate index time describes the source index.

**Why did I receive fewer results than requested?**
The scope may be small, records may be unchanged, or a scan limit may have stopped processing. The summary explains the stopping condition.

**Will a repeat snapshot cost money?**
Yes. Snapshot mode delivers current rows again. Only retained duplicates in monitoring mode are suppressed.

**What happens when a row is malformed?**
An uncharged diagnostic explains the omission without exposing the rejected payload. A source-wide request failure fails the run.

**Can monitoring repeat a previously delivered version?**
Yes, after retention expires, when old ledger entries are pruned, or after a crash between separate dataset and state writes. There is no absolute exactly-once guarantee.

**Are coordinates available for every office?**
The Actor returns source-reported coordinates when present. It does not geocode missing values or certify a physical entrance location.

**Can I schedule the Actor?**
Yes. Weekly schedules suit the source cadence. Keep monitoring filters stable and schedule runs far enough apart to avoid overlap.

### More from Ledgerstar

Explore [Texas New Business Leads](https://apify.com/ledgerstar/texas-sales-tax-permits), [Nonprofit Finder](https://apify.com/ledgerstar/nonprofit-finder) and [Building Permits](https://apify.com/ledgerstar/building-permits) for other source-linked business research workflows.

### Support

Support: open an issue on this Actor's Issues tab in Apify Console.

# Changelog

This Actor's version history is a separate document: https://apify.com/ledgerstar/bank-branch-finder/changelog.md

# Actor input Schema

## `state` (type: `string`):

Two-letter state code for branch locations, such as TX. Omit to search all states.

## `certificates` (type: `array`):

FDIC bank certificate numbers, such as 3066. Leave empty for every bank in the selected territory.

## `maxItems` (type: `integer`):

Maximum successfully delivered branch rows. Diagnostic rows are free.

## `newSince` (type: `string`):

Snapshot returns current rows on each new run. Change monitoring suppresses versions already retained for this input scope; it does not prove branch openings or closures.

## `maxRowsScanned` (type: `integer`):

Total source row budget. Raise this when alert runs must scan many unchanged branches.

## `maxPages` (type: `integer`):

At most 20 source rows per page. A capped run reports incomplete coverage in its summary.

## Actor input object example

```json
{
  "state": "TX",
  "maxItems": 20,
  "newSince": "off",
  "maxRowsScanned": 100,
  "maxPages": 5
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "state": "TX",
    "maxItems": 20,
    "newSince": "off",
    "maxRowsScanned": 100,
    "maxPages": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("ledgerstar/bank-branch-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "state": "TX",
    "maxItems": 20,
    "newSince": "off",
    "maxRowsScanned": 100,
    "maxPages": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("ledgerstar/bank-branch-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "state": "TX",
  "maxItems": 20,
  "newSince": "off",
  "maxRowsScanned": 100,
  "maxPages": 5
}' |
apify call ledgerstar/bank-branch-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ledgerstar/bank-branch-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/U7A879WKMkJSgShkb/builds/xY9CKwS3WRmaVL0BF/openapi.json