Skip to content

Contracts Data Dictionary

This document describes the fields available in the Contracts API endpoints (/api/contracts/). For filtering, ordering, and pagination, see the Contracts API Reference.

Overview

Contracts are definitive contract awards from FPDS (Federal Procurement Data System). Contracts are sourced from both FPDS and USAspending, and Tango merges those inputs during award materialization.

Identifiers

  • key (canonical): The canonical award identifier derived from FPDS/USAspending award keys. This is what the API uses for lookups: GET /api/contracts/{key}/.
  • uuid (internal): Tango’s deterministic internal UUID used as the database primary key and for stable internal joins/orderings. This is not intended as a public lookup key.

Note: The full set of fields is available via the shape query parameter. The base response includes a subset of commonly-used fields. See Response Shaping for details.

Update Frequency

Contract data is refreshed via the awards ETL pipeline (FPDS updates twice daily; USAspending inputs update daily).

Fields

Field Type Description Source
key String Canonical award identifier (stable across FPDS and USAspending). Used for detail lookups and cross-referencing. FPDS / USAspending
piid String Procurement Instrument Identifier. The official contract number. FPDS / USAspending
award_date Date Date the contract was awarded. FPDS / USAspending
award_type Object Type of award (e.g., contract type code and description). Use the award_type expansion for code, description. FPDS / USAspending
naics_code Integer NAICS code on the award (when stored as a single code). FPDS / USAspending
psc_code String Product/Service Code on the award (when stored as a single code). FPDS / USAspending
total_contract_value Decimal Total value of the contract (base + options, when reported). Expressed in US dollars. FPDS / USAspending
base_and_exercised_options_value Decimal Base contract value plus exercised options. Expressed in US dollars. FPDS / USAspending
fiscal_year Integer Federal fiscal year of the award (Oct–Sep). FPDS / USAspending
obligated Decimal Total obligated amount (dollars) on the contract. FPDS / USAspending
description String Contract description or title, when available. FPDS / USAspending
set_aside Object Set-aside type (e.g., small business, 8(a)). Use the set_aside expansion for code, description. FPDS / USAspending
transactions Array List of transaction/modification records. Use the transactions expansion; each item can include modification_number, transaction_date, obligated, description, action_type. FPDS / USAspending
subawards_summary Object Summary of subawards under this contract. Use the subawards_summary expansion for count, total_amount. USAspending / Tango

Expansions (via shape)

recipient

Returns the awardee (entity). Fields: uei, display_name, legal_business_name, cage, duns.

place_of_performance

Returns the place of performance. Fields: country_code, country_name, state_code, state_name, city_name, zip_code.

awarding_office / funding_office

Returns the awarding or funding office. Fields: office_code, office_name, agency_code, agency_name, department_code, department_name.

parent_award

Returns the parent award (e.g., IDV) when this contract is a child order. Fields: key, piid.

The default (non-shaped) response includes parent_award as a minimal {key, piid} reference derived from the award key without a database query. Use ?shape= with parent_award(key,piid) to get the same fields via the shaping pipeline, or expand to the full parent award object.

period_of_performance

Returns period of performance. Fields: start_date, current_end_date, ultimate_completion_date.

award_type / set_aside

Returns code and description for award type or set-aside type.

transactions

Returns the list of modifications/transactions. Each item: modification_number, transaction_date, obligated, description, action_type.

competition

Returns competition-related fields: contract_type, extent_competed, number_of_offers_received, other_than_full_and_open_competition, solicitation_date, solicitation_identifier, solicitation_procedures.

legislative_mandates

Returns legislative mandate flags (e.g., Clinger-Cohen, labor standards, employment eligibility).

officers

Returns contracting/officer information (when available).

naics / psc

Returns NAICS or PSC as {code, description}.

subawards_summary

Returns count and total_amount for subawards under this contract.

Common code values

These fields use standardized code systems. The canonical mappings live in src/awards/choices.py.

award_type

Code Meaning
A BPA Call
B Purchase Order
C Delivery Order
D Definitive Contract

competition.contract_type

Code Meaning
J Firm Fixed Price
U Cost Plus Fixed Fee
R Cost Plus Award Fee
Y Time and Materials
Z Labor Hours
1 Order Dependent
2 Combination
3 Other

(Many additional contract-type codes exist; see CONTRACT_TYPE_CHOICES.)

competition.extent_competed

Code Meaning
A Full and Open Competition
C Not Competed
D Full and Open after exclusion of sources
F Competed under SAP
G Not Competed under SAP
CDO Competitive Delivery Order
NDO Non-Competitive Delivery Order

(See EXTENT_COMPETED_CHOICES for the complete mapping.)

set_aside

Code Meaning
NONE No set aside used
SBA Small Business Set Aside - Total
8A 8(a) Competed
HZC HUBZone Set Aside
SDVOSBC Service-Disabled Veteran-Owned Small Business Set Aside
WOSB Women-Owned Small Business
EDWOSB Economically Disadvantaged Women-Owned Small Business

(See Set-aside codes for the complete mapping.)

Data Sources

  • FPDS – Contract actions, PIID, dates, values, NAICS, PSC, set-aside, competition, offices, recipient reference.
  • USAspending – Supplemental award/transaction inputs used in award materialization and subaward linkage.
  • Tango – Internal deterministic uuid and merged award materialization.

Usage Notes

  • Use key for API references – key is the canonical award identifier used by the Contracts API.
  • Use piid for human/FPDS lookups – PIID is the contract number users see in FPDS and solicitations.
  • Scoped endpoints – Use /api/entities/{uei}/contracts/, /api/idvs/{key}/awards/, or /api/vehicles/{uuid}/orders/ for contract lists scoped to an entity, IDV, or vehicle; see Contracts API Reference.
Report an issue with this page