Federal Hierarchy vs Agency Crosswalk

GovCon API exposes two related-but-different tools for federal agency data. They sound similar, so this page explains exactly when to use each, where they overlap, and the two-step pattern that uses them together.

The problem both tools solve

Federal agencies have spellings, codes, abbreviations, and dotted-path representations that vary across data sources. The same office shows up in different SAM feeds as DEPT OF DEFENSE, DoD, Department of Defense, 9700, 097, or a multi-level path like DEPT OF DEFENSE.DEFENSE LOGISTICS AGENCY.DLA AVIATION.DLA AV RICHMOND. Most APIs surface one of these representations as a raw string and leave normalization to you.

GovCon API exposes two complementary tools so you don't have to build that normalization yourself.

Side-by-side

When to use Agency Crosswalk

You have a string in your data and need to know its standard form. Common situations:

• An opportunity record has agency: "DOD" and you want to display "Department of Defense" instead.
• You're matching opportunities against a CRM that uses Federal Register canonical names.
• You want USAspending's toptier_agency_code from a SAM agency name.
• You need the frequency of each spelling variant to understand how messy your input data is.

Notice the federal_hierarchy sub-object. After January 2026, every crosswalk row that resolves to a SAM Federal Hierarchy entry (about 99.6%) includes the organization_id you can pass to the Federal Hierarchy endpoint for the full structure.

When to use Federal Hierarchy

You're working with structure, not just names. Common situations:

• "Show me all sub-agencies under Department of Defense" (traverse the hierarchy).
• "What's the official short name for CGAC 097?" (DOD).
• "What are the alternative spellings of this organization?" (returns the array used by SAM internally).
• "Walk the ancestor chain for a deep sub-office."

The two-step pattern

The crosswalk and the hierarchy work best together. Start from a raw agency string, canonicalize through the crosswalk, then traverse through the hierarchy.

1. Crosswalk: send the raw string you have (e.g. DOD or DEPT OF DEFENSE.DEFENSE LOGISTICS AGENCY.DLA AVIATION) and read the response.
2. Read the federal_hierarchy.organization_id from the crosswalk response.
3. Hierarchy: call GET /api/v1/federal-hierarchy/{organization_id} to get the structured record, children, and ancestor chain.

You now have the official short name, CGAC code, alternative spellings, and full position in the org tree, derived from a raw string you didn't know how to interpret.

Where they overlap

• Both produce a canonical agency name. The crosswalk's canonical is sourced from Federal Register; the hierarchy's is from SAM master. These agree for the vast majority of records (~99.6% match rate). When they disagree, the hierarchy is authoritative.
• Both expose a CGAC. The crosswalk includes usaspending_toptier_code (matches CGAC for most agencies). The hierarchy exposes cgac directly.
• Both are free.

Where they differ

• The crosswalk only knows about agencies that have appeared in our ingested opportunity data (top 2,000 by frequency). The hierarchy includes every federal organization SAM tracks, including ones that haven't posted opportunities yet.
• The crosswalk gives you a flat string mapping. The hierarchy gives you parent/child relationships, hierarchy depth, dotted-path codes, and alternative spellings as a structured array.
• The crosswalk uses heuristic name matching (string similarity, manual mappings). The hierarchy is deterministic, sourced from SAM's authoritative master.

Comparable products

Tango's /api/organizations/ exposes a similar Federal Hierarchy view at $25/mo (Tango Micro). HigherGov gates equivalent structural lookups inside their $500/yr Starter bundle. GovCon API exposes this on the free tier as foundational reference data, because the value of the API surface should be in the data layer above it (opportunities, awards, subawards, vendor risk).

Limitations and edge cases

• About 0.4% of crosswalk rows don't resolve to a Federal Hierarchy entry. These are typically minor commissions, councils, or historical orgs that exist in Federal Register but aren't in SAM's master Federal Hierarchy. The crosswalk still returns them with federal_hierarchy: null.
• The hierarchy index has just two type values today (DEPARTMENT, AGENCY). SAM's underlying data implies finer types (offices, sub-commands, bureaus) but the public fh index only exposes the top two.
• Hierarchy depth is shallow (mostly 1-2 levels). Deeper org structure visible in opportunities.agency dotted paths isn't fully captured in the public hierarchy index.