GovCon API Documentation

GET /api/agency-crosswalk No Auth Required

Free agency name standardization utility. Returns mappings between agency variants and canonical names, with department hierarchy and USASpending codes.

Data: Generated fresh from current contract database. Includes 2,000+ agency mappings with confidence scores.

Response Format

Example

GET /api/v1/opportunities/{notice_id} Requires Auth

Fetch one complete opportunity by its 32-character notice_id. Use it when you already hold a notice_id (from search results, a sam.gov URL, or your own store) and want the full record.

Parameters

• notice_id (path) — a 32-character hex string (regex ^[a-f0-9]{32}$, case-insensitive). Example: 00016e91148440e0b80537f6362f45ea.

No query parameters are accepted; field projection via ?fields= is not available on this endpoint (the full record is always returned).

Response Format

The record is wrapped under opportunity, with two metadata fields alongside it:

• opportunity — the same 59-field record returned by search. Reminders from the search domain primer: naics / psc are arrays; description_text is tri-state (real text / "NO_DESCRIPTION_AVAILABLE" / null); active is always "Yes" by design; set_aside_type "none" is tri-state.
• has_raw_data — true if the original SAM payload is retained for this notice (available for notices ingested through the live pipeline; older backfilled rows may be false).
• last_updated — when this notice last changed in our database. Same value /opportunities/delta sorts and filters on.

Errors

• 400 — path is not 32-char hex (e.g. a solicitation number passed by mistake). Returns a structured body with a hint_url pointing to the search endpoint so the caller can recover programmatically.
• 404 — well-formed id, no such notice in our database. Body: {"detail": "Opportunity not found"}.
• 429 — rate limit exceeded.

Sample 400 body when a solicitation number is passed instead of a notice_id:

Example

Note: description_text: null does not mean "no description exists." It means enrichment has not run for this notice yet (rare on notices older than a day). Re-fetch later, or check the live description_url.

Worked example: an EPA Region 1 procurement (real)

Calling GET /api/v1/opportunities/0035baae11ef4760b1157425704b23c2 returns the EPA Region 1 Contracting Office's notice "H--Proficiency Testing (PT) Samples" for the New England Regional Laboratory at North Chelmsford, MA. Live response excerpt (verified 2026-06-02):

One detail call delivers the procurement context (agency hierarchy, NAICS, PSC, solicitation number), the awarding officer (name, email, phone), the place of performance (lab address), the lifecycle markers (posted_date, response_deadline, archive_date_detailed), and the SAM last_updated stamp. Per the active column is "Yes" by design rule, "active": "Yes" here even though the notice has archived; the canonical "is it currently open" answer is archive_date_detailed compared against today.

GET /api/v1/opportunities/{notice_id}/attachments Requires Auth

Return the downloadable attachment URLs (solicitation PDFs, drawings, statements of work, amendments) for one notice. URLs are direct SAM.gov download links you can hand to a browser or HTTP client; we do not proxy them.

Parameters

• notice_id (path) — same 32-character hex rule as /opportunities/{notice_id}. A solicitation number returns the same structured 400 with a hint_url.

No query parameters are accepted.

Response

• attachment_count — length of attachments. Often 0; many notices carry their documents as external links or have no files at all.
• attachments — array of canonical SAM.gov download URLs. Same data as resource_links_array on the main opportunity record. An empty array ([]) is returned when a notice has none.

This is the same data the search filter has_attachments reads, so the two stay consistent: has_attachments=true on search selects notices where this array is non-empty.

Finding notices that have attachments

There is no list endpoint; look them up per notice. Filter search first, then fetch attachments for each id:

Downloading the files

Each URL is a SAM.gov "front-door" link. When a client follows it, SAM 303-redirects to a short-lived signed S3 URL and the file streams from there. Three practical notes:

• Use GET with redirect-follow, not HEAD. AWS pre-signed URLs scope the signature to the GET method; a HEAD against the resolved S3 URL returns 403.
• Do not cache the resolved S3 URL. The signature has a very short expiry. Re-hit the SAM URL each time you need the file.
• Allow *.s3.amazonaws.com through proxies / firewalls. If a corporate proxy blocks S3, the redirect lands on a host that fails to load.

Errors

• 400 — path is not 32-char hex (e.g. a solicitation number). Structured body with hint_url to the search endpoint, same shape as /opportunities/{notice_id}.
• 404 — well-formed id, no such notice. Body: {"detail": "Opportunity not found"}. A notice that exists but has no files returns 200 with attachment_count: 0, not 404.
• 429 — rate limit exceeded.

Example

Freshness: the array is rebuilt periodically from the source; a brand-new notice may briefly show 0 before its files are picked up, even when SAM already has them.

GET /api/v1/stats Requires Auth

Get comprehensive database statistics including total records, recent activity, unique agencies and NAICS codes.

Response

Note: All values shown are examples. Use the endpoint to get current statistics.

Example

GET /api/stats No Auth Required

Public statistics endpoint for landing page. Returns real-time counts computed from database.

Response

Note: All values shown are examples. Use the endpoint to get current statistics.

Field Descriptions

• total_notices - Total contract notices in database (all types, never archived)
• currently_open - Notices still accepting bids (deadline > now, not yet awarded)
• award_records - Notices with award information (winner, amount, date)
• full_descriptions - Notices with complete extracted requirement text from SAM.gov

Example

GET /meta No Auth Required

Get metadata about the dataset including last collection time and total record count.

Response

Example

Note: Use this endpoint to check data freshness. Collection runs daily at 2:00 AM UTC. The records value shown is an example - use the endpoint to get the current count.

GET /api/v1/me Requires Auth

Get information about your API key: plan, entitlements, current rate-limit state, and your effective historical search window. A good first authenticated call to confirm your key works (it requires no other parameters).

Response

• plan / contacts_access — your tier and whether Pro Contacts/Companies/Vendor-Risk features are enabled.
• rate_limit / rate_limit_remaining — your hourly ceiling and what's left this window (also returned as X-RateLimit-Limit / X-RateLimit-Remaining headers on every response).
• historical_window_days / historical_earliest_allowed — the effective search window applied to /opportunities/search, /awards/search, and /export.csv.

Example

GET /api/v1/contracts/search Requires Auth

Search federal prime contract transactions. Every base award and every modification is one row, sourced from the federal procurement system of record (FPDS) for award types A, B, C, and D. Coverage today is FY2025 + FY2026 (action dates from October 2024 onward).

Parameters

At least one of uei, parent_uei, piid, parent_piid, agency, or naics is required. Unknown parameters return 400.

• uei — recipient UEI, 12 characters, exact match (case-insensitive).
• parent_uei — recipient parent UEI for corporate roll-up across subsidiaries.
• piid — Procurement Instrument Identifier, exact match.
• parent_piid — parent vehicle (IDV) PIID.
• agency — awarding agency name substring, case-insensitive. defense matches every DoD sub-agency.
• naics — exactly 6 digits.
• award_type_code — one of A (BPA Call), B (Purchase Order), C (Delivery Order), D (Definitive Contract). Not a substantive filter on its own; combine with one of the above.
• date_from / date_to — YYYY-MM-DD bounds on action_date. Older dates are soft-clamped to the coverage floor; the clamp is surfaced in the window block.
• amount_min / amount_max — bounds on federal_action_obligation. 0 is honored. Accepts value_min / value_max as aliases.
• sort_by — one of action_date (default), federal_action_obligation, current_total_value_of_award, recipient_name.
• sort_order — asc or desc (default).
• limit — 1 to 250, default 50.
• offset — pagination offset.
• fields — lean (default, 26 fields), expanded (57 fields), full (every column), or a comma-separated list.

Response

Standard list envelope: data, pagination, filters_applied, window, and _sources. pagination.total is exact (no estimate cap). Each row in data is one FPDS transaction. _sources is ["usaspending_fpds"].

Example

GET /api/v1/contracts/{piid} Requires Auth

Single contract by PIID. Returns the latest transaction (the contract block, 26 lean fields by default) plus a transaction_rollup sibling that aggregates obligations, ceiling, distinct recipients, and action-date bounds across every transaction under that PIID. Pro responses also include a subaward_rollup sibling.

Parameters

