Federal Contract Awards API

Federal prime contract data is the foundation under every other procurement question, but accessing it is fragmented across three systems that all return different shapes of the same answer.

FPDS is the official record. The interface is SOAP, the response is XML, and stitching together one company's contract history is a multi-day integration that you redo from scratch every time the schema shifts. USAspending exposes the same data through a modern REST interface, but its search endpoint returns null for NAICS, PIID, total obligation, and contract type. To populate those fields you re-fetch each award individually from a second endpoint, then merge. SAM.gov publishes the subset that becomes a public notice, which is roughly 10 to 30 percent of obligations depending on the agency. Subaward filings live in a fourth dataset entirely.

If you need contract activity to drive BD pipelines, recipient profiles, vendor risk scoring, or supply-chain analysis, you end up integrating all four data sources with different schemas, rate limits, and refresh cadences. This endpoint is the alternative: every federal prime contract transaction in one JSON shape, with stable identifiers, a documented field set, and a single auth header.

Three endpoints cover search, detail, and the full modification trail under a single PIID.

Applies to /api/v1/contracts/search. At least one of uei, parent_uei, piid, parent_piid, agency, or naics is required. Unknown parameters return 400.

Search returns a data array, a pagination block, a filters_applied echo of the resolved filters, a window block describing the coverage horizon, and a _sources array naming where the data came from.

The detail endpoint returns a singular contract object plus a transaction_rollup sibling block that aggregates obligations, ceiling, distinct recipients, and action-date bounds across every transaction under that PIID. Pro responses also include a subaward_rollup sibling for subaward enrichment.

For the wider 57-field expanded projection (funding agency, period of performance, place of performance, competition flags) and the 298-column full projection, pass ?fields=expanded or ?fields=full respectively.

The detail endpoint /api/v1/contracts/{piid} returns a subaward_rollup sibling block on Pro keys, summarizing the FFATA subaward footprint flowing from this prime contract. The block carries the sub-vendor count, total subcontracted dollars, share of the prime obligation, distinct sub-vendor count, first and last subaward dates, plus the top 5 named sub-vendors with per-sub totals.

Within the FY2025+ coverage window the PIID join into the subaward layer is dense: roughly 88 percent of subaward filings match a prime contract row, and 98 percent of in-scope contracts that have subaward activity see a populated block. The corresponding join from SAM Award Notices into subawards covers under 1 percent of the same population, which is why subaward enrichment lives on this endpoint rather than on the SAM-notice surface.

What this response shape means for a BD or due-diligence read. The example above is the live response for Deloitte's $392M Army task order under PIID W56JSR23F0062. The customer-actionable signals are visible in one call: transaction_count: 52 says the prime has cycled 52 mods over 16 months (active, well-managed contract). subcontract_share: 0.0608 says Deloitte keeps 94 percent of the work in-house (high incumbency moat for a recompete). max_potential_total_value exceeds latest_potential_total_value only when an earlier mod set a higher ceiling than the current one, which is a scope-reduction signal worth chasing in a recompete play. The top 5 named subs (omitted in the snippet for length) include the same federal IT shops bidding the same recompete cycle, plus often a research partner. None of this requires joining three datasets client-side. The detail call delivers it.

For the full subaward record set under a PIID, use /api/v1/subawards/search?piid={piid}. For vendor-wide subaward activity across every contract a recipient holds, use the UEI-keyed reverse lookup /api/v1/companies/{uei}/subawards.

Federal contracts have one PIID and many transactions. The base award is one transaction; every option exercised, value added, partial termination, and administrative cleanup is another. /api/v1/contracts/{piid}/modifications returns the full ASC-ordered trail, oldest action first, so you can reconstruct what happened on a single contract over its life.

This endpoint is not date-windowed. When you ask for one PIID's history, you get the full history we carry, regardless of the coverage window that applies to search.

Each transaction carries the full agency hierarchy: awarding_agency_name, awarding_sub_agency_name, awarding_office_name, and the matching code fields. These tell you which office issued the contract and which office holds the re-compete.

Personal contact information (specific contracting officer name and email) is not part of the federal procurement record. For that data, use the contracting officer directory below, which indexes contacts by office and by past award.

Search caps at 250 results per request, modification trails cap at 500. The wider modification cap reflects that a typical contract has dozens of mods, not thousands of unrelated rows.

# Page 1
GET /api/v1/contracts/search?naics=541512&agency=defense&limit=250&offset=0
→ { "data": [...], "pagination": { "limit": 250, "offset": 0, "total": 54332, "has_next": true } }

# Page 2
GET /api/v1/contracts/search?naics=541512&agency=defense&limit=250&offset=250
→ { "data": [...], "pagination": { "limit": 250, "offset": 250, "total": 54332, "has_next": true } }

# Stop when has_next is false

Rate limits

Two layers, both enforced:

