Loans Data Dictionary¶

This document describes the fields on /api/assistance/loans/. The four financial-assistance endpoints share one schema; the others are Grant awards · Direct payments · Other assistance. For filtering, search, ordering and pagination, see the Loans API Reference. For how the pieces fit together, see the Financial assistance overview.

Overview¶

A financial-assistance award is money a federal agency gives a recipient without buying anything from it: a grant, a loan or loan guarantee, a direct payment, insurance, and a few rarer kinds. Agencies report each action on an award (the new award, each continuation, amendment or closeout) to USAspending as a transaction. Tango rolls each award's transactions up into one record, keeps the transactions alongside it, and files the award under one of four endpoints by its assistance type.

On a loan, face_value_of_loan is the amount lent or guaranteed and loan_subsidy_cost the estimated long-term cost to the government. pragmatic_obligations is the subsidy cost, the figure that compares with a grant's or a payment's obligation.

Identifiers¶

key (canonical): Tango's award identifier, built from USAspending's award ID. It's what the API uses for lookups: GET /api/assistance/loans/{key}/.
fain: the Federal Award Identification Number the agency assigned. Present on non-aggregate records (record types 2 and 3).
uri: the Unique Record Identifier, present on aggregate records (record type 1).
former_award_keys: award IDs USAspending has retired in favor of this award. A retired key still resolves to this award. An empty list when there are none.

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

Update Frequency¶

Financial-assistance data is refreshed daily from USAspending's financial-assistance files.

Fields¶

Award¶

