# Filed.dev API reference

> Filed.dev is a REST API for US business entity data. It covers state business registrations from all 50 states plus DC, and enriches them with SEC EDGAR filings, Senate lobbying disclosures, USASpending.gov contracts, SAM.gov registrations, IRS 990 data and SBA PPP loans. This file is the full reference in plain markdown. The short index is at https://filed.dev/llms.txt and the human-readable docs are at https://filed.dev/docs.

## Basics

- Base URL: `https://filed.dev/api/v1`
- Format: JSON responses. `POST` bodies are JSON (`Content-Type: application/json`).
- Auth: every endpoint below requires an API key (see Authentication).
- Get a key: https://filed.dev/register. Manage or regenerate it at https://filed.dev/account.
- Plans and pricing: https://filed.dev/developers#pricing
- FAQ: https://filed.dev/faq

## Authentication

Send your API key in the `Authorization` header with the Bearer scheme:

```
Authorization: Bearer fd_live_aBcDeFgH
```

| Key prefix | Environment |
| --- | --- |
| `fd_live_` | Production. Counts against your plan's credits. |
| `fd_test_` | Testing. Same endpoints and data. |

Regenerating a key invalidates the old one immediately. Call the API from your server, never from browser code.

A missing or invalid key returns `401`:

```json
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key. Get one at https://filed.dev/register" } }
```

## Plans, credits and rate limits

| Plan | Monthly | Annual (prepaid, 2 months free) | Monthly credits |
| --- | --- | --- | --- |
| Developer | $49/mo, 14-day trial | $490/yr, 14-day trial | 1,000 |
| Business | $199/mo | $1,990/yr | 10,000 |
| Scale | $499/mo | $4,990/yr | 50,000 |

Monthly billing is the default. To choose annual, add `&interval=year` to the signup link, e.g. https://filed.dev/register?plan=business&interval=year. On annual plans the credit allowance still resets at the start of every calendar month (UTC); it is not a yearly pool.

Every plan is limited to 60 requests per minute per API key. For more than 50,000 credits a month or more than 25 queries per batch, see https://filed.dev/enterprise.

Credits per request:

| Request | Credits |
| --- | --- |
| `GET /v1/search` with `state` | 1 |
| `GET /v1/search` without `state` (cross-state), or with `officer` | 5 |
| `GET /v1/entity/{id}` | 1, plus 1 per `include` token (`include=all` = 7) |
| `POST /v1/batch` | the sum over its queries: each query costs 1 (5 if it is cross-state or uses `officer`), plus 1 per `include` token |
| `GET /v1/sec/search` | 2 |
| `GET /v1/lobbying/search` | 2 |
| `GET /v1/contracts/search` | 2 |

A request answered with any 5xx status costs 0 credits.

Rate limit headers on every response:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

## Errors

Every error has the same JSON shape:

```json
{ "error": { "code": "rate_limit_exceeded", "message": "You have exceeded your monthly lookup limit." } }
```

| HTTP status | `code` | Meaning |
| --- | --- | --- |
| 400 | `invalid_params` | Missing or invalid parameters |
| 401 | `unauthorized` | Missing or invalid API key |
| 403 | `tier_insufficient` | Endpoint needs a higher plan (for example, `/v1/batch` on Developer) |
| 404 | `not_found` | Entity not found |
| 429 | `rate_limit_exceeded` | Monthly credits or per-minute limit used up |
| 500 | `internal_error` | Server error |
| 502 | `upstream_error` | A state data source is temporarily unavailable. Retry after 5-10 seconds |
| 503 | `service_unavailable` | The API key could not be checked right now. Wait for `Retry-After`, then retry. Do not regenerate the key |
| 504 | `timeout` | A search did not finish within 25 seconds. Sent with `Retry-After: 5` |

## Endpoints

### GET /v1/search

