Get Entity

Retrieve full details for a specific business entity by ID, with optional enrichment from federal databases, SAM.gov, IRS 990 filings, UCC records, SBA PPP loans, and related-entity data.

Endpoint

GET /api/v1/entity/{id}

Get full details for a specific business entity. Pass ?include= with one or more comma-separated tokens to enrich the response with data from external sources. Each token adds 1 credit on top of the base cost of 1 credit.

Parameters

Name	Type	Required	Description
`id`	string	yes	Entity ID from search results (UUID for DB states, STATE:id for Socrata states)
`include`	string	no	Comma-separated enrichment tokens (see Include Tokens below). Example: `?include=federal,sam,nonprofit`. Unknown tokens are silently ignored.

Include Tokens

Token	Data added	Source
`federal`	SEC filings, USASpending contracts, Senate LDA lobbying disclosures	SEC EDGAR, USASpending.gov, Senate LDA
`sam`	UEI, CAGE code, NAICS code, business types, registration status	SAM.gov
`nonprofit`	EIN, income, assets, NTEE code, ruling date, subsection code	ProPublica IRS 990
`ucc`	UCC filings	CT and CO only — limited coverage
`ppp`	SBA Paycheck Protection Program loans	SBA
`related`	Entities sharing a registered agent or principal address	Filed cross-reference
`all`	All of the above	Shortcut for all six tokens

Example Request

cURL

# Basic entity lookup (1 credit)
curl "https://filed.dev/api/v1/entity/ent_mNqR7xKp" \
  -H "Authorization: Bearer fd_live_aBcDeFgH"

# Federal + SAM + nonprofit enrichment (4 credits)
curl "https://filed.dev/api/v1/entity/NY:1393779?include=federal,sam,nonprofit" \
  -H "Authorization: Bearer fd_live_aBcDeFgH"

# All enrichments (7 credits)
curl "https://filed.dev/api/v1/entity/NY:1393779?include=all" \
  -H "Authorization: Bearer fd_live_aBcDeFgH"

Python

import requests

headers = {"Authorization": "Bearer fd_live_aBcDeFgH"}

# Basic lookup
resp = requests.get(
    "https://filed.dev/api/v1/entity/ent_mNqR7xKp",
    headers=headers
)

# Multiple enrichments
resp = requests.get(
    "https://filed.dev/api/v1/entity/NY:1393779",
    params={"include": "federal,sam,nonprofit"},
    headers=headers
)

Node.js

const headers = { Authorization: "Bearer fd_live_aBcDeFgH" };

// Basic lookup
const res = await fetch(
  "https://filed.dev/api/v1/entity/ent_mNqR7xKp",
  { headers }
);

// Multiple enrichments
const res2 = await fetch(
  "https://filed.dev/api/v1/entity/NY:1393779?include=federal,sam,nonprofit",
  { headers }
);

// Basic lookup
req, _ := http.NewRequest("GET",
  "https://filed.dev/api/v1/entity/ent_mNqR7xKp", nil)
req.Header.Set("Authorization", "Bearer fd_live_aBcDeFgH")
resp, _ := http.DefaultClient.Do(req)

// Multiple enrichments
req2, _ := http.NewRequest("GET",
  "https://filed.dev/api/v1/entity/NY:1393779?include=federal,sam,nonprofit", nil)
req2.Header.Set("Authorization", "Bearer fd_live_aBcDeFgH")
resp2, _ := http.DefaultClient.Do(req2)

Response

Each include token adds a top-level key to data when data is found. Keys present in the response correspond directly to the tokens requested: federal, sam, nonprofit, ucc, ppp, related.

Officers aggregation

The officers array aggregates entries across all active sources (state records, SAM.gov, IRS 990). Each entry includes a source field indicating where it came from. Deduplication is case-insensitive on name + role.

"officers": [
  { "name": "JANE DOE", "title": "CEO", "source": "state" },
  { "name": "Jane Doe", "title": "Authorized Representative", "source": "sam" },
  { "name": "JANE DOE", "title": "Principal Officer", "source": "irs_990" }
]

source values: state, sam, irs_990.

Example response (`?include=federal,sam,nonprofit`)

{
  "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" },
      { "name": "ALBERT BOURLA", "title": "Authorized Representative", "source": "sam" }
    ],
    "filings": [],
    "federal": {
      "sec": {
        "items": [
          { "type": "10-K", "date": "2026-02-26", "description": "PFIZER INC" }
        ],
        "totalCount": 7
      },
      "contracts": {
        "items": [
          {
            "awardId": "W58P0524D0020",
            "amount": 787274.80,
            "agency": "Department of Defense",
            "startDate": "2025-08-26"
          }
        ],
        "totalCount": 500
      },
      "lobbying": {
        "items": [
          {
            "registrantName": "PFIZER INC",
            "clientName": "PFIZER INC",
            "amount": 2890000,
            "issueArea": "Pharmaceutical Industry",
            "filingDate": "2026-03-17"
          }
        ],
        "totalCount": 1730
      }
    },
    "sam": {
      "uei": "ABC123DEF456",
      "cageCode": "1A2B3",
      "naicsCode": "325412",
      "businessTypes": ["2X", "A2"],
      "registrationStatus": "Active",
      "expirationDate": "2027-01-15"
    },
    "nonprofit": {
      "ein": "13-5315170",
      "nteeCode": "G30",
      "income": 58496000000,
      "assets": 167489000000,
      "rulingDate": "195306",
      "subsectionCode": "03"
    }
  },
  "meta": {
    "source": "New York Division of Corporations",
    "lastUpdated": "2026-03-18T04:00:00Z",
    "creditsUsed": 4
  }
}

Credits

Request	Credits
Basic lookup (no `include`)	1
Each `include` token	+1 per token
`include=all` (6 tokens)	7 total

Examples: include=federal = 2 credits, include=federal,sam,nonprofit = 4 credits, include=all = 7 credits.

Try It

Test this endpoint in the Playground.

On this page