Entities Data Dictionary¶

This document describes the fields available in the Entities API endpoints (/api/entities/). For filtering, ordering, and pagination, see the Entities API Reference.

Overview¶

Entities represent vendors and recipients in federal contracting and assistance. The canonical identifier is UEI (Unique Entity ID). Data is sourced from SAM.gov, with supplemental data from DSBS and Tango-calculated obligation metrics.

Identifiers¶

• uei (canonical): Public identifier for entities and the API lookup key: GET /api/entities/{uei}/.
• uuid (internal): Tango's internal UUID primary key for the entity record. This is not intended as a public lookup key; other tables typically reference entities by uei.

Note: The full set of fields is available via the shape query parameter. The base response includes a subset of commonly-used fields. See Response Shaping for details.

Update Frequency¶

Entity data is updated from SAM.gov on a regular sync cadence (typically within 20–60 minutes of SAM changes). Federal obligation rollups are derived from award data.

Fields¶

Common code values¶

purpose_of_registration_code (SAM.gov)¶

SAM.gov registration-purpose codes:

sba_business_types (DSBS / SAM.gov)¶

These are SBA program classifications you'll commonly see (non-exhaustive). From SBA_BUSINESS_TYPE_MAP:

business_types (SAM.gov)¶

Entities store business types as 2-character codes (e.g., A6, 2R, QF). The canonical list (including certifier) is exposed at /api/business_types/ (see Business Types Data Dictionary).

Expansions (via shape)¶

physical_address / mailing_address¶

Returns the address as an object with normalized snake_case keys:

• address_line1, address_line2, city, state_or_province_code, zip_code, zip_code_plus4, country_code, country_name, county, county_code, fips_code

Address data from different sources (SAM uses snake_case, DSBS uses camelCase) is automatically normalized to the canonical snake_case format above. The county, county_code, and fips_code subfields are available when provided by DSBS.

business_types¶

Returns a normalized array of {code, description} objects. Raw data may be stored as:

• [{code, description}] (SAM format — passed through)
• {"2X": true, "F": true} (DSBS format — normalized with description lookups)

sba_business_types¶

Returns a normalized array of {code, description, entry_date, exit_date} objects. Same normalization as business_types.

naics_codes¶

Returns a normalized array of {code, sba_small_business} objects. Plain string arrays (e.g., ["541512", "541511"]) are normalized to [{code: "541512", sba_small_business: null}, ...].

federal_obligations¶

Expand-only field (not available as a leaf). Returns obligation rollups with child fields total and active.

# Both total and active
/api/entities/{uei}/?shape=uei,federal_obligations(*)

# Only total obligations
/api/entities/{uei}/?shape=uei,federal_obligations(total)

Each sub-object structure:

• total: {awards_obligated, awards_count, subawards_obligated, subawards_count, idv_count}
• active: {awards_obligated, awards_count, idv_count}

highest_owner / immediate_owner¶

Returns the corporate owner as {cage_code, legal_business_name, uei}. Supports child field selection.

relationships¶

Returns the list of related entities. Each item can include:

• relation, type, source, uei, display_name

uei and display_name identify the partner — the company on the other end of the tie, not the entity you requested.

Match on type, not relation¶

type is the stable machine-readable code. relation is a display label describing the partner's role, and its vocabulary can change — it did in API 4.20.0, when subcontracting and corporate-succession ties stopped reporting the catch-all affiliate. If you have code matching the string affiliate, switch it to type.

Two notes on reading these:

• descendant, not child. An ultimate_parent tie is only recorded when the ultimate owner differs from the immediate owner, so the company on the other end is never a direct subsidiary — it sits at least one company further down the chain. Use parent_subsidiary for immediate ties.
• A prime_sub tie is not a partnership. One subaward creates the edge, and it never expires — a single 2016 subaward is indistinguishable from an active arrangement. Subaward reporting is also a reporting-threshold sample, so a missing tie means "not reported," never "never worked together." It is not a joint venture; there is no joint-venture relationship type.

Entries are de-duplicated after your shape selection is applied, so a narrower shape can return fewer entries. A company with several distinct ties to the same partner collapses to one entry under shape=relationships(uei) but stays separate under shape=relationships(*).

Code/description pair expands¶

The following fields are structured {code, description} expands. When the model's description is missing or empty, the system falls back to a lookup map (where available).

• entity_structure(code, description) — falls back to ENTITY_STRUCTURE_MAP
• entity_type(code, description) — falls back to BUSINESS_TYPE_MAP
• profit_structure(code, description) — falls back to BUSINESS_TYPE_MAP
• organization_structure(code, description) — falls back to BUSINESS_TYPE_MAP
• state_of_incorporation(code, description) — uses model description
• country_of_incorporation(code, description) — falls back to the GENC standard for country names when SAM.gov doesn't provide one
• purpose_of_registration(code, description) — falls back to PURPOSE_OF_REGISTRATION_MAP

Returns null when the code is null.

# Get entity structure as structured object
/api/entities/{uei}/?shape=uei,entity_structure(*)

# Just the code
/api/entities/{uei}/?shape=uei,entity_structure(code)

Data Sources¶

• SAM.gov – Registration, UEI, legal name, addresses, NAICS/PSC/business types, dates, status, corporate ownership.
• DSBS – Capabilities, keywords, SBA business types, current principals, NAICS small codes, special equipment/materials, capabilities link, non-federal certifications, additional website, county/county code/FIPS code (when available).
• Tango – display_name, federal_obligations (derived from award data), relationships.

Usage Notes¶

• Use uei for lookups – All entity endpoints accept UEI; it is case-insensitive.
• Use shape for large responses – Request only the fields you need to reduce payload size.
• Scoped award endpoints – Use /api/entities/{uei}/contracts/, .../idvs/, etc., for awards tied to an entity; see Entities API Reference.
• Address key normalization – Address subfields are always returned in snake_case (address_line1, state_or_province_code, zip_code), regardless of how the data was originally stored.
• Business type normalization – business_types(*) and sba_business_types(*) always return [{code, description, ...}] arrays, even when the source data uses dict format.