• 1,000 requests per hour per API key (Developer plan). This is the sustained limit.
• 60 requests per minute per IP, across all endpoints. This is a burst ceiling.

Hit either and you get a 429 with a Retry-After header. Both X-RateLimit-Limit and X-RateLimit-Remaining are present on every response so you can pace your client.

Competitive intelligence by NAICS

Filter by NAICS and date range to see every recipient winning work in your category, what they were obligated, which agencies are awarding it, and at what cadence. Sort by federal_action_obligation descending to find the largest single actions, or by current_total_value_of_award for the largest ceilings.

Recipient due diligence

Pull a recipient's full contract activity by UEI to see total obligations, agency mix, NAICS spread, and set-aside posture before teaming or subcontracting. Use parent_uei for the corporate roll-up across subsidiaries.

Re-compete research

Look up a contract by PIID to see the latest action, the ceiling, the period of performance, and the awarding office. Pull the modification trail to understand what changed over the contract's life and where the option exercises sit.

Subaward and supply-chain analysis

On Pro, the detail endpoint returns a populated subaward_rollup for contracts with FFATA filings. For vendor-wide subaward activity, switch to the UEI-keyed reverse lookup at /companies/{uei}/subawards.

BD pipeline polling

Poll with date_from set to your last sync timestamp to fetch only new actions. Combine with NAICS or agency filters to keep the result set scoped. Recipient UEI and PIID are stable identifiers you can store and re-query against.

FPDS prime contract activity stitches into the rest of the GovCon API surface so a single endpoint call can return the full federal picture without round-trips:

• /companies/{uei} returns fpds_obligated_total, fpds_distinct_contracts, fpds_transaction_count, fpds_first_action_date, fpds_latest_action_date, fpds_top_naics (up to 5), and fpds_top_agencies (up to 5) alongside the existing SAM Award Notice totals and subaward income aggregates. The combined view answers "what's this UEI's complete federal activity?" in one call.
• /entities/{uei} and /entities/by-cage/{cage} return the same fpds_obligated_total and date-bound activity on the SAM entity record. Vendor-onboarding reads federal scale alongside registration data in the call your CRM is already making.
• /vendor-risk/{uei} returns a contract_exposure block with obligation flow, transaction count, distinct contracts, action-date bounds, and top awarding agencies. Compliance teams read FPDS exposure alongside the seven existing risk signals and the subaward_exposure block.
• /exclusions/{uei_sam} returns a recent_contract_actions block summarizing direct prime contract obligations the excluded UEI has received in the last 12 months: net obligated, transaction count, distinct contracts and agencies, most-recent action (date, amount, agency, PIID), top paying agencies. The compliance question goes from "are they debarred?" to "is anyone still paying them?" in one call.

All enrichment blocks are silently omitted on Free / Developer keys. _sources on every response composes the underlying source identifiers (sam_entities, usaspending_fpds, usaspending_ffata, ...) so callers know exactly which data layers fed the response.

Beyond the inline enrichment above, contract records cross-link into the rest of the API through stable identifiers.

• recipient_uei joins to /api/v1/entities/{uei} (SAM registration), /api/v1/companies/{uei} (cross-source view), /api/v1/vendor-risk/{uei} (seven-signal screening), and /api/v1/exclusions/{uei} (debarment screening).
• award_id_piid joins to /api/v1/subawards/search?piid={piid} for the full subaward record set and to /api/v1/opportunities/search?solicitation_number={...} for the originating notice when one was published.
• recipient_parent_uei rolls up across subsidiaries for corporate-group queries.
• contract_award_unique_key is the global join key when PIID alone is ambiguous (same PIID assigned by two different agencies).

Data is sourced from the federal procurement system of record (FPDS) for prime contract types A, B, C, and D, refreshed daily.

• Coverage today: FY2025 + FY2026 (action dates from October 2024 onward). 9 million+ transactions, 8 million+ distinct contracts, 100,000+ recipients.
• Refresh cadence: daily. Upstream lag is typically 1 to 2 days from action date to availability.
• Plan window: 5 years. The customer-facing earliest_searchable field in every response is the actual floor, so window math is always honest.
• Older fiscal years: available on Enterprise. Future open-tier backfill will extend the window as it lands.
• Indefinite delivery vehicles (IDVs): the parent vehicles themselves are not in this scope; the orders and modifications against them are. To find the parent IDV for an order, use parent_award_id_piid.
• Grants and assistance awards: not in scope. This endpoint is FAR-based prime contracts only.

Contract search is included on every paid plan; the Pro plan adds subaward enrichment on the detail endpoint.

• Free trial (14 days): all filters available, 25 results per request.
• Developer: all filters, 250 results per request, 1,000 requests per hour.
• Pro: Developer access plus subaward_rollup on the detail endpoint, vendor-risk and companies enrichment, and the wider field-projection tiers.

Every parameter is available on every paid plan; the differences across tiers are result count per request, enrichment access, and rate limits. See full pricing.