Field	Type	Description
`key`	String	Canonical award identifier. Used for detail lookups and the sub-routes.
`fain`	String	Federal Award Identification Number (non-aggregate records).
`uri`	String	Unique Record Identifier (aggregate records).
`former_award_keys`	Array of strings	Retired award IDs that now resolve to this award; `[]` when none.
`award_date`	Date	Date of the award's first action.
`last_action_date`	Date	Date of the award's most recent action.
`last_modified_date`	Datetime	The latest source modification time among the award's transactions.
`fiscal_year`	Integer	Federal fiscal year (October–September) of the award's first action.
`assistance_type`	String	GSDM assistance type code (`F001`–`F010`, or `-1`) of the award's most recent action. It decides which endpoint the award is under. The `assistance_type` expansion adds its description. See Assistance types.
`assistance_types_count`	Integer	How many distinct assistance types the award's transactions carry.
`record_type`	String	`1` aggregate, `2` non-aggregate, `3` non-aggregate to an individual (PII-redacted). See Record types.
`cfda_number`	String	The award's primary assistance listing (CFDA) number, e.g. `93.778`. The `assistance_listing` expansion adds the program title.
`listings_count`	Integer	How many distinct assistance listing numbers the award's transactions name. The `listings` expansion breaks the money out by listing.
`transactions_count`	Integer	How many transactions the award has.
`title`	String	A short title for the award, at most 60 characters, written from its descriptions.
`summary`	String	A plain-language summary of what the award funds, written from its base description and its transactions' descriptions.
`purposes_differ`	Boolean	`true` when the award's transactions describe different purposes, `false` when they don't (including when there's only one description), `null` when not yet assessed.
`award_amount_basis`	String	How the award amount was selected (GSDM v1.2), from the most recent action that reports it. See Award amount basis.
`award_recipient_basis`	String	How the recipient was selected (GSDM v1.2), from the most recent action that reports it. See Award recipient basis.
`business_funds_indicator`	String	`NON` (not Recovery Act funds) or `REC` (Recovery Act funds).
`disaster_emergency_fund_codes`	String	Disaster Emergency Fund Codes (DEFC) on the award, as `code: description` entries separated by `;`.
`funding_opportunity_number`	String	The funding opportunity number the award was made under, as on the Grants.gov opportunity.
`funding_opportunity_goals_text`	String	The goals of that funding opportunity, as the agency reported them.
`sai_number`	String	State Application Identifier from the state's intergovernmental review (Executive Order 12372), or `SAI EXEMPT`.
`treasury_accounts_funding_this_award`	String	Treasury account symbols that fund the award, e.g. `012-X-1004-000`.
`federal_accounts_funding_this_award`	String	Federal accounts that fund the award, e.g. `012-1004`.
`object_classes_funding_this_award`	String	Object classes of the funding, e.g. `41.0: Grants, subsidies, and contributions`.
`program_activities_funding_this_award`	String	Program activities of the funding, e.g. `0014: AGRICULTURAL CONSERVATION EASEMENT PROGRAM`.
`transactions`	Array	Every transaction on the award. See `transactions`.

Money¶

Every dollar field is in US dollars. The first group sums the award's transactions; the award_total_* group is what USAspending published as the award's totals.

Field	Type	Description
`obligated`	Decimal	Federal action obligation, summed over the award's transactions.
`pragmatic_obligations`	Decimal	The obligation for grants, payments and other assistance, and the subsidy cost for loans. This is the one money field comparable across all four endpoints.
`non_federal_funding_amount`	Decimal	Non-federal funding the recipient contributes, summed over the transactions.
`indirect_cost_federal_share_amount`	Decimal	The federal share of indirect costs, summed over the transactions.
`face_value_of_loan`	Decimal	Face value of a direct loan or loan guarantee, summed over the transactions.
`loan_subsidy_cost`	Decimal	Estimated long-term cost to the government of a loan or guarantee, summed over the transactions.
`insurance_coverage_amount`	Decimal	Insurance coverage in force, reported only for FEMA's National Flood Insurance Program (`97.022`), whose aggregate records report coverage as obligations. `null` for every other program.
`award_total_obligated`	Decimal	Total obligations as USAspending published them for the award.
`award_total_outlayed`	Decimal	Total outlays as USAspending published them for the award.
`award_total_non_federal_funding`	Decimal	Total non-federal funding as published.
`award_total_face_value_of_loan`	Decimal	Total face value of loans as published.
`award_total_loan_subsidy_cost`	Decimal	Total loan subsidy cost as published.
`covid19_obligated`, `covid19_outlayed`	Decimal	Obligations and outlays from COVID-19 supplemental appropriations, as published.
`iija_obligated`, `iija_outlayed`	Decimal	Obligations and outlays from Infrastructure Investment and Jobs Act appropriations, as published.

Expansions (via `shape`)¶

`recipient`¶

The award's recipient: a shared record, shaped like an entity, that every award to the same recipient points at. Every assistance recipient has one, including the many with no UEI and no SAM.gov registration. Its values are the latest the recipient filed, all taken from that one filing, so an old address never sits beside a new name. null when the award has no recipient, which is the case on aggregate and PII-redacted records (record types 1 and 3).

Field	Description
`uuid`	Tango's recipient identifier. For a recipient with a UEI, it's the same UUID as the entity's.
`uei`	Unique Entity Identifier, when the recipient has one.
`duns`	Legacy DUNS number, on older filings.
`legal_business_name`	Recipient name, normalized.
`legal_business_name_raw`	Recipient name as filed.
`county`	County name of the recipient's address.
`congressional_district`	The recipient's congressional district under current district boundaries, as filed (e.g. `FL-25`). Unlike an entity's, it carries the state prefix.
`congressional_district_original`	The recipient's congressional district as originally reported, before any redistricting, as filed.
`highest_owner`	The recipient's parent organization, as `{uei, duns, legal_business_name, legal_business_name_raw}`.
`business_types`	The recipient's types, as a list of `{code, description}`. These are USAspending's recipient-type codes (`A`–`X`), not SAM.gov's business types. See Business types. `null` when none are filed.

`recipient_address`¶

The recipient record's address, under the same key names as an entity's physical_address, plus the address fields USAspending files beside them, plus the two congressional districts filed on this award. null when every key is empty.

Field	Description
`address_line1`, `address_line2`	Street address.
`city`	City.
`state_or_province_code`	State (USPS code) or province.
`zip_code`, `zip_code_plus4`	Five-digit ZIP code and its four-digit extension.
`country_code`	Country code.
`county_fips`, `state_fips`	County and state FIPS codes.
`foreign_city_name`, `foreign_province_name`, `foreign_postal_code`	Address parts for a recipient outside the U.S.
`congressional_district_original`	The recipient's congressional district as originally reported on this award.
`congressional_district_current`	The recipient's congressional district under current district boundaries, as filed on this award.

`place_of_performance`¶

Where the award's money is spent.

Field	Description
`country`	ISO 3166 alpha-3 country code, e.g. `USA`.
`state_code`, `state_name`, `state_fips`	The state, as a USPS code, name and FIPS code.
`county_fips`, `county_name`	The county.
`city_name`	The city.
`zip_code`, `zip_plus_four`	The five-digit ZIP code and its four-digit extension.
`code`	The place-of-performance code as filed, which distinguishes, for example, a county-wide place from a state-wide one.
`scope`	How wide the place is. See Place of performance scope.
`foreign_location`	Free-text location, for places outside the U.S.

`awarding_office` / `funding_office`¶

The awarding or funding office, resolved against the federal hierarchy: organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name. See Shared response objects.

`assistance_listing`¶

The award's primary assistance listing from the assistance listings catalog: number and title. null when the catalog doesn't list the number; cfda_number still carries it.

`assistance_type`¶

The award's assistance type as {code, description}, from Assistance types.

`period_of_performance`¶

start_date and current_end_date.

`officers`¶

The recipient's five most highly compensated officers, when reported: highly_compensated_officer_1_name, highly_compensated_officer_1_amount, through highly_compensated_officer_5_amount. null when none are reported.

`obligations_by_fiscal_year`¶

The award's obligations per federal fiscal year, summed from its transactions by transaction date, oldest first: a list of {fiscal_year, obligated}, each rounded to cents. null when no transaction carries a date.

`listings`¶

The award's money broken out by assistance listing, one entry per listing, primary listing first. An award funded under several programs has one entry per program, and entries with no listing number group the transactions that named none. The entries sum to the award.

Field	Description
`cfda_number`	The assistance listing number, or `null`.
`is_primary`	`true` on exactly one entry per award: the listing in the award's `cfda_number`.
`obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`	This listing's share of each amount, summed over its transactions.
`transactions_count`	How many of the award's transactions name this listing.
`first_action_date`, `last_action_date`	The first and last of those transactions' dates.

The same entries are available, paginated, at GET /api/assistance/loans/{key}/listings/.

`transactions`¶

Every action on the award, latest first. Also available, paginated, at GET /api/assistance/loans/{key}/transactions/.

Field	Description
`key`	The transaction's identifier.
`modification_number`	The amendment or modification number, when the agency reports one.
`transaction_date`	The action date (`YYYY-MM-DD`).
`action_type`	What the action did (GSDM v1.2). See Action types.
`assistance_type_code`	The assistance type as filed on this action: a GSDM code, or a legacy two-digit code on older actions. See Assistance types.
`correction_delete_indicator`	`C` when the record corrects an earlier one; `null` on an original record. See Correction indicators.
`cfda_number`	The assistance listing this action was made under.
`obligated`	Federal action obligation. Negative on a deobligation.
`pragmatic_obligations`	The obligation, or for a loan the subsidy cost.
`non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`	This action's amounts.
`award_amount_basis`, `award_recipient_basis`	GSDM v1.2 selection codes, as filed.
`action_date_fiscal_year`	Federal fiscal year of the action date.
`last_modified_date`	When the record was last modified at the source.
`initial_report_date`	When the action was first reported.

Code values¶

Assistance types¶

The award's assistance_type is a GSDM code, and it decides the endpoint. /api/assistance/loans/ holds:

Code	Description
`F003`	Direct Loan
`F004`	Loan Guarantee

Older actions carry legacy two-digit codes. These map to this endpoint's GSDM codes:

Legacy code	Description	GSDM code
`07`	Direct loan	`F003`
`08`	Guaranteed/insured loan	`F004`

Record types¶

Code	Description
`1`	Aggregate record: many small payments reported as one record, by county or state, with no individual recipient.
`2`	Non-aggregate record: an award to one recipient.
`3`	Non-aggregate record to an individual recipient, with the individual's identity redacted (PII-redacted).

Action types¶

The twelve GSDM v1.2 action types. Older actions reported with USAspending's legacy A–E codes are recoded to these.

Code	Description
`A1`	New Award
`A2`	Renewal Award
`B1`	Continuation
`C1`	Termination Initiated: Material Failure to Comply
`C2`	Termination Initiated: Mutual Consent
`C3`	Termination Initiated: Recipient-Initiated
`C4`	Termination Initiated: No Longer Effectuates Program Goals or Agency Priorities
`D1`	Closeout
`E1`	Recipient Change
`EX`	Other Action, Non-Financial
`FX`	Other Action, Financial
`G1`	Mixed Aggregate

Award amount basis¶

Code	Description
`A01`	Discretionary Award Amount Selection
`A02`	Formula Award Amount Selection
`A03`	Mandatory Award Amount Selection
`A04`	Fixed Award Amount Selection

Award recipient basis¶

Code	Description
`R01`	Discretionary and Competitive Recipient Selection Award
`R02`	Discretionary and Non-Competitive Recipient Selection Award
`R03`	Non-Discretionary and Competitive Recipient Selection Award
`R04`	Non-Discretionary and Non-Competitive Recipient Selection Award

Both basis codes are new in GSDM v1.2, so older awards don't carry them.

Business types¶

The recipient types USAspending's financial-assistance data uses, carried on the recipient as recipient(business_types). They aren't SAM.gov's business types.

Code	Description
`A`	State Government
`B`	County Government
`C`	City or Township Government
`D`	Special District Government
`E`	Regional Organization
`F`	U.S. Territory or Possession
`G`	Independent School District
`H`	Public/State Controlled Institution of Higher Education
`I`	Indian/Native American Tribal Government (Federally-Recognized)
`J`	Indian/Native American Tribal Government (Other than Federally-Recognized)
`K`	Indian/Native American Tribal Designated Organization
`L`	Public/Indian Housing Authority
`M`	Nonprofit with 501C3 IRS Status (Other than an Institution of Higher Education)
`N`	Nonprofit without 501C3 IRS Status (Other than an Institution of Higher Education)
`O`	Private Institution of Higher Education
`P`	Individual
`Q`	For-Profit Organization (Other than Small Business)
`R`	Small Business
`S`	Hispanic-serving Institution
`T`	Historically Black College or University (HBCU)
`U`	Tribally Controlled College or University (TCCU)
`V`	Alaska Native and Native Hawaiian Serving Institutions
`W`	Non-domestic (non-U.S.) Entity
`X`	Other

Place of performance scope¶

Value	Description
`CITY-WIDE`	City-wide
`COUNTY-WIDE`	County-wide
`FOREIGN`	Foreign
`MULTI-STATE`	Multi-State
`SINGLE ZIP CODE`	Single ZIP code
`STATE-WIDE`	State-wide

Correction indicators¶

Value	Description
`null`	An original record.
`C`	A correction of an earlier record.
`L`, `_`	Published on some records but defined nowhere; served like any other record.

Deleted records are removed rather than served.

Data Sources¶

USAspending – Financial-assistance transactions (the agencies' FABS submissions), including amounts, recipients, places of performance, offices, assistance listings and the published award totals.
Tango – The award rollup from transactions, the per-listing breakdown, the shared recipient record (one per recipient, from its latest filing), organization resolution for awarding_office / funding_office, title, summary and purposes_differ.

Usage Notes¶

Use key for API references. It's the identifier every detail and sub-route URL takes; retired keys keep working.
Use pragmatic_obligations to compare across endpoints. It takes a loan's subsidy cost, the measure that compares with a grant's or a payment's obligation, where obligated does not.
Use listings for per-program money. cfda_number is only the primary program; an award spread across several programs counts in full under it.
Don't expect a recipient on aggregate or PII-redacted records. Record types 1 and 3 carry no recipient identity by design.

Report an issue with this page