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)¶

From src/entities/loaders/maps.py:

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

Address data from different sources (SAM uses snake_case, DSBS uses camelCase) is automatically normalized to the canonical snake_case format above.

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, uei, display_name

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 django-genc (GENC country names)
• 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 – Description, capabilities, keywords, SBA business types (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.