Loans¶

Federal financial-assistance awards of direct loans and loan guarantees are exposed at /api/assistance/loans/. For field definitions, see the Loans Data Dictionary. For how assistance awards, transactions, listings and recipients fit together, see the Financial assistance overview. The other assistance endpoints, which take the same filters and shapes: Grant awards · Direct payments · Other assistance.

The endpoint holds every award whose GSDM assistance type is one of:

Loans measure money differently from the other kinds of assistance. face_value_of_loan is the amount lent or guaranteed. loan_subsidy_cost is the estimated long-term cost of the loan to the government, and it's what pragmatic_obligations holds on a loan, so ordering=-pragmatic_obligations ranks loans by what they cost the government and compares with grants and payments. The award_total_face_value_of_loan and award_total_loan_subsidy_cost fields are USAspending's published totals for the award.

Endpoints¶

• GET /api/assistance/loans/ (list, with filtering, search and ordering)
• GET /api/assistance/loans/{key}/ (detail)
• GET /api/assistance/loans/{key}/transactions/ (the award's transactions, latest first)
• GET /api/assistance/loans/{key}/listings/ (the award's money broken out by assistance listing, primary listing first)

Identifiers¶

key is the canonical award identifier, and it's what every detail and sub-route URL takes. The fain (Federal Award Identification Number, on non-aggregate records) and uri (Unique Record Identifier, on aggregate records) are the identifiers agencies report; filter on them to find an award's key.

• Retired keys still resolve. When USAspending retires an award ID in favor of another, the old ID is kept in the award's former_award_keys. Requesting a retired key returns the award that carries it now, with its current key in the body. The sub-routes accept retired keys too.
• An award lives under one endpoint. An award's endpoint follows the assistance type of its latest action. If that type moves to another group (a grant reclassified as a direct payment, say), the award moves to the other endpoint with the same key, and its old URL returns 404.
• A key that names no award on this endpoint returns 404 on detail and an empty list on the sub-routes.

Filtering¶

Swagger is the canonical list of query parameters. Any parameter an endpoint doesn't recognize returns 400, and so does a one-character search, awarding_agency or funding_agency.

Multi-value filter syntax¶

Filters marked "OR via |" match any of several values. Separate them with | or the literal word OR:

cfda_number=93.778|93.767

Award identifiers¶

Recipients¶

A broad recipient term covers only its closest names, not every recipient whose name contains it. To pin one recipient, filter on uei.

Agencies¶

Programs and types¶

Dates and fiscal years¶

All date filters require YYYY-MM-DD. Invalid dates or inverted ranges return 400. See Date filters.

Place of performance¶

Dollars¶

To compare dollar amounts across the four assistance endpoints, read pragmatic_obligations rather than obligated: it's the obligation for grants and payments, and the subsidy cost for loans. See the data dictionary.

Search¶

search runs full-text search over each award's:

• identifiers: key, fain, uri, retired keys and assistance listing numbers;
• recipient name, as normalized and as filed;
• assistance listing titles;
• descriptions: the award's base description and every distinct transaction description.

Descriptions are searchable but aren't returned in responses; read summary and title instead.

The syntax is web-search style:

Words are matched in their English stem forms, so mitigate also matches mitigation.

search combines with every filter and with ordering. Two forms are fast: search alone, ordered by award_date or obligated, and search with only date or fiscal-year filters (award_date, award_date_gte, award_date_lte, fiscal_year, fiscal_year_gte, fiscal_year_lte), ordered by award_date. Any other filter or ordering, or exact=true, takes a slower path.

Ordering¶

ordering= accepts a strict allowlist; prefix a field with - for descending. The default is -award_date.

• award_date
• obligated
• pragmatic_obligations

Examples:

• Newest first: GET /api/assistance/loans/?ordering=-award_date
• Largest first, comparable across endpoints: GET /api/assistance/loans/?ordering=-pragmatic_obligations

Pagination and counts¶

The four list endpoints use cursor-based (keyset) pagination, like the other award endpoints (see Contracts pagination):

• limit sets the page size.
• Follow the next / previous URLs; to build a request by hand, pass the cursor parameter from the next URL.

A filtered request, including one filtered by uei or recipient, is counted exactly up to 10,000 results and estimated above that. An unfiltered request's count is an estimate. Add ?exact=true for an exact count; see Result counts.

The sub-routes use page-number pagination (page, limit):

Response shaping¶

These endpoints support response shaping via ?shape=.

Default shape (list and detail, no ?shape= param):

key,fain,uri,award_date,fiscal_year,assistance_type(code,description),record_type,cfda_number,assistance_listing(number,title),title,obligated,pragmatic_obligations,face_value_of_loan,loan_subsidy_cost,awarding_office(*),funding_office(*),recipient(*),place_of_performance(*),period_of_performance(start_date,current_end_date)

Leaves: key, fain, uri, award_date, last_action_date, last_modified_date, fiscal_year, assistance_type, record_type, cfda_number, title, summary, purposes_differ, obligated, pragmatic_obligations, non_federal_funding_amount, indirect_cost_federal_share_amount, face_value_of_loan, loan_subsidy_cost, insurance_coverage_amount, award_total_obligated, award_total_outlayed, award_total_non_federal_funding, award_total_face_value_of_loan, award_total_loan_subsidy_cost, covid19_obligated, covid19_outlayed, iija_obligated, iija_outlayed, transactions_count, listings_count, assistance_types_count, award_amount_basis, award_recipient_basis, business_funds_indicator, disaster_emergency_fund_codes, funding_opportunity_number, funding_opportunity_goals_text, sai_number, former_award_keys, treasury_accounts_funding_this_award, federal_accounts_funding_this_award, object_classes_funding_this_award, program_activities_funding_this_award, transactions

Expansions:

A few behaviors worth knowing:

• recipient is a shared recipient record, shaped like an entity. Every assistance recipient has one, including the many with no UEI, and every award to that recipient points at the same record. Its values are the latest the recipient filed, all taken from that one filing, so an old address never sits beside a new name. recipient.uuid is Tango's recipient identifier; for a recipient with a UEI it's the same UUID the entity carries. business_types is a list of {code, description} using USAspending's recipient-type codes, not SAM.gov's (codes).
• recipient_address is that record's address, with the entity endpoints' key names, plus the two congressional districts filed on this award. It's null when every key is empty.
• Aggregate and PII-redacted records (record types 1 and 3) have no recipient, so recipient is null on them.
• cfda_number is always a plain field. assistance_listing(number,title) adds the program title from the catalog, and is null when the catalog doesn't list the number.
• officers is null when no officers are reported. obligations_by_fiscal_year is null when no transaction carries a date.
• transactions is also available as a leaf, which returns every key of every transaction. For long award histories, the /transactions/ sub-route pages through them instead.

Access¶

These endpoints are available on every plan, and no field on them is tier-gated (see Plans & Data Access). Call them with an API key or OAuth token (see Authentication), under the same rate limits as the other award endpoints. They aren't alertable: no webhook alert covers financial-assistance awards.

Examples¶

# Loans with places of performance in Virginia, fiscal year 2024
curl -H "X-API-KEY: $TANGO_API_KEY" \
  "https://tango.dev/api/assistance/loans/?pop_state=VA&fiscal_year=2024"

# The costliest loans to the government, with face value and subsidy cost
curl -H "X-API-KEY: $TANGO_API_KEY" \
  "https://tango.dev/api/assistance/loans/?ordering=-pragmatic_obligations&shape=key,award_date,face_value_of_loan,loan_subsidy_cost,pragmatic_obligations,recipient(legal_business_name)&limit=10"

# Loan guarantees only
curl -H "X-API-KEY: $TANGO_API_KEY" \
  "https://tango.dev/api/assistance/loans/?assistance_type=F004&ordering=-award_date"

# One loan's transactions
curl -H "X-API-KEY: $TANGO_API_KEY" \
  "https://tango.dev/api/assistance/loans/ASST_NON_8582749100_073/transactions/?limit=50"

SDK examples¶

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

The official SDKs don't yet expose first-class methods for these endpoints. You can call them through the SDK's internal HTTP helper.

import os

from tango import TangoClient

client = TangoClient(api_key=os.environ["TANGO_API_KEY"])
data = client._get(
    "/api/assistance/loans/",
    params={"pop_state": "VA", "fiscal_year": 2024, "limit": 25},
)
for award in data["results"]:
    print(award["key"], award["award_date"], award["obligated"])

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/assistance/loans/", {
  pop_state: "VA",
  fiscal_year: 2024,
  limit: 25,
});
for (const award of data.results) {
  console.log(award.key, award.award_date, award.obligated);
}