# US LDA Lobbying Client & Registrant New-Filing Watchlist (`plym-actor-factory/us-lda-lobbying-filing-watchlist`) Actor

Watch lobbying client and/or registrant firm names; poll the official Senate LDA REST API (lda.gov); emit typed events only for new filing\_uuid values for your book. Not an LDA dump; not Quorum/FiscalNote; not HTML scrape.

- **URL**: https://apify.com/plym-actor-factory/us-lda-lobbying-filing-watchlist.md
- **Developed by:** [Daniel Witney](https://apify.com/plym-actor-factory) (community)
- **Categories:** AI, Automation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 lda filing event delivereds

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

## US LDA Lobbying Client & Registrant New-Filing Watchlist

Watch a **book of lobbying clients and/or registrant firms** and receive **typed events** when a **new** Senate Lobbying Disclosure Act (LDA) filing (`filing_uuid`) appears for those names — LD-1 registrations, LD-2 quarterly activity reports, terminations, and amendments.

**Not** a nationwide LDA dump. **Not** Quorum / FiscalNote. **Not** an HTML scrape of the lda.senate.gov search UI.

### Official source

- **Senate Office of Public Records LDA REST API** — `https://lda.gov/api/v1/` (canonical; `lda.senate.gov` redirects here)
- Free; **no API key required** (anonymous ~15 req/min). Optional user key raises limits.
- Docs: https://lda.gov/api/

**Attribution:** Data from the U.S. Senate Office of Public Records Lobbying Disclosure Act (LDA) API. *The Senate Office of Public Records cannot vouch for derived analyses.* **No Senate Seal** is used in this Actor.

### Events (PPE)

| `event_type` | Meaning |
|---|---|
| `LDA_NEW_LD1_REGISTRATION` | New LD-1 registration (`RR`) |
| `LDA_NEW_LD2_QUARTERLY` | New LD-2 quarterly / mid-year / year-end activity report (`Q*`, `MM`, `YY`, …) |
| `LDA_TERMINATION` | Termination filing (`*T`, `MT`, `YT`, …) |
| `LDA_AMENDMENT` | Amendment / termination-amendment (`RA`, `*A`, `*@`, …) |
| `RUN_STATUS` | Non-billable run health row |

**Pricing (Model A):** single tier ≈ **$0.02 / event** (`lda-filing-event-delivered`) + `apify-actor-start` ≈ $0.00005. Quiet days ≈ $0.

### Modes

| `sourceMode` | Behavior |
|---|---|
| `fixture` (default) | Store / CI health path — emits **only** non-billable `RUN_STATUS` / `FIXTURE_HEALTH` (0 product charges) unless `emitFixtureDemoEvents=true` |
| `live` | Poll official LDA API for each watchlist name/ID; baseline first-seen `filing_uuid`s; emit events only for **new** UUIDs |

### Matching honesty (read before buying)

- Name match is **normalized string / substring** (case-insensitive; punctuation stripped).
- **DBA / trade-name / former-name aliases may miss.** Prefer `clientIds` / `registrantIds` when you have them.
- First observation of each `filing_uuid` is **baseline only** (no charge). Re-seen UUIDs stay quiet.
- Anonymous API rate limit ≈ **15/min** — default `requestPaceMs=4500`. Optional `ldaApiKey` for higher limits.

### Production use

1. Set **`sourceMode` = `live`**
2. Provide `clientNames` and/or `registrantNames` (and/or IDs)
3. Optionally set `filingYears` and `postedAfter`
4. Schedule after your desired cadence (daily/weekly is typical)

#### Production example

```json
{
  "clientNames": ["ACME ENERGY CORP"],
  "registrantNames": ["SMITH & JONES LLP"],
  "sourceMode": "live",
  "filingYears": [2026],
  "maxRunSeconds": 120,
  "resumeFromCheckpoint": true
}
```

### Legal

- **GREEN** for official Senate LDA API reuse with attribution.
- Do **not** use the Senate Seal.
- Cite retrieval date in downstream products.

### A1b

Cited **A1b PASS** from `opportunity/reports/phase3-a1b-next3-v8.md` — zero adopted client/registrant portfolio new-filing PPE products on Store; dump shelf is a different job.

# Actor input Schema

## `clientNames` (type: `array`):

Lobbying client names to watch (case-insensitive; normalized string / substring match). Prefer clientIds when known. DBA aliases may miss.

## `registrantNames` (type: `array`):

Lobbying registrant firm names to watch (case-insensitive; normalized string / substring match).

## `clientIds` (type: `array`):

Optional Senate LDA client IDs (exact).

## `registrantIds` (type: `array`):

Optional Senate LDA registrant IDs (exact).

## `filingYears` (type: `array`):

Filing years to poll (default: current calendar year).

## `postedAfter` (type: `string`):

Optional lower bound on dt\_posted (filing\_dt\_posted\_after).

## `maxRunSeconds` (type: `integer`):

Wall-clock budget for this scheduled poll.

## `maxEvents` (type: `integer`):

Stop after this many unique billable filing events (excludes RUN\_STATUS).

## `resumeFromCheckpoint` (type: `boolean`):

If true, resume seen filing\_uuid values and event\_uids from the default Key-Value Store.

## `sourceMode` (type: `string`):

fixture = Store/CI default (RUN\_STATUS only unless emitFixtureDemoEvents=true). live = official Senate LDA REST API.

## `emitFixtureDemoEvents` (type: `boolean`):

When sourceMode=fixture, if true push fabricated filing events from local fixtures. Default false so Store auto-tests never charge lda-filing-event-delivered. SAMPLE rows only: demo events use placeholder entities (never real companies/IDs), are flagged sample=true / isSample=true, and are NEVER charged.

## `requestPaceMs` (type: `integer`):

Delay between LDA HTTP requests. Anonymous ≈ 15/min — default 4500ms. Optional ldaApiKey raises limit.

## `ldaApiKey` (type: `string`):

Optional Senate LDA API key (Authorization: Token …) for higher rate limits.

## `pageSize` (type: `integer`):

LDA filings page size (1–25).

## `maxPagesPerQuery` (type: `integer`):

Max pages per watchlist query (CU / rate guard).

## Actor input object example

```json
{
  "clientNames": [
    "ACME ENERGY CORP",
    "CONTOSO HEALTH INC"
  ],
  "registrantNames": [
    "SMITH & JONES LLP"
  ],
  "clientIds": [],
  "registrantIds": [],
  "filingYears": [
    2026
  ],
  "maxRunSeconds": 55,
  "maxEvents": 500,
  "resumeFromCheckpoint": true,
  "sourceMode": "fixture",
  "emitFixtureDemoEvents": false,
  "requestPaceMs": 4500,
  "pageSize": 25,
  "maxPagesPerQuery": 3
}
```

# Actor output Schema

## `OUTPUT` (type: `string`):

JSON summary: delivered, charged, runStatus, checkpoint, stats, attribution

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("plym-actor-factory/us-lda-lobbying-filing-watchlist").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("plym-actor-factory/us-lda-lobbying-filing-watchlist").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 '{}' |
apify call plym-actor-factory/us-lda-lobbying-filing-watchlist --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,plym-actor-factory/us-lda-lobbying-filing-watchlist"
        }
    }
}
```

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/9fIb5J1GgK4LNapLZ/builds/kr2DTwAvKZq2W2uGX/openapi.json