Entity Lookup

POST /v1/entities/lookup is the core read path. It is read-only — it never creates entities, only matches them against the canonical store.

Identifier types

Type	Description	Example
uei	Unique Entity Identifier (SAM.gov)	ABCD12345678
tin	Taxpayer Identification Number (EIN)	12-3456789
duns	Dun & Bradstreet number (legacy)	123456789
cage	Commercial and Government Entity code	7XYZ2

You can also pass legal_name and address as top-level fields alongside identifiers.

Exact mode

Exact mode runs first for every lookup. It:

1. Normalizes each identifier value
2. Hashes the normalized value
3. OR-queries the identifier table for any matching hash
4. Combines with exact normalized-name matches
5. Returns the highest-confidence match

{
  "identifiers": [
    { "type": "uei", "value": "ABCD12345678" },
    { "type": "tin", "value": "12-3456789" }
  ]
}

Fuzzy mode

If no exact match is found — or you request it explicitly — the lookup adds a trigram candidate search over entities.normalized_name, scored by:

• Identifier overlap evidence
• Jaro-Winkler name similarity

Results are returned ranked by score. Enable fuzzy mode by passing "mode": "fuzzy":

{
  "legal_name": "Acme Federal Services",
  "mode": "fuzzy"
}

Response

{
  "id": "ent_01abc...",
  "legal_name": "ACME FEDERAL SERVICES LLC",
  "identifiers": {
    "uei": "ABCD12345678",
    "tin": "****6789",
    "cage": "7XYZ2"
  },
  "sam_gov": {
    "registration_status": "active",
    "cage": "7XYZ2",
    "expiration_date": "2027-01-15",
    "entity_type": "Business or Organization"
  },
  "addresses": [
    {
      "type": "physical",
      "line1": "123 Main St",
      "city": "Washington",
      "state": "DC",
      "zip": "20001",
      "country": "US"
    }
  ],
  "confidence": 0.97,
  "sources": [
    { "name": "sam_gov", "retrieved_at": "2026-04-19T00:00:00Z", "version": "2026-04-19" }
  ]
}

TIN masking

TIN values are always masked as ****{last4} in API responses. The full value is never returned.

No match

If no entity matches, the API returns 404:

{
  "error": "entity_not_found",
  "message": "No entity matched the provided identifiers."
}

Use POST /v1/entities to explicitly create an entity that doesn't appear in source registries (e.g. a subcontractor not in SAM.gov).

Multiple candidates (fuzzy)

When fuzzy mode returns multiple ranked candidates:

{
  "candidates": [
    { "id": "ent_01...", "legal_name": "ACME FEDERAL SERVICES LLC", "confidence": 0.92 },
    { "id": "ent_02...", "legal_name": "ACME FEDERAL SERVICES INC", "confidence": 0.71 }
  ]
}