Organizations Data Dictionary¶

This document describes the fields available in the Organizations API endpoint (/api/organizations/). For filtering, ordering, and pagination, see the Organizations API Reference.

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. Without a ?shape= parameter, a default shape is applied. See Response Shaping for details.

Update Frequency¶

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

Default Shape¶

All responses go through the shaping pipeline. When no ?shape= parameter is provided, the following fields are returned:

key, fh_key, name, short_name, type, level, is_active, code, fpds_code, cgac, canonical_code, parent_fh_key, full_parent_path_name

Fields¶

Usage Notes¶

• The Organizations API lookup key is fh_key (Federal Hierarchy orgKey), returned as a zero-padded 9-character string.
• The fh_key is intended for "current" lookups, but it is not a stable globally-unique identifier across all historical snapshots/versions.
• If you need to track historical versions, use the internal key (UUID) plus timestamps/versions (Tango stores org history separately).

Organization Types¶

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

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 (zero-padded)
• name
• short_name
• type
• level
• is_active
• code
• cgac

ancestors¶

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

• fh_key (zero-padded)
• name
• short_name
• level

children¶

Returns a list of immediate child organizations (prefetched for performance). Each child includes:

• key
• fh_key (zero-padded)
• name
• short_name
• type
• level
• is_active
• code
• cgac

department¶

Returns the L1 (department-level) ancestor formatted as a legacy-compatible department object. Returns null for level 1 organizations (a department doesn't have a department — it is one).

• code — the department's CGAC code
• name — the department's full name
• abbreviation — the department's short name / abbreviation

agency¶

Returns the L2 (agency-level) ancestor formatted as a legacy-compatible agency object. Returns null for level 1 and 2 organizations (no agency above them).

• code — the agency's FPDS code
• name — the agency's full name
• abbreviation — the agency's short name (resolved via cached lookup)

Data Sources¶

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

1. Federal Hierarchy (SAM.gov) - The authoritative source for federal organization structure. Provides the canonical hierarchy, names, and parent-child relationships.

2. USAspending - Supplements Federal Hierarchy with operational codes (CGAC, FPDS codes) and obligation data that appear in financial transactions.

3. 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 default response (no ?shape= parameter):

{
  "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fh_key": "100012345",
  "name": "Federal Emergency Management Agency",
  "short_name": "FEMA",
  "type": "AGENCY",
  "level": 2,
  "is_active": true,
  "code": "7022",
  "fpds_code": "7022",
  "cgac": "070",
  "canonical_code": "L2:7022",
  "parent_fh_key": "100000123",
  "full_parent_path_name": "Department of Homeland Security > Federal Emergency Management Agency"
}

The following example shows a shaped response with legacy-compatible expands:

/api/organizations/?shape=fh_key,name,type,department(code,name),agency(code,name,abbreviation)&level=3

{
  "fh_key": "047020017",
  "name": "FA8219 AFLCMC EGLIN",
  "type": "OFFICE",
  "department": {
    "code": "097",
    "name": "DEPT OF DEFENSE"
  },
  "agency": {
    "code": "5700",
    "name": "DEPT OF THE AIR FORCE",
    "abbreviation": "USAF"
  }
}

Usage Notes¶

• Use fh_key for API lookups — The Organizations API uses fh_key in the detail URL: GET /api/organizations/{fh_key}/. The fh_key is returned as a zero-padded 9-character string (e.g., "000000001").
• Use key as an internal identifier — key is Tango's internal UUID primary key and may be useful for internal joins/debugging.
• 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").
• Level behavior for department/agency expands — The department expand is defined for level 2+ orgs; the agency expand is defined for level 3+ orgs. When these expands are requested on orgs below the applicable level, the corresponding field is included in the response as null (no error is raised). Filter by level if you want to avoid null values in list responses.