Subawards¶

Subawards (subcontracts reported under federal prime contracts and IDVs) are exposed at /api/subawards/. For field definitions, see the Subawards Data Dictionary.

Endpoints¶

• GET /api/subawards/ (list + filtering + ordering)
• GET /api/subawards/{key}/ (detail; key is the report UUID)

Scoped lists:

• GET /api/contracts/{key}/subawards/ (subawards under a contract)
• GET /api/entities/{uei}/subawards/ (subawards where the entity is the subawardee)

Keys¶

A subaward's key is the subaward report's own identifier: the UUID that SAM.gov assigns to a subcontract report (subAwardReportNumber) and that USAspending republishes as subaward_sam_report_id, in lowercase. One row per report; an amendment keeps the key and changes the values.

Before API version 5.15.0 the key was an integer. Those keys keep resolving until 2027-04-30:

• GET /api/subawards/{integer}/ answers 301 to the UUID URL, with Deprecation: true and Sunset: Fri, 30 Apr 2027 00:00:00 GMT headers.
• ?key= accepts integers beside UUIDs.
• ?shape=…,fsrs_report_id still answers: the leaf returns key in its pre-5.15.0 uppercase spelling. It is not part of expand(*).

Update stored keys to the UUIDs before the sunset.

Default response¶

All subaward responses use the shaping pipeline by default. No ?shape= parameter is required to get a shaped response.

Default fields (equivalent to requesting):

amount_suspect,award_key,awarding_office(*),fsrs_details(*),funding_office(*),key,piid,
place_of_performance(*),place_of_performance_id,prime_recipient(uei,display_name),
prime_recipient_id,recipient_id,recipient_parent_id,retired_at,subaward_details(*),
subaward_recipient(uei,display_name)

Shaping¶

Use ?shape= to request a custom field set. Subawards support the following leaves and expansions.

Leaves¶

Expansions¶

Recipient and place details are no longer stored on the subaward itself: they come from the entity and place records the ids point at, so a subawardee's name, address and business types are the ones on /api/entities/{uei}/.

Examples¶

# Default response (no shape needed)
/api/subawards/

# Minimal fields
/api/subawards/?shape=key,piid,award_key

# Subaward details with recipient info
/api/subawards/?shape=key,piid,subaward_details(*),subaward_recipient(uei,display_name)

# Office hierarchy for awarding office
/api/subawards/?shape=key,awarding_office(office_code,office_name,agency_name)

# Place of performance
/api/subawards/?shape=key,place_of_performance(city,state,country_code),pop_cd_current

# Report details
/api/subawards/?shape=key,fsrs_details(id,year,month,last_modified_date)

# Highly compensated officers
/api/subawards/?shape=key,highly_compensated_officers(name,amount)

# Discover available fields
/api/subawards/?show_shapes=true

Filtering¶

Retired reports¶

A report that USAspending published and later stopped publishing (and that SAM.gov has not re-filed since) is kept with retired_at set to when Tango first saw it gone, rather than deleted. Lists omit retired reports unless you send include_retired=true; a detail lookup by key always answers. A report only SAM.gov holds is never retired.

Ordering¶

Subawards support ordering= with a strict allowlist:

• last_modified_date (the report's last modification, fsrs_details.last_modified_date)

Examples:

• Most recently modified first: GET /api/subawards/?ordering=-last_modified_date

Pagination¶

Subawards use standard page-number pagination:

• page (default 1)
• limit (max 100)

SDK examples¶

See also: Full SDK method reference — tango-python methods · tango-node methods.

import os

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
data = client._get(
    "/api/subawards/",
    params={"recipient": "deloitte", "ordering": "-last_modified_date", "limit": 10},
)
print("count:", data.get("count"))

import { TangoClient } from "@makegov/tango-node";

const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY });
const http = (client as any).http;

const data = await http.get("/api/subawards/", {
  recipient: "deloitte",
  ordering: "-last_modified_date",
  limit: 10,
});

console.log("count:", data.count);