Financial assistance¶

Federal financial assistance is money an agency gives a recipient to carry out a public purpose, rather than to buy something for the government: a research grant, a disaster loan, a farm subsidy payment, flood insurance. It's reported separately from contracting, through USAspending's financial-assistance data, under its own data standard (the Governmentwide Spending Data Model, or GSDM).

Tango serves it at /api/assistance/, one endpoint per kind of assistance. This page explains how that data is shaped. Each endpoint's API reference covers how to query it, and its data dictionary defines every field:

All four award endpoints take the same filters, shapes and ordering, and share pagination and result counts, response shaping and agency search. They're available on every plan, with no tier-gated fields (Plans & Data Access), and they aren't alertable through webhooks.

Opportunities versus awards¶

These two are easy to confuse:

An award records the funding opportunity it was made under in funding_opportunity_number when the agency reports one, so you can filter awards by the opportunity number you found on /api/grants/.

Four kinds of assistance, four endpoints¶

Every award carries a GSDM assistance type, and the type decides which endpoint it's under:

Older records use the legacy two-digit assistance type codes; Tango maps those to the GSDM codes (each endpoint's data dictionary lists its own, e.g. grant awards).

The four endpoints share every field, filter and shape. They're split because the kinds of assistance measure money differently. A grant's obligation is money out the door; a loan's face value is money lent, and what the government actually spends on it is the subsidy cost. That's why each award carries pragmatic_obligations: the obligation for grants, payments and other assistance, and the subsidy cost for loans. It's the one figure you can compare or add up across all four endpoints.

An award's type can change. An award takes the assistance type of its most recent action. When an agency reclassifies an award (a grant later reported as a direct payment, say), the award moves to the other endpoint, keeping its key, and its old URL returns 404.

Awards and their transactions¶

Agencies report financial assistance one action at a time. Each new award, continuation, amendment, termination or closeout is a separate transaction in USAspending, with an action type such as A1 (New Award), B1 (Continuation) or D1 (Closeout).

Tango rolls each award's transactions up into one award record:

• Money is summed over the award's transactions, so obligated is the award's net obligation, deobligations included.
• Dates come from the transactions: award_date is the first action's date, last_action_date the most recent, and fiscal_year the federal fiscal year of the first action.
• Descriptive fields, such as the assistance type, recipient and place of performance, come from the most recent action.

The transactions themselves stay available, latest first, as the transactions expansion or at each endpoint's /{key}/transactions/ sub-route. obligations_by_fiscal_year sums them by fiscal year, for an award that spans several years.

USAspending also publishes its own award totals (award_total_obligated, award_total_outlayed and the others), plus the COVID-19 and Infrastructure Investment and Jobs Act amounts. Tango serves those as published, alongside its own sums.

Assistance listings (CFDA)¶

Every assistance program has an assistance listing number, still widely called a CFDA number: 93.778 is Medicaid, 10.551 is SNAP. The assistance listings endpoint is the catalog of programs.

An award's cfda_number is its primary listing, and that's what the cfda_number filter matches. But one award can be funded under several programs, with each transaction naming the program it's paid from. Counting such an award's whole amount under its primary program overstates that program and misses the others.

The listings expansion, also at /api/assistance/{type}/{key}/listings/, breaks the award's money out by listing, one entry per program. Exactly one entry is marked is_primary, and the entries sum to the award. Use listings whenever the question is per program: how much a program obligated, or every award that drew on it.

Award IDs that change¶

USAspending identifies an award by a unique award ID, which is the award's key in Tango. Agencies sometimes correct an award's identifiers, and USAspending then retires the old ID in favor of a new one. Tango keeps the retired IDs in the award's former_award_keys, and requesting a retired ID returns the current award, with its current key in the body. A link or a stored ID keeps working after the award is re-identified.

Recipients¶

Assistance goes to a far wider range of recipients than contracts do: states, counties, universities, tribes, nonprofits, businesses, and individual people. Most of them never register in SAM.gov, so most assistance recipients have no UEI.

So assistance recipients get records of their own. Every recipient (with a UEI, with only a legacy DUNS, or known only by name) has one shared recipient record, shaped like an entity, and every award to that recipient points at it through recipient(...). The record holds the latest values the recipient filed, all from that one filing: its name as normalized and as filed, its UEI and DUNS when it has them, its address, its parent organization in highest_owner, and its recipient types in business_types.

When a recipient has a UEI, its record carries the same UUID as the SAM.gov entity, and the uei filter finds its awards. The recipient filter (grant awards, for example) matches names on every recipient record, UEI or not, returning each term's closest names rather than every name that contains it.

The award itself keeps only what belongs to that one filing: the recipient's two congressional districts as filed on the award, shown in recipient_address(congressional_district_original,congressional_district_current) beside the record's address.

Two kinds of records have no recipient at all, by design. record_type says which:

• Aggregate records (1): many small payments, often to individuals, reported as one record by county, state or country. They carry a uri instead of a fain.
• PII-redacted records (3): an award to an individual person, with the person's identity removed.

On both, recipient is null. Everything else on the award (amounts, program, agency, place of performance) is still there.

Descriptions, summaries and titles¶

Agencies write a description on every transaction, and an award's descriptions can run long and change from action to action. Tango doesn't return them. Instead each award has:

• summary: a plain-language summary of what the award funds, written from its descriptions;
• title: a short title, at most 60 characters;
• purposes_differ: true when the award's transactions describe different purposes, which is a hint that the award funds more than one thing.

The full descriptions are still searchable: ?search= matches every word of the award's base description and of each distinct transaction description.

Where the data comes from¶

All of it comes from USAspending's financial-assistance data, which is built from the agencies' own submissions. Tango refreshes it daily. On top of the source data, Tango adds:

• the award rollup and the per-program breakdown;
• the awarding_office and funding_office resolution against the federal agency hierarchy;
• summary, title and purposes_differ.