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.

TL;DR:

The Agency Crosswalk answers "I see DOD in my data, what's the standard name?" The Federal Hierarchy answers "What's the structure under Department of Defense, and what's its CGAC code?" Crosswalk is observed name variants → canonical. Federal Hierarchy is SAM's authoritative org tree with structure and codes. They're complementary, not redundant.

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

	Agency Crosswalk	Federal Hierarchy
Answers	"Is DOD the same as DEPT OF DEFENSE?"	"What's the structure under DoD, and what's its CGAC?"
Source	Observed variants across our opportunity corpus, joined with Federal Register canonical names and USAspending toptier codes.	SAM.gov's authoritative master Federal Hierarchy.
Records	~3,600 variant mappings	907 organizations
Endpoint	GET /api/agency-crosswalk	GET /api/v1/federal-hierarchy/ + lookup by ID
Refresh	Nightly (rebuilt from current opportunity data)	Monthly (refreshed from SAM source)
Best for	Display/normalize agency names you've already seen	Hierarchy queries, structural lookups by code, getting alternative names
Tier	Free, no auth	Free tier (auth'd API key)

When to use Agency Crosswalk

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

• An opportunity record carries the whole contracting-office path in one string, such as "DEPT OF DEFENSE.DEFENSE LOGISTICS AGENCY.DLA MARITIME.DLA MARITIME COLUMBUS.DLA LAND AND MARITIME", and you want the canonical DEFENSE LOGISTICS AGENCY to group or display by.
• 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.

curl https://govconapi.com/api/agency-crosswalk | jq '.data[0]'
{
  "raw_agency_text": "DEPT OF DEFENSE",
  "canonical_agency": "DEPT OF DEFENSE",
  "canonical_acronym": "9700",
  "department": "DEPT OF DEFENSE",
  "fh_level": "sub_tier",
  "usaspending_toptier_code": "097",
  "confidence": 1.0,
  "frequency": 14328,
  "federal_hierarchy": {
    "organization_id": 100000000,
    "cgac": "097",
    "type": "DEPARTMENT"
  }
}

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."

# List all DEPARTMENT-level organizations
curl -H "Authorization: Bearer $GOVCONAPI_KEY" \
  "https://govconapi.com/api/v1/federal-hierarchy/?type=DEPARTMENT&limit=10"

# Detail for Department of Defense (organization_id from crosswalk)
curl -H "Authorization: Bearer $GOVCONAPI_KEY" \
  "https://govconapi.com/api/v1/federal-hierarchy/100000000"

# Immediate children of DoD (DARPA, DCAA, DLA, DFAS, ...)
curl -H "Authorization: Bearer $GOVCONAPI_KEY" \
  "https://govconapi.com/api/v1/federal-hierarchy/100000000/children"

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 (every agency string we have seen). 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; their cheapest paid plan is $100/mo (Small, 1,500 requests/day), verified 2026-08-31. 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.

Build with this data.

Both are documented endpoint by endpoint: the agency crosswalk endpoint for normalizing a raw agency string, and the Federal Hierarchy list endpoint for searching the organization tree. The Agency Crosswalk is free with no auth. The Federal Hierarchy needs a free API key, available on the pricing page.