• piid (path) — Procurement Instrument Identifier, upper-cased server-side.
• fields — lean / expanded / full / comma list, applies to the contract block. transaction_rollup is fixed shape.

Response

Reading the numbers

The example above is the live shape for Deloitte's $392M Army task order under PIID W56JSR23F0062. Two customer-actionable signals are in the rollup directly: transaction_count: 52 over a 16-month action-date span says the prime has cycled 52 mods (active, well-managed contract). max_current_total_value and latest_current_total_value agree at $392.56M (current ceiling matches the all-time peak, scope stable). max_potential_total_value at $504.35M agrees with latest_potential_total_value at the same number, but when these two differ in a live response, that is a scope-reduction signal worth chasing in a recompete play (a previous mod set a higher ceiling than the current one). Customers tracking ceilings over time read both pairs and compare.

Errors

• 404 — no contract with that PIID in the coverage window.
• 429 — rate limit exceeded.

Subaward enrichment Pro

On Pro keys, the response includes an additional subaward_rollup sibling summarizing the FFATA subaward footprint flowing from this prime contract: sub count, total subcontracted, share of the prime obligation, distinct sub-vendor count, first and last subaward dates, plus up to 5 named top_subs. The PIID join into the subaward layer is dense within the FY2025+ window: roughly 88% of subaward filings match a prime contract row, and 98% of in-scope contracts that have subaward activity see a populated block. _sources extends to ["usaspending_fpds", "usaspending_ffata"] when the block fires. For UEI-keyed reverse lookups across every contract a recipient holds, use /api/v1/companies/{uei}/subawards.

Example

GET /api/v1/contracts/{piid}/modifications Requires Auth

Full transaction history for one PIID, oldest action first. Every row is a single FPDS action: base award, exercised options, supplemental agreements, partial terminations, administrative cleanup. Use this to reconstruct what happened on a contract over its life.

Not date-windowed. When you ask for one PIID's history, you get the full history we carry, regardless of the search-time coverage window.

Parameters

• piid (path) — Procurement Instrument Identifier.
• limit — 1 to 500, default 100. Higher cap than search because modification trails are bounded.
• offset — pagination offset.
• fields — same options as search.

Response

Returns piid, data (ASC-ordered by action_date then modification_number), pagination, and _sources. 404 when no transactions exist for the PIID.

Example

GET /api/v1/grants/search Requires Auth

Search federal financial-assistance award transactions: block grants, formula grants, project grants, and cooperative agreements (assistance types 02-05), sourced from USAspending. This is the grant side of federal spending, money to states, universities, hospitals, nonprofits, tribes, and local governments, distinct from the contract (FPDS) side. Every base award and every modification is one row. Coverage today is FY2025 + FY2026 (action dates from October 2024 onward).

Parameters

At least one of uei, parent_uei, fain, agency, cfda, recipient_name, recipient_state, or funding_opportunity is required. recipient_type and assistance_type_code are refinements and do not satisfy the requirement on their own. Unknown parameters return 400.

• uei — recipient UEI, 12 characters, exact match. The same UEI joins into contracts and companies, so one organization's grants and contracts line up.
• parent_uei — recipient parent UEI for corporate roll-up.
• fain — Federal Award ID Number, exact match. Not unique across recipients/years; to pull one specific award use the detail endpoint with the award key.
• agency — awarding agency name substring, case-insensitive.
• cfda — CFDA / Assistance Listing number, exact (e.g. 93.778).
• assistance_type_code — 02 (Block grant), 03 (Formula grant), 04 (Project grant), 05 (Cooperative agreement). Refinement only.
• recipient_name — recipient name substring, case-insensitive (minimum 3 characters).
• recipient_state — recipient state: 2-letter code (exact) or full name (prefix).
• recipient_type — plain-language recipient bucket: higher_education, nonprofit, state_government, local_government, school_district, tribal, small_business, for_profit, individual. Refinement only.
• funding_opportunity — funding-opportunity (NOFO) number, exact.
• date_from / date_to — YYYY-MM-DD bounds on action_date. Older dates are soft-clamped to the coverage floor (surfaced in the window block).
• amount_min / amount_max — bounds on federal_action_obligation. 0 is honored. Accepts value_min / value_max as aliases.
• sort_by — one of action_date (default), federal_action_obligation, total_obligated_amount, recipient_name.
• sort_order — asc or desc (default).
• limit — 1 to 250, default 50.
• offset — pagination offset.
• fields — lean (default, 24 fields), expanded (~50 fields), full (every column), or a comma-separated list.

Two amounts, two meanings (read this)