Search state business entities. Auth: required (Bearer API key, any plan). Credits: 1, or 5 when `state` is omitted or `officer` is used.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | one of `name` / `agent` | Business name |
| `agent` | string | one of `name` / `agent` | Registered agent name |
| `state` | string | no | Two-letter state code, e.g. `FL`. Omit to search every state (5 credits, slower) |
| `status` | string | no | `active`, `inactive` or `all` (default `all`) |
| `type` | string | no | `llc`, `corporation` or `lp` |
| `record_class` | string | no | Comma-separated record classes, or `all`. Default `registry_entity,federal_registration` |
| `exact` | boolean | no | `true` to require an exact name match |
| `formed_after` | string | no | ISO 8601 date |
| `formed_before` | string | no | ISO 8601 date |
| `filing_number` | string | no | State-assigned filing number |
| `officer` | string | no | Officer name (5 credits) |
| `limit` | integer | no | Max 50, default 10 |
| `offset` | integer | no | Default 0 |

Example request:

```bash
curl "https://filed.dev/api/v1/search?name=Acme&state=FL" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response:

```json
{
  "data": [
    {
      "id": "ent_mNqR7xKp",
      "name": "ACME HOLDINGS LLC",
      "state": "FL",
      "type": "LLC",
      "status": "Active",
      "formedDate": "2019-03-14",
      "registeredAgent": { "name": "CSC Global", "address": "1234 Main St, Tallahassee, FL 32301" },
      "principalAddress": "123 Main St, Miami, FL 33101",
      "officerCount": 3,
      "lastUpdated": "2026-02-27T12:00:00Z",
      "recordClass": "registry_entity",
      "subjectType": "organization",
      "jurisdictionLevel": "state",
      "sourceAgency": "Florida Division of Corporations (Sunbiz)"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "state": "FL",
    "source": "Florida Division of Corporations",
    "record_class": ["registry_entity", "federal_registration"]
  }
}
```

Cross-state searches (no `state`) add `meta.partial` (boolean), `meta.statesSearched` (integer) and `meta.statesFailed` (array of state codes). `partial: true` means some states could not be reached. It does not mean the company is absent from those states.

Full docs: https://filed.dev/docs/api/search

### GET /v1/entity/{id}

Full details for one entity. Auth: required (Bearer API key, any plan). Credits: 1, plus 1 per `include` token.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | path string | yes | Entity ID from a search result, e.g. `ent_mNqR7xKp` or `NY:1393779` |
| `include` | string | no | Comma-separated enrichment tokens: `federal` (SEC, contracts, lobbying), `sam` (SAM.gov), `nonprofit` (IRS 990), `ucc` (UCC filings, CT and CO only), `ppp` (SBA PPP loans), `related` (entities sharing an agent or address), or `all`. Unknown tokens are ignored |

Example request:

```bash
curl "https://filed.dev/api/v1/entity/NY:1393779?include=federal,sam" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response (trimmed):

```json
{
  "data": {
    "id": "NY:1393779",
    "name": "PFIZER H.C.P. CORPORATION",
    "state": "NY",
    "stateEntityId": "1393779",
    "type": "Domestic Business Corporation",
    "status": "Active",
    "formedDate": "1953-06-02",
    "registeredAgent": { "name": "C T Corporation System", "address": "28 Liberty Street, New York, NY 10005" },
    "officers": [{ "name": "ALBERT BOURLA", "title": "CEO", "source": "state" }],
    "filings": [],
    "recordClass": "registry_entity",
    "subjectType": "organization",
    "jurisdictionLevel": "state",
    "sourceAgency": "New York Department of State",
    "federal": {
      "sec": { "items": [{ "type": "10-K", "date": "2026-02-26", "description": "PFIZER INC" }], "totalCount": 7 },
      "contracts": { "items": [], "totalCount": 500 },
      "lobbying": { "items": [], "totalCount": 1730 }
    },
    "sam": { "uei": "ABC123DEF456", "cageCode": "1A2B3", "naicsCode": "325412", "registrationStatus": "Active" }
  },
  "meta": { "source": "New York Division of Corporations", "lastUpdated": "2026-03-18T04:00:00Z", "creditsUsed": 3 }
}
```

Full docs: https://filed.dev/docs/api/entity

### POST /v1/batch

Run up to 25 search queries in one request. Auth: required (Bearer API key, Business or Scale plan; Developer keys get `403 tier_insufficient`). Credits: per query, 1 (5 if cross-state or `officer`) plus 1 per `include` token.

Request body:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `queries` | array | yes | Up to 25 query objects. More than 25 returns `400 invalid_params` |
| `queries[].name` | string | one of `name` / `agent` | Business name |
| `queries[].agent` | string | one of `name` / `agent` | Registered agent name |
| `queries[].state` | string | no | Two-letter state code. Omit for cross-state (5 credits) |
| `queries[].include` | string | no | Enrichment tokens, same as `/v1/entity/{id}` |
| `queries[].limit` | integer | no | Max 50, default 10 |

Batch queries do not accept `record_class`, and their results do not carry `recordClass` / `subjectType`.

Example request:

```bash
curl -X POST "https://filed.dev/api/v1/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"name": "Pfizer", "state": "NY", "include": "federal"}, {"name": "Acme", "state": "FL"}]}'
```

Example response (trimmed):

```json
{
  "results": [
    {
      "query": { "name": "Pfizer", "state": "NY", "include": "federal" },
      "data": [{ "id": "NY:1393779", "name": "PFIZER H.C.P. CORPORATION", "state": "NY", "status": "Active", "federal": { "sec": { "items": [], "totalCount": 7 } } }],
      "meta": { "total": 3, "limit": 10, "state": "NY" }
    },
    {
      "query": { "name": "Acme", "state": "FL" },
      "data": [{ "id": "ent_mNqR7xKp", "name": "ACME HOLDINGS LLC", "state": "FL", "type": "LLC", "status": "Active" }],
      "meta": { "total": 1, "limit": 10, "state": "FL" }
    }
  ]
}
```

Full docs: https://filed.dev/docs/api/batch

### GET /v1/sec/search

Search SEC EDGAR filings. Auth: required (Bearer API key, any plan). Credits: 2.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | at least one of `q` / `cik` / `sic` | Company name or keyword |
| `cik` | string | at least one of `q` / `cik` / `sic` | SEC Central Index Key |
| `sic` | string | at least one of `q` / `cik` / `sic` | SIC industry code, e.g. `2834` |
| `forms` | string | no | Comma-separated form types, e.g. `10-K,10-Q,8-K` |
| `start_date` | string | no | `YYYY-MM-DD` |
| `end_date` | string | no | `YYYY-MM-DD` |
| `limit` | integer | no | Max 100, default 25 |
| `offset` | integer | no | Default 0 |

Example request:

```bash
curl "https://filed.dev/api/v1/sec/search?q=Pfizer&forms=10-K,10-Q" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response (trimmed):

```json
{
  "data": [
    {
      "accessionNumber": "0000078003-26-000026",
      "formType": "10-K",
      "fileDate": "2026-02-26",
      "periodEnding": "2025-12-31",
      "filer": "PFIZER INC (PFE) (CIK 0000078003)",
      "cik": "0000078003",
      "sicCode": "2834",
      "incorporationState": "DE",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/78003/..."
    }
  ],
  "meta": { "totalCount": 1533, "offset": 0, "limit": 25, "hasMore": true, "source": "SEC EDGAR" }
}
```

Full docs: https://filed.dev/docs/api/sec

### GET /v1/lobbying/search

Search Senate Lobbying Disclosure Act (LDA) filings. Auth: required (Bearer API key, any plan). Credits: 2.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `client_name` | string | at least one of `client_name` / `registrant_name` / `issue_code` | Client being represented, e.g. `Pfizer` |
| `registrant_name` | string | at least one of `client_name` / `registrant_name` / `issue_code` | Lobbying firm or registrant |
| `issue_code` | string | at least one of `client_name` / `registrant_name` / `issue_code` | Issue area code, e.g. `HCR`, `DEF`, `TAX` |
| `filing_year` | string | no | e.g. `2025` |
| `filing_type` | string | no | e.g. `RR` (registration), `Q1`-`Q4` (quarterly reports) |
| `page` | integer | no | Default 1 |
| `page_size` | integer | no | Max 100, default 25 |

Example request:

```bash
curl "https://filed.dev/api/v1/lobbying/search?client_name=Pfizer" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response (trimmed):

```json
{
  "data": [
    {
      "filingId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "filingDate": "2026-03-17T00:00:00Z",
      "filingType": "1st Quarter - Report",
      "filingYear": 2026,
      "registrant": { "name": "PFIZER INC", "id": 24976 },
      "client": { "name": "PFIZER INC", "id": 24976 },
      "income": 2890000,
      "lobbyingActivities": [{ "issueCode": "HCR", "issueDescription": "Health Issues" }],
      "documentUrl": "https://lda.senate.gov/filings/public/filing/..."
    }
  ],
  "meta": { "totalCount": 1730, "page": 1, "pageSize": 25, "hasNext": true, "source": "Senate Office of Public Records (LDA)" }
}
```

Full docs: https://filed.dev/docs/api/lobbying

### GET /v1/contracts/search

Search federal contracts from USASpending.gov. Auth: required (Bearer API key, any plan). Credits: 2.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `recipient` | string | at least one of `recipient` / `agency` / `naics` / `psc` | Contractor name |
| `agency` | string | at least one of `recipient` / `agency` / `naics` / `psc` | Awarding agency, e.g. `Department of Defense` |
| `naics` | string | at least one of `recipient` / `agency` / `naics` / `psc` | NAICS code, e.g. `325412` |
| `psc` | string | at least one of `recipient` / `agency` / `naics` / `psc` | Product Service Code |
| `award_types` | string | no | Comma-separated: `A` (BPA call), `B` (purchase order), `C` (delivery order), `D` (definitive contract). Default `C,D` |
| `min_amount` | number | no | Minimum award in dollars |
| `max_amount` | number | no | Maximum award in dollars |
| `start_date` | string | no | `YYYY-MM-DD` |
| `end_date` | string | no | `YYYY-MM-DD` |
| `sort` | string | no | `Award ID`, `Recipient Name`, `Award Amount`, `Awarding Agency`, `Start Date` or `End Date` |
| `order` | string | no | `asc` or `desc` (default `desc`) |
| `page` | integer | no | Default 1 |
| `limit` | integer | no | Max 100, default 25 |

Example request:

```bash
curl "https://filed.dev/api/v1/contracts/search?recipient=Pfizer&min_amount=1000000" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Example response (trimmed):

```json
{
  "data": [
    {
      "awardId": "W58P0524D0020",
      "recipientName": "PFIZER INC.",
      "amount": 787274.80,
      "awardingAgency": "Department of Defense",
      "startDate": "2025-08-26",
      "endDate": "2026-08-25",
      "awardType": "Definitive Contract",
      "naicsCode": "325412"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "hasNext": true, "source": "USASpending.gov" }
}
```

Full docs: https://filed.dev/docs/api/contracts

## Record fields

Search and entity results carry four classification fields:

| Field | Values |
| --- | --- |
| `recordClass` | `registry_entity`, `federal_registration`, `filing_event`, `license`, `name_registration`, `government_vendor`, `financial_assistance_award` |
| `subjectType` | `organization` or `person` |
| `jurisdictionLevel` | `federal`, `state`, `county`, or `null` if unverified |
| `sourceAgency` | The agency that asserted the record, or `null` |

A `license` or `financial_assistance_award` record usually has no formation date or registered agent, because its publisher does not hold those fields. More: https://filed.dev/docs/data/record-classes

## More

- Documentation: https://filed.dev/docs
- State coverage: https://filed.dev/docs/data/coverage
- Changelog: https://filed.dev/docs/changelog
- x402 pay-per-request (USDC, no API key): https://filed.dev/api-x402
- Sitemap: https://filed.dev/sitemap.xml