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 YOUR_API_KEY"

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

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

Python

import requests

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

# 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 YOUR_API_KEY" };

// 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 YOUR_API_KEY")
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 YOUR_API_KEY")
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.

Record classification

data always carries two fields describing what kind of record it is:

Field	Type	Description
`recordClass`	string	`registry_entity`, `federal_registration`, `filing_event`, `license`, `name_registration`, `government_vendor` or `financial_assistance_award`
`subjectType`	string	`organization` or `person`

They matter most when a response looks thin. A license or financial_assistance_award record has no formation date and usually no registered agent, because its publisher does not hold those fields — that is the record being what it is, not a coverage gap. A subjectType of person means the subject is a named individual, not a company.

The values are identical to the ones /v1/search returns for the same record. See Record Classes for what each means.

Authority

data also carries two fields describing who actually asserted the record, independent of recordClass:

Field	Type	Description
`jurisdictionLevel`	string or `null`	`federal`, `state`, `county`, or `null` if unverified for this record's source
`sourceAgency`	string or `null`	The real asserting body, e.g. `"Texas Comptroller of Public Accounts"` — or `null` alongside a `null` `jurisdictionLevel`

Unlike recordClass and subjectType, these two can be null — check for that before displaying them. See Record Classes for the full explanation and the current coverage.

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": [],
    "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": [
          {
            "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