Organizations Data Dictionary¶

This document describes the fields available in the Organizations API endpoint (/api/organizations/).

Overview¶

The Organizations resource provides a unified view of federal government organizations, consolidating data from multiple authoritative sources into a single hierarchical structure. Organizations include departments, agencies, sub-agencies, and offices.

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¶

All organization data is updated monthly via the sync_organizations management command.

Fields¶

Field	Type	Description	Source
`key`	UUID	Primary identifier for the organization in Tango. This is a stable UUID that can be used for referencing organizations across API calls.	Tango
`fh_key`	BigInteger	The Federal Hierarchy's unique `orgKey` identifier from SAM.gov. This links organizations to the authoritative federal hierarchy structure. May be null for organizations that exist only in USASpending or legacy FPDS data.	Federal Hierarchy (SAM.gov)
`name`	String	The full official name of the organization (e.g., "Federal Emergency Management Agency").	Federal Hierarchy (SAM.gov)
`short_name`	String	The abbreviated or common name of the organization (e.g., "FEMA", "DHS").	Federal Hierarchy (SAM.gov)
`type`	String	The organizational type within the federal hierarchy (e.g., "DEPARTMENT", "AGENCY", "OFFICE").	Federal Hierarchy (SAM.gov)
`level`	Integer	The depth level in the organizational hierarchy. Level 1 represents top-level departments, with higher numbers indicating deeper nesting.	Federal Hierarchy (SAM.gov)
`cgac`	String	Common Government-wide Accounting Classification code. A 3-character code used for financial reporting (e.g., "069" for Department of Transportation).	USAspending
`fpds_code`	String	Federal Procurement Data System code. A 4-digit agency identifier used in contract transactions.	USAspending
`fpds_org_id`	String	Alternative FPDS organization identifier. May be present when `fpds_code` is not available or for additional organization matching.	USAspending
`code`	String	Office or agency code. Used to identify specific offices within agencies, particularly in contract and financial assistance transactions.	Federal Hierarchy / USAspending
`is_active`	Boolean	Indicates whether the organization is currently active. Derived from the `mod_status` field in Federal Hierarchy.	Federal Hierarchy (SAM.gov)
`parent_fh_key`	BigInteger	The Federal Hierarchy `fh_key` of this organization's parent organization. Null for top-level departments.	Federal Hierarchy (SAM.gov)
`full_parent_path_name`	String	A human-readable path showing the full hierarchy from the top-level department to this organization, separated by " > " (e.g., "Department of Homeland Security > Federal Emergency Management Agency").	Federal Hierarchy (SAM.gov)
`mod_status`	String	The modification status of the organization in the Federal Hierarchy (e.g., "ACTIVE", "INACTIVE").	Federal Hierarchy (SAM.gov)
`description`	String	A description of the organization's mission or purpose, when available.	Federal Hierarchy (SAM.gov)
`obligations`	Float	Total federal contract and financial assistance obligations associated with this organization and all its descendants (rolled up from the entire subtree). This is an alias for `tree_obligations`. Expressed in US dollars.	USAspending
`obligation_rank`	Integer	A percentile ranking (1-100) of this organization's obligations relative to other organizations. Higher values indicate larger obligation amounts.	Calculated
## Organization Types

Organization types define the position of an organization within the federal hierarchy. Each type corresponds to a specific hierarchy level:

Type	Level	Description
`DEPARTMENT`	1	Top-level federal departments (e.g., Department of Defense, Department of Health and Human Services)
`AGENCY`	2	Major sub-components of departments (e.g., Department of the Army, Food and Drug Administration)
`OFFICE`	3+	Sub-agencies, bureaus, and offices at various depths within the hierarchy

Expansions¶

The following expansions are available via the shape query parameter to include related data:

`parent`¶

Returns the immediate parent organization with the following fields: - key - fh_key - name - short_name - type - level - is_active

`ancestors`¶

Returns a list of all ancestor organizations from the top-level department down to the immediate parent. Each ancestor includes: - fh_key - name - short_name

`children`¶

Returns a list of immediate child organizations. Each child includes: - key - fh_key - name - short_name - type - level - is_active

Data Sources¶

Organization data is consolidated from multiple authoritative sources with a priority-based system:

Federal Hierarchy (SAM.gov) - The authoritative source for federal organization structure. Provides the canonical hierarchy, names, and parent-child relationships.
USAspending - Supplements Federal Hierarchy with operational codes (CGAC, FPDS codes) and obligation data that appear in financial transactions.
Legacy FPDS - Historical organization data from the Federal Procurement Data System, used to backfill organizations that appear in contract transactions but are missing from current reference sources.

Higher-priority sources are never overwritten by lower-priority ones, ensuring that Federal Hierarchy's authoritative structure is preserved while other sources fill in the gaps.

Example Response¶

The following example shows a response using the shape parameter to include all available fields:

{
  "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fh_key": 100012345,
  "name": "Federal Emergency Management Agency",
  "short_name": "FEMA",
  "type": "AGENCY",
  "level": 2,
  "cgac": "070",
  "fpds_code": "7022",
  "fpds_org_id": "7022",
  "code": "7022",
  "is_active": true,
  "parent_fh_key": 100000123,
  "full_parent_path_name": "Department of Homeland Security > Federal Emergency Management Agency",
  "mod_status": "ACTIVE",
  "description": "FEMA's mission is helping people before, during, and after disasters.",
  "obligations": 25000000000.00,
  "obligation_rank": 85
}

Note: To retrieve all fields, use the shape query parameter: /api/organizations/?shape=key,fh_key,name,short_name,type,level,cgac,fpds_code,fpds_org_id,code,is_active,parent_fh_key,full_parent_path_name,mod_status,description,obligations,obligation_rank

Usage Notes¶

Use key for API references - The UUID key is the primary identifier for the Organizations API and should be used when storing references to organizations.
Use fh_key for Federal Hierarchy lookups - When cross-referencing with SAM.gov or other federal data sources that use the Federal Hierarchy, use fh_key.
Use code lookups for transaction matching - When matching contract or financial assistance transactions, use the specific code type (cgac, fpds_code, code) that appears in your source data.
Use the search parameter for discovery - The /api/organizations/?search= endpoint handles abbreviations, acronyms, typos, and contextual queries (e.g., "Treasury OIG").