Each row carries both federal_action_obligation (what this transaction obligated, sum it to total a recipient, program, or window) and total_obligated_amount (the award's lifetime cumulative, repeated on every transaction of that award, never sum it across rows). Conflating them is the most common grant-data mistake. De-obligations carry a negative federal_action_obligation; summing nets them out correctly, so do not filter negatives away.

Response

Standard list envelope: data, pagination, filters_applied, window, and _sources (["usaspending_fabs"]). pagination.total is exact. Each row is one transaction.

Example

GET /api/v1/grants/{award_key} Requires Auth

Single grant award by assistance_award_unique_key (the unambiguous award id that also appears in the USAspending permalink, e.g. ASST_NON_4683DRCAP00000001_070). Returns the latest transaction (the grant block, lean fields by default) plus a transaction_rollup sibling aggregating obligations, outlays, program count, and action-date bounds across every transaction under that award. Use the award key, not the FAIN, since a FAIN can recur across recipients and years.

Response

Reading the numbers

The example is the live shape for a California FEMA disaster-recovery grant (CFDA 97.036). transaction_rollup.total_obligated ($312.3M) is the sum of federal_action_obligation across this award's 1,409 transactions in our coverage window; award_total_obligated_amount ($403.7M) is the award's lifetime cumulative carried verbatim from USAspending, so the roughly $91M gap is obligation that predates our FY2025+ coverage; award_total_outlayed ($264.3M) is money actually disbursed. To answer "how much has this grant obligated to date," read the award figure; to answer "how much landed in my window," read the rollup sum.

Errors

• 404 — no award with that key.
• 429 — rate limit exceeded.

Example

GET /api/v1/grants/{award_key}/modifications Requires Auth

Full transaction history for one award, oldest action first. Every row is a single assistance action: the base obligation, added funding, de-obligations, administrative corrections. Not date-windowed, when you ask for one award's history you get the full history we carry.

Parameters

• award_key (path) — the assistance_award_unique_key.
• limit — 1 to 500, default 100. Higher cap than search because one award can carry hundreds of modifications.
• offset — pagination offset.
• fields — same options as search.

Response

Returns award_key, data (ASC by action_date then modification_number), pagination, and _sources. 404 when no transactions exist for the award.

Example

GET /api/v1/companies/{uei}/grants Requires Auth

Every grant a recipient received, by UEI, plus a summary and its top programs. The reverse lookup over /grants/search for one recipient.

Response

Returns uei, a summary (total obligated, distinct awards, distinct programs, distinct agencies, first/last action date, and a top_programs CFDA breakdown ranked by dollars), then the standard data / pagination / filters_applied / window / _sources. summary.total_obligated sums federal_action_obligation, so a program whose only in-window action was a de-obligation shows a negative total and the sum is the net.

Parameters

• uei (path) — recipient UEI.
• date_from / date_to, sort_by, sort_order, limit, offset, fields — same as search.

Example

GET /api/v1/grant-opportunities/search Requires Auth

Search federal grant opportunities (grants.gov notices of funding opportunity), the open funding you can still apply for, the forward-looking counterpart to grant awards. The full corpus is searchable (open, forecasted, closed, archived); status is derived live from the dates, so the default search returns the actionable set (open + forecasted) and "open" means open today, not a stale flag.

Parameters

Open + forecasted is browseable without a filter; reaching into closed, archived, or all requires at least one of keywords, agency, or cfda. Unknown parameters return 400.

• keywords — full-text over title + description.
• agency — awarding agency code or name substring, case-insensitive.
• cfda — CFDA / Assistance Listing number, exact, array-contains (e.g. 93.213). The same number joins to /grant-programs/{cfda} and to grant awards.
• eligibility — plain-language applicant bucket: for_profit, small_business, nonprofit, government, tribal, higher_education, individual, unrestricted. Resolved to grants.gov applicant-type codes; the ambiguous "Others (see text)" code is excluded from the for-profit/small-business buckets.
• funding_category — category-of-funding-activity code (e.g. ST science/technology, HL health, ED education); array-contains.
• funding_instrument — G (grant), CA (cooperative agreement), PC (procurement contract), O (other).
• status — open, forecasted, closed, archived, or all. Default: open + forecasted. Derived live from post_date / close_date / archive_date.
• date_from / date_to — YYYY-MM-DD bounds on close_date (the deadline axis).
• posted_after / posted_before — YYYY-MM-DD bounds on post_date.
• value_min / value_max — award-range overlap: value_min matches award_ceiling, value_max matches award_floor. 0 honored. Accepts amount_min / amount_max as aliases.
• sort_by — close_date (default), post_date, award_ceiling, opportunity_title, last_updated_date.
• sort_order — asc (default; soonest deadline first) or desc.
• limit — 1 to 250, default 50. offset — pagination offset.
• fields — lean (default), expanded, full, or a comma-separated list.

Response

Standard list envelope: data, pagination (exact total), filters_applied (echoes the effective status), and _sources (["grants_gov"]). No window block, this surface is not date-windowed. Each row carries a derived status; a null close_date is a rolling deadline (treated as open), not missing data; a notice has no recipient (there is no winner until it is awarded).

Example

GET /api/v1/grant-opportunities/{opportunity_id} Requires Auth

The full notice by opportunity_id: title, agency, eligibility, award range, funding instrument, dates, the agency point of contact, the description, and the CFDA program(s). On Pro keys the response also carries a program_intel block inline (the same data as /grant-programs/{cfda}), so one call tells you both what the notice is and whether the program is worth pursuing; on non-Pro keys that block is a short {"locked": true} stub with no award data.

Response

A flat opportunity object plus the program_intel sibling and _sources (["grants_gov"], or ["grants_gov","usaspending_fabs"] when the program intel joins award history). 404 on an unknown id; not date-windowed.

Example

GET /api/v1/grant-programs/{cfda} Pro

Program competitive intelligence: for a CFDA program, who has historically won it, whether it is a genuine open competition or wired to a few incumbents, and the realistic award size, joined from the federal grant-award record on the same program number. This answers the question a notice never does, "is this worth a proposal?", before you write one. Pair it with /grant-opportunities/search?cfda=... to see what is open under the program now.

Response

Returns cfda, a program_intel block, the open_opportunity_count currently open under the program, and _sources (["grants_gov","usaspending_fabs"]). Inside program_intel: distinct_awards, distinct_recipients, total_obligated, median_award (the realistic ask when a notice omits the ceiling), top_recipient_share and top5_recipient_share (the single / top-five recipients' share of gross obligated dollars, bounded 0-1; near 0 = open field, near 1 = wired to incumbents), and incumbents (top recipients by dollars). A program with no award history returns the block with nulls and has_award_history: false.

Errors

• 402 — Pro plan required.
• 422 — cfda is not a valid Assistance Listing number (format NN.NNN).

Example

GET /api/v1/awards/search Requires Auth

Search federal contract awards as a lean, award-focused list. Filter by awardee name, UEI, agency, NAICS, amount range, date range, or state. Each result is a 16-field record; pair the notice_id with /opportunities/{notice_id} for the full 59-field record when you need more.

How It Works

• All filters on every plan. Unlike opportunities, awards filters are not plan-gated. Plans differ on page size (Free 50, paid 1,000) and rate limit, not filter access.
• Partial matching: awardee_name and agency are case-insensitive substring matches. awardee_name=boeing matches "BOEING DISTRIBUTION SERVICES, INC", "BELL BOEING JOINT PROJECT OFFICE", etc.
• Cross-reference to the full record: every result carries notice_id; pass it to /opportunities/{notice_id} for the complete 59-field record.
• Exact total, no estimate cap. Unlike opportunities search, pagination.total here is an exact count (no total_is_estimate flag). Page-forward math is reliable.

Filter Parameters

• awardee_name — Company name (case-insensitive substring on awardee_name). Alias: name.
• uei — Exact UEI match. Uppercased server-side; lowercase works.
• naics — Exactly 6 digits. 2-5 digit prefix returns 400; a well-formed but nonexistent 6-digit code returns 200 with total=0 (an empty result can mean "bad code," not "no awards").
• agency — Awarding agency, case-insensitive substring on the dotted hierarchy path.
• amount_min — Minimum award_amount (≥ 0). amount_min=0 is applied — it excludes null-amount rows.
• amount_max — Maximum award_amount.
• awarded_after — Awards on or after this calendar date (YYYY-MM-DD). Subject to the plan history window (see note below). Alias: date_from.
• awarded_before — Awards on or before this date (YYYY-MM-DD). Alias: date_to.
• state — Awardee state code (2-letter, uppercased). This is the awardee's HQ state, NOT performance.
• sort_by — award_amount, award_date, awardee_name. Default is award_date. Invalid value returns 400 with the valid list (no silent fallback).
• sort_order — asc or desc (default desc). NULLs sort first on asc, last on desc. Tie-broken by notice_id for stable pagination.
• limit — Page size. Framework floor 1 (limit=0 returns 422); over the plan cap returns 403 (Free 50, paid 1,000). Default 20.
• offset — ≥ 0. Negative returns 422.
• fields — Comma-separated projection; notice_id always included. Unknown name returns 400. See Response Shaping.

This endpoint is subject to the plan history window: awarded_after is injected (when omitted) or clamped (when older than the floor), the same way date_from behaves on opportunities search. Always read filters_applied.awarded_after to see the effective date. Because of the corrupted future-dated rows discussed in the concepts note above, awarded_before does not cleanly cap the top of the result set either — pin both bounds when you need a tight range.

Response (16 fields per award)

Examples

Find awards by company name:

DoD awards over $1M in 2025:

IT services awards in Virginia:

Find all awards for a specific company by UEI:

For FFATA subaward enrichment on a specific contract, use the single-record /awards/{award_number} endpoint; the full prime→sub flow with named sub-vendors is on the dedicated /subawards/* surface.

GET /api/v1/awards/{award_number} Requires Auth

Fetch a single award by its contract / award number (also called the PIID). Returns the most recent record when more than one row shares that number.

Parameters

• award_number (path) — free-form contract / PIID. URL-encode slashes or spaces.

No query parameters are accepted; ?fields= projection is not available on this endpoint.

Response

The record is wrapped under award and contains the same 16 fields as a /awards/search result.

Same data caveats as /awards/search (corrupted dates, amount sentinels, address-laden names, null UEIs). For the full ~59-field record (place of performance, full contacts, links, description, archive dates), take the notice_id from this response and call /api/v1/opportunities/{notice_id}.

Why "most recent if multiple"

One award_number can map to more than one stored row. An award gets modifications over its life, and modified awards sometimes appear as separate rows with the same contract number. This endpoint resolves the ambiguity by returning the latest by award_date (ORDER BY award_date DESC NULLS LAST LIMIT 1). To see every version, list the company's awards via /companies/{uei}/awards, or search by the parent solicitation on opportunities search.

Errors

• 404 — no award with that number. Body: {"detail": "Award not found: {award_number}"}.
• 429 — rate limit exceeded.
• 500 — unexpected. Body: {"detail": "Failed to retrieve award"} (sanitized).

Example

Scope reminder: like all award endpoints, this is SAM Award Notice data, not the full FPDS contract history. See the /awards/search scope note.

Subaward enrichment

For subaward context on a federal prime contract, use the /api/v1/contracts/{piid} endpoint. The PIID-based join through the prime contract layer covers roughly 88% of FY2025+ subaward activity, versus under 1% for the SAM Award Notice slice this endpoint serves.

GET /api/v1/entities/{uei} Requires Auth

Single SAM-registered entity by UEI. Returns the registration block (status, expiration, dates) and the entity block (legal name, address, NAICS, PSC, business-type certifications, CAGE codes). Available on Developer tier; Pro subscribers can use /api/v1/companies/{uei} for the same data merged with award history.

Parameters

• uei (path) - 12-character SAM Unique Entity Identifier. Normalized: lowercase, mixed case, and surrounding whitespace are accepted.

Response

Example

Errors: 401 (no auth), 404 (UEI not in current SAM data), 429 (rate limit).

Use cases: compliance checks before contract signing (registration.active + registration.expiration_date), CRM enrichment, vendor-onboarding form auto-fill, set-aside qualification preview (entity.business_types_labels).

Pro enrichment fields Pro

When the caller has Pro, two families of enrichment fields are added inline alongside the SAM data. Fields are omitted entirely on non-Pro keys; existing Developer-tier integrations see exactly the SAM record above.

FFATA subaward income — what this UEI received as a sub-vendor:

• sub_revenue_total — sum of FFATA dollars received as a sub-vendor within current subaward coverage (FY2025 + FY2026 today; window scales as backfill lands).
• top_paying_primes — up to 10 {uei, name, total, subaward_count} objects, sorted desc by total.

FPDS prime contract activity — what this UEI has been awarded directly as a prime:

• fpds_obligated_total — sum of federal action obligation across every FPDS transaction for this UEI in the FY2025-onward window (since 2024-10-01).
• fpds_distinct_contracts / fpds_transaction_count — count of distinct contracts and total transactions (base awards + every modification).
• fpds_first_action_date / fpds_latest_action_date — ISO date bounds.

Field shapes are documented once at the top of the Endpoints section under Pro enrichment fields (universal pattern).

Worked example (Pro response, both enrichment families present)

Live GET /api/v1/entities/CKV2L9GZKJK3 excerpt (verified 2026-06-01):

For per-record drill-down, use the underlying surfaces: /api/v1/contracts/search?uei=… for every FPDS transaction; /api/v1/companies/{uei}/prime-relationships for every subaward received. The combined prime + sub revenue picture with prime_revenue_share lives on /api/v1/companies/{uei} (also Pro). The bidirectional vendor-risk view (as_prime + as_sub + contract_exposure) lives on /api/v1/vendor-risk/{uei}.

GET /api/v1/entities/by-cage/{cage_code} Requires Auth

Same record as /api/v1/entities/{uei}, keyed by 5-character CAGE code instead of UEI. Adds a queried_cage field at the top of the response so callers can confirm the match. Useful for legacy DoD systems that key on CAGE.

Parameters

• cage_code (path) - 5-character DLA-issued CAGE code. Normalized: lowercase and surrounding whitespace are accepted and converted to uppercase.

Response

Example

Errors: 401, 404 (CAGE not found), 429.

Note: Most entities have one CAGE code. Some large organizations (USPS, large banks) have many - up to 80. The entity.cage_codes array in the response lists all CAGE codes registered to the resolved UEI.

Pro enrichment fields Pro. When the caller has Pro, the response carries the same enrichment families as /entities/{uei} — FFATA subaward income (sub_revenue_total, top_paying_primes) and FPDS prime contract activity (fpds_obligated_total, fpds_distinct_contracts, fpds_transaction_count, fpds_first_action_date, fpds_latest_action_date) — computed against the UEI the CAGE resolves to. See the /entities/{uei} section for worked example and field documentation.

GET /api/v1/entities/search Requires Auth Pro (filters)

Filter-based entity search. Name-only search (q) is available on Developer tier. Multi-filter search (any of naics / state / business_type / active_only) requires Pro. The DSBS replacement: programmatic NAICS x state x certification x active-status filtering across the SAM directory.

Parameters

• q - Name substring (2-250 chars, case-insensitive, trigram-indexed). Developer tier.
• naics - 6-digit NAICS code, no Y/N suffix. Matches both primary_naics and any code in naics_codes[]. Pro tier.
• state - 2-character US state code. Pro tier.
• business_type - 2-3 character SAM business-type code (e.g. 8W = WOSB, QF = SDVOSB, 27 = Self-Cert SDB). Unknown codes return 400. Pro tier.
• active_only - true restricts to registration_status='A'. Pro tier.
• limit - Results per page (1-100, default 20).
• offset - Pagination offset (default 0).
• fields - Comma-separated response fields. uei always included. Example: fields=uei,legal_business_name,primary_naics. See Response Shaping.

At least one of q / naics / state / business_type / active_only must be provided.

Response

The row array is returned under BOTH results AND data (identical contents). Either key is safe to read.

Examples

Errors: 400 (no params provided OR unknown business_type), 401, 402 (Pro filter without contacts_access), 422 (validation), 429.

Note: Results are ranked by name similarity when q is provided; filter-only searches are ordered by legal_business_name. SBA-certified codes (A6=8(a), XX=HUBZone, A4=SBA-SDB) are essentially absent from this dataset; the closest available signals are self-cert variants (27, 8W, QF).

GET /api/v1/entities/expiring Requires Auth Pro

Active SAM registrations expiring within within_days days. Sorted by urgency (most urgent first). Past-due registrations are excluded (their status is 'E'). The renewal-radar use case: compliance dashboards, renewal-reminder SaaS, BD pipelines flagging at-risk leads.

Parameters

• within_days - 1-365, default 60. Days from today to look ahead.
• state - 2-character US state code (optional).
• naics - 6-digit NAICS code, no suffix (optional). Matches both primary_naics and naics_codes[].
• limit - 1-500, default 50.
• offset - Pagination offset (default 0).

Response

The row array is returned under BOTH results AND data (identical contents). Either key is safe to read.

Example

Errors: 401, 402 (not on Pro), 422 (within_days out of 1-365), 429.

Note: days_until_expiration is computed at request time. Cached responses can drift. Sort is fixed at urgency-ascending.

GET /api/v1/federal-hierarchy Requires Auth

Search and filter the SAM Federal Hierarchy: the canonical tree of federal departments, agencies, offices, bureaus, and commands (~907 organizations). Use it to resolve and normalize agency identity, walk the org tree, or join external datasets on Treasury cgac codes. Free on any plan; this is reference data.

Parameters

• type - Org type, uppercased: DEPARTMENT, AGENCY, OFFICE, BUREAU, MAJOR COMMAND, SUB COMMAND, DIVISION.
• cgac - Treasury Common Government-wide Accounting Code, e.g. 097 (DoD), 017 (Navy). Many orgs share a department's cgac.
• parent_id - Filter to immediate children of this organization_id.
• hierarchy_level - Depth; 1 = root department.
• is_active - Defaults to true. Pass is_active=false to include inactive orgs.
• search - Case-insensitive match across canonical name, short name, and alternative names (≥ 2 chars).
• limit - 1-1000, default 50.
• offset - ≥ 0.

Response (list rows, 9 fields)

Example

Note: Both /federal-hierarchy and /federal-hierarchy/ work; no redirect. total is exact. Results ordered by hierarchy_level then canonical_name. Reference data; expect rare changes. Key your joins on organization_id (stable integer).

GET /api/v1/federal-hierarchy/{organization_id} Requires Auth

Look up one federal organization by integer ID, returning its full 17-field record plus its parent, immediate children, and full ancestor chain in a single call. Useful for rendering breadcrumbs, expanding tree nodes, or joining a downstream dataset against the org tree without extra round-trips.

Parameters

• organization_id (path) - Integer org ID. Non-integer returns 422; unknown ID returns 404.

Response

Example

Errors: 401, 404 (unknown ID), 422 (non-integer path), 429.

Note: data is the full 17-field record; parent / children / ancestors are the 9-field list shape. hierarchy_path is the ordered list of ancestor IDs (root first), the same source used to build the inline ancestors array.

GET /api/v1/federal-hierarchy/{organization_id}/children Requires Auth

Return the immediate child organizations of one org (one level down), ordered by name. Use it to expand one node of the tree without pulling the full detail response.

Response

Example

Note: Immediate children only, not the full subtree. A leaf org (or an unknown integer ID) returns { "data": [], "count": 0 } with a 200, not a 404; if you need to confirm the org exists, use the detail endpoint instead.

GET /api/v1/federal-hierarchy/{organization_id}/ancestors Requires Auth

Return the chain of ancestors for one org, ordered root department first down to the immediate parent. Use it to render breadcrumbs ("DEPT OF DEFENSE > DEPT OF THE NAVY > ...") for any organization.

Response

Example

Errors: 401, 404 (unknown org), 422 (non-integer path), 429.

Note: Order is root → immediate parent. Root organizations return { "data": [], "count": 0 }. Unknown IDs return 404 (this endpoint checks existence first, unlike children which returns an empty list).

GET /api/v1/companies/search Requires Auth Pro

Find distinct awardees by name substring or UEI prefix. Returns each company once with aggregate stats, ranked by total award count. Pro only; Developer-tier keys get a 402.

Parameters

• q (required) - Search string, 2-250 chars. Matches against awardee name (case-insensitive substring) and UEI prefix.
• naics (optional) - 6-digit NAICS code. Filters to companies that have actually won at least one award under this NAICS. Non-6-digit values return a 400. Distinct from Federal Contractor Search, which filters by SAM-registration data ("registered for NAICS X" vs "won awards under NAICS X").
• agency (optional) - Top-level agency name (e.g. DEPT OF DEFENSE). Matches the top-level of SAM's dotted agency path. Filters to companies with at least one award from this agency.
• limit - Results per page (1-100, default 20)
• offset - Pagination offset, default 0
• fields - Comma-separated response fields. uei always included. Example: fields=uei,name,total_value. See Response Shaping.

Response

The row array is returned under BOTH results AND data (identical contents — data was added for envelope consistency with other list endpoints; results stayed for backward compatibility). Either key is safe to read.

When naics or agency filters are applied, total_awards / total_value on each result reflect only the subset of awards matching the filter, not the company's full award history. Use GET /api/v1/companies/{uei} for the full profile.

Example

Notes: LIKE wildcard characters (%, _) in the query are escaped. Trigram search matches substrings at any position, so q=ARTIN finds MARTIN MILITARY INC. UEI prefix matching is case-insensitive. Use pagination.total + pagination.has_next to page through deep result sets.

GET /api/v1/companies/{uei} Requires Auth Pro

Combined SAM registration + award profile for one UEI. Returns 200 if either the SAM entity registry or our award data has the UEI; returns 404 only when both miss. Award fields populate when the UEI has at least one Award Notice; otherwise they zero out and the registration / entity blocks still populate.

Parameters

• uei (path) - 12-character SAM Unique Entity Identifier. Normalized: lowercase, mixed case, and surrounding whitespace are accepted.

Response

Example

Use cases: compliance check (registration.active + registration.expiration_date), customer-concentration risk (top_agency_share_pct — single-buyer dependents register near 100), set-aside mix (set_aside_distribution — what % of their wins are SDVOSB / WOSB / 8(a)), pipeline health (awards_last_90d vs awards_last_12mo), capability mapping (top_naics, entity.business_types_labels). UEI normalization: lowercase, mixed case, and surrounding whitespace are accepted.

For SAM-data-only lookups without the award merge, see /api/v1/entities/{uei} (Developer tier).

Subaward revenue fields

The profile carries three subaward fields alongside the prime-award totals (within current subaward coverage — FY2025 + FY2026 today). They surface the "true federal revenue" picture that prime-only data misses — for SMBs in particular, sub revenue is often the larger half:

• sub_revenue_total — total dollars this UEI has received as a sub-vendor (sum of subaward_amount).
• top_paying_primes — up to 10 primes that have paid this UEI as a sub, sorted by total $. Each entry: {uei, name, total, subaward_count}.
• prime_revenue_share — float in [0, 1], the share of this UEI's combined federal revenue that came in as prime contracts (vs subs). Computed as fpds_obligated_total / (fpds_obligated_total + sub_revenue_total), using the FPDS prime obligation total (not the SAM-noticed total_value, which undercounts prime work and would read near 0 for FPDS-active firms). null when neither prime nor sub revenue exists; a pure-prime vendor reads 1.0.

Fields are populated for every UEI we have profile data on; sub_revenue_total and top_paying_primes zero out when no subawards exist (prime_revenue_share then reads 1.0 if the UEI has FPDS prime activity, and is null only when it has neither prime nor sub revenue). For the underlying records, use /api/v1/companies/{uei}/prime-relationships.

FPDS prime contract activity fields

The profile also carries FPDS prime contract aggregates from the federal procurement system of record. These cover the recipient's full direct prime contract activity (every base award and modification under their UEI in the plan window), where the SAM Award Notice total_value field above covers only the SAM-noticed slice (~10-30% of obligations). Both views are surfaced so callers can pick the denominator that matches their question.

• fpds_obligated_total — total federal_action_obligation obligated to this UEI as a prime, summed across every FPDS transaction in the FY2025-onward window (since 2024-10-01).
• fpds_distinct_contracts — count of distinct contracts (contract_award_unique_key) the recipient holds.
• fpds_transaction_count — count of every FPDS row: base awards plus every modification.
• fpds_first_action_date / fpds_latest_action_date — ISO date bounds on the recipient's FPDS activity in the window.
• fpds_top_naics — array of up to 5 {code, description, transaction_count, value} objects, top NAICS by total $. Each object also includes a deprecated n field with the same value as transaction_count.
• fpds_top_agencies — array of up to 5 {name, transaction_count, value} objects, top awarding sub-agencies by total $. Each object also includes a deprecated n field.

Worked example (Pro response, FPDS + subaward enrichment)

Calling GET /api/v1/companies/CKV2L9GZKJK3 (Deloitte Consulting LLP) on a Pro key returns the SAM profile + award aggregates documented above, plus enrichment fields. Live response excerpt (verified 2026-06-15):

Notice the magnitude split: total_value (the SAM-noticed slice, only 12 award notices) is ~$1.31B, while fpds_obligated_total (the full prime contract picture across 914 contracts and 2,856 transactions, FY2025 onward) is ~$4.23B. fpds_obligated_total is the authoritative federal-activity number for this recipient.

GET /api/v1/companies/{uei}/awards Requires Auth Pro

Paginated award history for one UEI. Same data as /api/v1/awards/search?uei=X, served under a company-centric URL for convenience.

Parameters

• limit - Results per page (1-1000, default 50)
• offset - Pagination offset (default 0, no upper bound)
• sort - date (default, desc) or amount (desc). Strict: any other value returns 422.
• sort_by / sort_order - cross-endpoint alias matching awards search: sort_by=award_date|award_amount with sort_order=asc|desc (default desc). Wins over sort when present, and unlike sort it supports ascending order. Invalid sort_by returns 400.
• fields - Comma-separated response fields. notice_id always included. Example: fields=notice_id,award_amount,award_date,agency. See Response Shaping.

Response

Example

GET /api/v1/companies/{uei}/peers Requires Auth Pro

Similar companies ranked by NAICS and agency overlap with the target. Use for competitive mapping, teaming-partner discovery, and BD target lists.

Parameters

• limit - Results (1-50, default 10)

Response

Ranking

similarity_score = naics_overlap * 3 + agency_overlap. NAICS is weighted 3x higher because same-industry is a direct competition signal; shared customers is a weaker signal. Results sorted by similarity_score desc, then total_awards desc.

Example

GET /api/v1/subawards/search Requires Auth

Filter-based search across the FFATA subaward record set: every Section 2 report of a sub-vendor receiving more than $30K under a federal prime contract, sourced from USAspending's bulk_download. One denormalized 118-field row per FFATA report. Use it to map a prime contract's supply chain, find every prime that paid a given sub, or pull all subaward flow under one PIID. Refreshed daily; 2-day source lag.

Filter parameters

• prime_uei — 12-character UEI. Returns subawards paid by this prime. Normalized (strip + upper). Exact length: a 13-char or 11-char value returns 422.
• sub_uei — 12-character UEI. Returns subawards received by this sub-vendor. Same normalization.
• piid — Prime award PIID (max 80 chars). Returns all subaward records flowing from that single contract. Normalized (strip + upper); free-form government contract numbers.
• agency — Awarding agency name substring (case-insensitive, max 200 chars). Matches prime_award_awarding_agency_name.
• naics — Exactly 6 digits. Matches prime_award_naics_code. A 1-digit / 5-digit / 7+ digit value returns 400; well-formed but nonexistent codes return 200 with total=0.
• sub_name — Sub-vendor name substring (3-200 chars, case-insensitive). Matches subawardee_name.

Date, amount, sort, paging

• date_from / date_to — YYYY-MM-DD. Filter subaward_action_date. Subject to the subaward history window (see Search Window); the window block in the response surfaces clamping. Effective floor today is the data floor (2024-10-01).
• amount_min / amount_max — Filter subaward_amount. amount_min=0 is honored (excludes null-amount rows).
• sort_by — subaward_action_date (default), subaward_amount, or subaward_sam_report_last_modified_date. Invalid value returns 400 with the valid list — no silent fallback.
• sort_order — asc or desc (default desc). NULLs sort first on asc, last on desc. Tie-broken by subaward_sam_report_id for stable pagination.
• limit — 1-250 (default 50). Capped lower than /opportunities/search and /awards/search (which allow 1,000) because each subaward row is wider: 250 rows is ~400 KB, 1,000 rows would be ~1.5 MB. Bounds violation returns 422 (not the awards-style 403). Page size is a fixed cap on this free base layer, so there is no higher tier to upgrade to for a larger page size.
• offset — ≥ 0 (default 0).
• fields — Comma-separated projection. subaward_sam_report_id always included. See Response Shaping.

Unknown query params return 400 with the valid set listed in the error detail. No silent dropping.

Response (29 fields per row, subset of the 118-column corpus)

prime_award_project_title is null on the vast majority of procurement subawards — USAspending only populates it for assistance/grant subawards. prime_award_amount is the prime ceiling, the same value on every row sharing one PIID; aggregations by anything other than PIID will multi-count it.

Errors

• 400 — no filter passed / unknown query param / invalid sort_by / naics not 6 digits.
• 401 — missing or invalid API key.
• 422 — malformed UEI length, bad date format, limit out of range.
• 429 — rate limit exceeded.

Examples

What subs has Lockheed paid (most recent first):

Every sub under one prime contract:

Sub-vendor reverse lookup (everyone who paid this UEI as a sub) over the last 12 months above $100K:

Find subaward flow into a small-business sub-vendor by name fragment + NAICS:

GET /api/v1/subawards/{subaward_sam_report_id} Requires Auth

Single FFATA report by its SAM report ID (a UUID, the natural primary key of the subawards table). Returns the same 29-field row shape as a search result. Not subject to the subaward history window — if you have a report ID, the record returns regardless of age.

Parameters

• subaward_sam_report_id (path) — the UUID from any row in /subawards/search (the subaward_sam_report_id field on each result). Normalized (strip + upper); accepted in mixed case. No query parameters; ?fields= is not supported on this endpoint.

Response

A flat object with the same 29 fields documented under /subawards/search → Response. No wrapper; no data / pagination / window envelope on single-record lookup.

Errors

• 401 — missing or invalid API key.
• 404 — well-formed ID, no such report. Body: {"detail": "Subaward report not found"}.
• 429 — rate limit exceeded.

Example

Note: The natural-looking subaward_number field (e.g. 1A4PZ-006-WTERX) is not the unique identifier — empirically about 10% of subaward_number values collide across records (modifications, re-issues). The 32-character UUID subaward_sam_report_id is the only stable per-record key.

GET /api/v1/companies/{uei}/subawards Requires Auth

Prime-side reverse lookup: "what subs has this UEI paid?" Indexed on prime_awardee_uei. Same row shape as /subawards/search plus a top-level summary block aggregating across the filtered result set.

Parameters

• uei (path) — 12-character UEI of the prime. Normalized.
• sort_by — subaward_action_date (default), subaward_amount, or subaward_sam_report_last_modified_date.
• sort_order — asc or desc (default desc).
• date_from / date_to — YYYY-MM-DD. date_from is clamped to the effective subaward floor (2024-10-01 today).
• limit — 1-250 (default 50). 422 on out-of-range. Tighter cap than awards/opportunities because subaward rows are wider.
• offset — ≥ 0 (default 0).
• fields — Comma-separated projection (subaward row columns). subaward_sam_report_id always included.

Response

UEIs with no subaward records return 200 with an empty data array and a zero summary, not a 404 — same pattern as /companies/{uei}/awards.

Example

GET /api/v1/companies/{uei}/prime-relationships Requires Auth

Sub-side reverse lookup: "what primes have paid this UEI as a sub-vendor?" Indexed on subawardee_uei. Same row shape as /subawards/search plus a summary block with a top-10 paying-primes leaderboard.

Parameters

• uei (path) — 12-character UEI of the sub-vendor. Normalized.
• sort_by / sort_order — same as /companies/{uei}/subawards.
• date_from / date_to — YYYY-MM-DD. date_from window-clamped.
• limit — 1-250 (default 50). Same cap as the prime-side sibling.
• offset — ≥ 0 (default 0).
• fields — Comma-separated projection.

Response

For most SMBs, this is the better revenue picture than /companies/{uei}/awards — sub revenue is often the larger half of federal income, and prime-only data systematically undercounts it.

Example

Errors (both reverse-lookup endpoints): 401 (auth), 422 (bad UEI / out-of-range param), 429 (rate limit). 404 is not returned on "no records" — empty data with zero summary is.

GET /api/v1/partners/search Requires Auth Pro

Find federal contractors with proven past performance for a NAICS, awarding agency, place-of-performance state, or set-aside, ranked by gross obligated dollars, each with its socioeconomic status, SAM registration, and named points of contact. Composed from FPDS prime awards (FY2025 onward) plus the SAM registry. Built for teaming and subcontractor sourcing. Factual, not scored.

Parameters

At least one filter is required; the endpoint will not return the whole corpus. Unknown parameters return 400.

• naics: NAICS code, exact, 2 to 6 digits.
• agency: awarding agency name or acronym, resolved through the agency crosswalk (e.g. Army, Navy, Air Force). The only contractor endpoint that filters by agency.
• state: 2-letter place-of-performance state.
• set_aside: one of sdvosb, vosb, wosb, woman_owned, hubzone, 8a, sdb, minority_owned.
• psc: Product or Service Code, exact.
• keywords: matches the prime-award description text.
• limit: 1 to 50, default 20.
• offset: 0 to 200 (top ~250 firms per query; narrow filters for more).

Response

Standard list envelope: data, pagination, filters_applied, and _sources (["usaspending_fpds", "sam_entities"]). Results are ranked by gross_obligated descending, most recent award breaking ties; pagination.total is the exact distinct-firm count. Each row carries uei, name, contracts, gross_obligated, last_award_date, set_asides, agencies, registration_status, location, primary_naics, and pocs[] (named SAM points of contact with name, title, city, state, roles[]; no email or phone).

Rate limits

Tighter than general search because it surfaces contact data: 15 requests/minute per IP, 20/minute per key, pages capped at 50, pagination depth capped at 200. Bulk extraction is not supported by design.

Example

Returns 135 SDVOSB IT firms in Virginia ranked by dollars won; the top result is Liberty IT Solutions ($228M, 5 contracts) with its Department of Veterans Affairs award record and named points of contact. See the Teaming Partner Finder guide for worked examples.

GET /api/v1/vendor-risk/{uei} Requires Auth Pro

Returns every red-flag signal the public federal record contains about one vendor UEI, plus a mechanical triage verdict so compliance teams can sort without parsing the full tree. Seven signals, all derived from SAM data: exclusion status, address cluster, name-variant cluster, individual exclusions at the same address, coordinated-wave membership, last-award-to-exclusion gap, and dual-CAGE detection.

Parameters

• uei (path) - 12-character SAM UEI. Case-insensitive; non-alphanumeric input returns 422.

Response

Triage categories

• high - the entity itself is actively excluded.
• elevated - not excluded, but ≥2 co-tenants at the same address are excluded, or a name-variant entity is excluded, or ≥1 individual exclusion shares the address.
• needs_review - weaker signals only (e.g. multiple CAGE codes).
• clean - no signals returned.
• unknown - UEI not present in SAM exclusions or opportunities data at all.

Triage rules are deliberately simple and visible in triage.reasons so your compliance team can override by reading the signals themselves. Keys in the response are stable: values may be null, empty arrays, or false, but the shape never changes. Safe to parse with response_version branching if you need to stay compatible as we add signals.

Example

Notes: Returns 404 only when the UEI has no record in any of our SAM tables (exclusions, opportunities, or the ~873K-firm entity registry). SAM-registered vendors with no exclusion and no recent award still return 200 with a clean triage verdict. For non-US addresses where the state field is empty (Singapore, Hong Kong, Ankara, etc.), clustering falls back to line1+city. The address_source field tells you which table the address came from: exclusions, opportunities, entities, or unknown when no address was found. See /vendor-risk-api for signal definitions, the triage rules, and worked examples from real federal enforcement actions.

Enrichment blocks Pro

Two top-level blocks sit alongside signals and triage (NOT nested inside them) on Pro responses. Both are descriptive — they don't change the triage verdict — but compliance teams read them alongside the seven signals to size the supply-chain footprint around a single UEI.

subaward_exposure block — FFATA subaward dollar flow on both sides:

• as_prime — what this UEI has paid out to sub-vendors: {total_paid_to_subs, distinct_sub_vendors, subaward_count, first_subaward_date, last_subaward_date, top_subs: [{uei, name, total, subaward_count}, ... up to 5]}.
• as_sub — what this UEI has received from primes: {total_received_from_primes, distinct_primes, subaward_count, first_subaward_date, last_subaward_date, top_primes: [{uei, name, total, subaward_count}, ... up to 5]}.
• window_days — the lookback (1825 today).

Both sub-blocks always populate (zero shape when no records); subaward_exposure itself is omitted only when this UEI has no record in any of our tables (i.e. when the whole response would be a 404 candidate).

contract_exposure block — FPDS prime contract activity (parallel to subaward_exposure):

• fpds_obligated_total, fpds_distinct_contracts, fpds_transaction_count — magnitudes.
• fpds_first_action_date, fpds_latest_action_date — activity bounds in the window.
• top_agencies — array of up to 5 {name, value, transaction_count} objects, awarding sub-agencies ranked by total $.
• window_days — the lookback (1825 today).

The block returns the zero shape when this UEI has no FPDS prime contract activity in the window.

Worked example (Pro response, actively excluded UEI with mixed compliance picture)

UEI C1ZLDAS18FJ3 (ATI Government Solutions) was placed on the SBA "Ineligible (Proceedings Pending)" list on 2025-10-21 alongside its 3 named principals, debarred as individuals the same day (a firm-plus-officers coordinated action; wave_size 4). The contract_exposure block surfaces activity from 2024-10-01 onward (FY2025+): $95.34M in net obligations across 33 contracts, with the IRS as the largest awarding sub-agency at $82.55M. The subaward_exposure.as_prime shows this UEI paid out $55.44M to 10 distinct sub-vendors over the same window. For the recency-focused "is the problem ongoing?" view, see the parallel example on /exclusions/{uei_sam}, where the last-365-days window shows -$9.31M net (deobligations exceeding new obligations recently). Triage scores on the seven signals above; the exposure blocks add descriptive supply-chain context.

Field shapes for both blocks are also documented at the top of the Endpoints section under Pro enrichment fields (universal pattern). Live response verified 2026-06-01.

POST /api/v1/vendor-risk/bulk Requires Auth Pro

Bulk vendor screening. Upload up to 100 UEIs in one call and get back a risk report for each. Designed for quarterly vendor reviews where you want to screen your whole subcontractor list in one pass, not one-at-a-time.

Request body

• ueis - array of 1-100 UEIs. Duplicates deduplicated server-side. Max 100 per request (422 if exceeded).

Response

Per-row status is one of: ok (report present), not_found (UEI in none of our sources), or invalid (not 12 alphanumeric characters). A bad or stale UEI is surfaced per-row, never failing the whole request, since real vendor lists always contain some. returned_count reflects the post-dedup unique count, so it can be lower than requested_count. An empty ueis list or more than 100 entries returns 422. Each UEI counts against your hourly quota (a 100-UEI bulk = 100 quota hits). Expected latency: ~80ms per UEI on warm paths.

Example

Use cases: quarterly subcontractor review ("which of my 200 vendors now need attention?"), pre-contract screening, M&A target due diligence on a portfolio company's vendor list.

GET /api/v1/contacts/lookup Requires Auth Pro

Resolver lookup for federal contracting officers: pass a name (and optionally an agency), get back up to 5 matching contacts with email, phone, agency, department, and location. Designed for BD / outreach / intelligence platforms that already know who they are looking for and need the contact info to act on it.

This is a resolver, not a directory. There is no listing endpoint, no pagination, and no filter-only browse. To explore the directory (search by NAICS, view award history, see colleague graphs, AI dossiers), use the GovCon Contacts web app at contacts.govconapi.com (included with Pro).

Parameters

One of name or email is required.

• name - Name or partial name. Min 2 characters. Substring match, case-insensitive. Returns up to 5 results.
• agency (optional, with name) - Agency or department substring for disambiguation (e.g. Air Force, DLA, Veterans). Matches both current_agency and current_department.
• state (optional, with name) - 2-letter state/territory code (e.g. CA, DC, VA) for geographic disambiguation.
• email - Exact email address for reverse lookup. Returns one record. Useful for CRM enrichment when you have the email on file and want the current name/agency/phone.

Response

Examples

Caching: Successful responses include Cache-Control: public, max-age=3600. Data refreshes nightly so an hour of client-side caching is safe and saves your quota on repeat queries.

Heads-up on generic search terms: "Coordinator", "Specialist", and similar return shared role inboxes (e.g. "BAA Coordinator" appears in 23 agencies as a shared queue address) rather than individual people. Use agency and/or state to narrow, or look up by email when you need exactly one record.

Errors: 401 (no auth), 402 (Developer key, Pro required), 404 (no matches), 422 (neither name nor email provided, or name too short), 429 (rate limit), 503 (contacts data store transiently unavailable; retry).

Use cases: a BD platform sees a contracting officer mentioned in a news feed or post and resolves their email/phone for outreach; a CRM enriches contact records with agency and location; an intelligence system maps names from public discussions to verified federal buyer identities.

Coverage: ~23,000 federal contracting officers and contracting specialists across 124 agencies. 100% have an email; ~61% have phone numbers. Refreshed nightly from federal contract notices.

GET /api/v1/opportunities/delta Requires Auth

Get all opportunities that were added or updated since a given timestamp. Use this to keep your local database in sync without re-downloading the entire dataset.

How It Works

• Pass a timestamp, get changes. Returns every record that was added, updated, or backfilled since the timestamp you provide. This includes newly posted notices, updated deadlines, and historical records that were filled in during data reconciliation.
• Same 59 fields as the search endpoint. Each record is a complete opportunity, not a diff.
• Data updates daily around 2:00 AM UTC. A typical day has 1,000 to 2,000 changed records. Calling this once a day keeps you fully in sync.
• Save the server_time from the response and use it as since on your next sync. This guarantees no gaps.

Parameters

• since (required) - ISO 8601 timestamp (e.g. 2026-04-05T06:00:00Z). Clamped to the last 60 days: an older value still returns 200, and the sync block reports since (the effective value used), since_requested, and clamp_reason. Delta is a sync tool, not a backfill; for older data use search with date filters.
• limit - Results per page (Free: max 50, Developer: max 1000, default 1000). Over your plan cap returns 403 (not a silent cap).
• offset - Pagination offset

Only since, limit, and offset are accepted. Any other parameter (e.g. naics_multiple) returns 400; delta does not filter by content. Errors: 400 (unknown param, or unparseable since), 401 (no/invalid key), 403 (limit over plan cap), 422 (since missing), 429 (rate limit).

Response

The sync.server_time field is the next-cursor. Save it from this response and pass it as since on your next pull. The field is not currently named next_since but it functions as one; treat it as the watermark of "everything up to here has been delivered." If you re-pass your original since instead, you will re-pull the same records you already saw.

What a real delta pull contains. A live pull on 2026-06-02 against since=2026-05-30T22:00:00Z returned 1,984 changed records. Across the first 1,000 sampled, the notice-type mix is Combined Synopsis/Solicitation (32%), Award Notice (25%), Solicitation (21%), Sources Sought (8%), Presolicitation (7%), Special Notice (6%), plus a small tail of Justification notices (1%). The endpoint reports every state change, not just new postings, so a BD pipeline sees the same notice cycle through pre-award stages and the award decision in the same delta stream.

Sync Workflow

GET /api/v1/exclusions/search Requires Auth

Search SAM.gov Exclusions database for debarred entities (companies and individuals prohibited from federal contracting). Perfect for vendor due diligence and compliance screening.

How It Works

• Dataset: 163,000+ exclusion records from SAM.gov (updated weekly). Check /api/v1/stats for current count. For more frequent updates, contact [email protected].
• Search Logic: Multiple filters are combined with AND logic. For example, classification_type=Firm&state=CA returns only California firms (not firms OR California)
• Partial Matching: Name and agency filters use case-insensitive partial matching. entity_name=Smith matches "John Smith", "Smithson Corp", etc.
• Individuals vs Firms: Most records are individuals (classification_type=Individual); fewer are firms. Most individuals don't have UEI identifiers, so search them by name.

Filter Parameters

• entity_name - Entity or person name (partial match, case-insensitive). Alias: name (if both are sent, entity_name wins).
• uei_sam - UEI SAM identifier (exact match). Note: most exclusions (individuals) have no UEI, so do not pass the literal string null to find them; it matches zero rows. Omit the param instead.
• cage_code - CAGE code (exact match)
• excluding_agency - Excluding agency code like "HHS", "DOJ" (partial, case-insensitive match on excluding_agency_code)
• classification_type - Type: Individual, Firm, Vessel, Special Entity Designation (exact, case-sensitive: individual returns 0)
• exclusion_type - Exclusion category (exact, case-sensitive; use SAM's exact string, e.g. Prohibition/Restriction)
• state - State/province code (e.g., CA, TX)
• country - Country code (e.g., USA)
• active_only - Boolean, default true (only active exclusions)
• limit - Results per page (Free: max 50, Developer: max 1000, default 20)
• offset - Pagination offset
• fields - Comma-separated response fields. uei_sam always included. Example: fields=uei_sam,entity_name,excluding_agency_code,activate_date. See Response Shaping.

Response

Examples

Search by entity name:

Returns 1,089 individuals and firms with "Smith" in the name

Find California firms:

Returns 742 excluded firms in California

HHS exclusions:

Returns 69,356 HHS exclusions (largest excluding agency)

OFAC sanctions match by name:

Returns the OFAC sanctions record for the named entity. Same response envelope as the DLA / HHS query above; the differentiating fields are excluding_agency_code: "OFAC", exclusion_type: "Prohibition/Restriction", exclusion_program: "Reciprocal", classification_type: "Special Entity Designation", and the international country_code (here "VNM"). The additional_comments field is "Redacted for security reasons" on OFAC records; the agency cite for the underlying action is on the published OFAC SDN list, not in our database. One screening pipeline reads OFAC and DLA records uniformly.

GET /api/v1/exclusions/{uei_sam} Requires Auth

Vendor-risk screening lookup: pass a UEI SAM and find out whether that entity has an active or historical exclusion on record.

Response semantics

• 200 — entity is on the exclusions list. Body returns the most recent exclusion record under an exclusion key (dates, location, agency, exclusion type, classification, ~37 fields total), a top-level additional_exclusion_records count (further records keyed to the same UEI, e.g. a debarment by a second agency; 0 for most entities, fetch the full set via /exclusions/search?uei_sam=), a top-level _sources array and, on Pro keys, the two enrichment blocks documented below.
• 404 — the UEI has no UEI-keyed exclusion. This is the expected answer for the vast majority of legitimate vendors, but it is not a full "clean" verdict: most exclusions are individuals with no UEI, so a 404 does not rule out a name-based debarment. See the coverage caveat below and pair this with a name search before treating a vendor as clear.

Example

Coverage caveat. Roughly 73% of SAM exclusions are individuals or small entities without a UEI. A 404 from this endpoint means no UEI-keyed exclusion; it does not rule out a name-based debarment of a principal, officer, or related individual. For full vendor screening, pair this lookup with /api/v1/exclusions/search?entity_name=....

Compliance enrichment blocks Pro

When the caller has Pro and the lookup returns a 200, the response carries two top-level blocks summarizing federal money flow to this excluded UEI in the last 12 months. The compliance question goes from "are they debarred?" to "is anyone in the federal supply chain still paying them — directly or indirectly?" in a single call. Both blocks default to a 365-day lookback and always return the zero shape when there's no activity, so client code can read fields without per-call null checks.

recent_sub_payments block — FFATA subaward dollars received indirectly (clean primes paying the excluded entity as a sub):

• lookback_days, total_received, subaward_count, distinct_primes.
• most_recent_subaward_date, most_recent_subaward_amount, most_recent_paying_prime: {uei, name} — the smoking-gun row.
• top_paying_primes — array of up to 5 {uei, name, total, subaward_count} objects.

recent_contract_actions block — FPDS prime contract obligations received directly (the excluded entity is still being awarded contracts by federal agencies):

• lookback_days, total_obligated_recent, transaction_count, distinct_contracts, distinct_agencies.
• most_recent_action_date, most_recent_action_amount, most_recent_awarding_agency, most_recent_piid — the smoking-gun row.
• top_paying_agencies — array of up to 5 {name, value, transaction_count} objects.

Net obligation (total_obligated_recent) can be negative — agencies clawing back contract money from an excluded vendor reads as a "compliance is working" pattern; positive amounts on an active exclusion read as "compliance gap, escalate." Both block shapes are also documented under Pro enrichment fields (universal pattern) at the top of the Endpoints section.

Worked example (Pro response on an excluded UEI with the recency view)

UEI C1ZLDAS18FJ3 (ATI Government Solutions): on the exclusions list since 2025-10-21. In the last 365 days agencies issued 64 contract actions across 21 distinct contracts and 6 agencies, with a NET obligation of -$9.31M, meaning deobligations are exceeding new awards. That's the "compliance is working" pattern. recent_sub_payments is zero (no recent FFATA sub income to this UEI). For the broader 5-year activity view, see the parallel example on /vendor-risk/{uei}.

Response shape. The exclusion record is wrapped under an exclusion key; enrichment blocks are siblings at the top level, per the multi-block detail convention. Free / Developer responses omit the two enrichment blocks; Pro responses include them with the zero-shape when no activity matches.

If you only need the screening yes/no plus the recent-payment views, this endpoint is sufficient. If you also want address clusters, name variants, coordinated-wave membership, and the longer 5-year exposure picture, call /api/v1/vendor-risk/{uei} instead — that response includes the subaward_exposure + contract_exposure blocks (1825-day window) plus the seven risk signals. Live response verified 2026-06-01.

GET /health No Auth Required

Health check endpoint showing system status and database connection.

Response

Note: For data freshness, see last_delta_utc on /meta or last_updated on /api/v1/stats.

Example

GET /export.csv Requires Auth Developer

Export contract notices as CSV file. Free plan does not have CSV export access.

Query Parameters

A subset of the /opportunities/search filters. For the full filter set (date ranges, value ranges, sort, location, attachments, active_only, response shaping), use /opportunities/search and write a CSV client-side.

• keywords - Full-text search across title, agency, description
• naics - Single NAICS code
• naics_multiple - Comma-separated NAICS codes (OR'd)
• agency - Agency name (partial match)
• state - 2-letter state code or full state name
• set_aside - Set-aside code (e.g. SBA, 8(a))
• notice_type - Notice type (e.g. Solicitation, Award Notice)
• solicitation_number - Solicitation number (partial match)
• limit - Max records to export (default 1000, max 1000)

Any other parameter returns 400 Bad Request. Unknown params are not silently dropped.

Plan Restrictions:

• Developer: All listed filters available. 15 exports/day.
• Free: No CSV export access.

CSV Format

CSV exports a 15-column analyst-friendly subset (the columns below in this exact order). Empty values show as blank cells. If you need fields not in this set, pull them from /api/v1/opportunities/search instead, which returns all 59 fields per record.

Examples

Export defense awards:

Export by NAICS and state:

Need filters not listed above? Use /api/v1/opportunities/search for the full filter set (value ranges, date ranges, sort, etc.) and write the CSV yourself. The 59-field response gives you everything; the 15-column CSV here is the analyst-ready subset.

Free plan - Not available:

POST /api/v1/keys No Auth Required

Create a new API key. The key will be emailed to you instantly. Generating a new key deactivates the previous one for that email.

Query Parameters

• email - Your email address (required)
• plan - Plan type: "free" (default) or "developer"

Example

Note: For the Developer plan, use the /api/v1/checkout endpoint to create a Stripe checkout session.

POST /api/v1/checkout No Auth Required

Create a Stripe checkout session for Developer plan subscription. Redirects to Stripe payment page.

Query Parameters

• email - Your email address (required)

Response

Example