--- description: "Overview of the Tango API β€” what data it covers, how to authenticate, and where to find endpoint references, guides, and SDKs." updated: 2026-10-30 --- # Welcome to Tango API Documentation The Tango API provides comprehensive access to federal procurement and assistance data, including contracts, grants, entities, and opportunities. This documentation will help you integrate with our API quickly and effectively. ## What is Tango? Tango is an integrated platform that consolidates federal procurement and assistance data from multiple sources (FPDS, USAspending, SAM) into a unified system. Our API provides: - **Contract Data**: Federal contract awards, modifications, and transactions - **Financial Assistance Data**: [Grant, loan, direct-payment and other assistance awards](api-reference/assistance.md) and their transactions (USAspending), plus [grant opportunities](api-reference/grants.md) (Grants.gov) - **Entity Information**: Vendor and recipient details with business classifications - **Opportunity Data**: Contract opportunities and solicitation notices (SAM.gov) - **Agency Data**: Government department, agency, and office information - **Award Announcements**: [The Department of War's daily contracts release and MakeGov-generated announcements](api-reference/award-announcements.md) of new civilian IDVs and OTAs - **Procurement Forecasts**: Upcoming procurement opportunities across many agencies - **State and Local Opportunities**: Solicitations and forecasts from state, local, and education buyers - **Webhooks**: Near-real-time notifications when new data is available (awards, opportunities, entities, grants, forecasts) ## Choose a starting point Start with the path that matches what you are building: - **Calling the HTTP API directly:** Follow the [Quick Start Guide](getting-started/quick-start.md) to create a key and make a working request in cURL, Python, or JavaScript. - **Building in Python:** Install `tango-python` and open the [Python SDK guide](sdks/python/index.md). - **Building in Node or TypeScript:** Install `@makegov/tango-node` and open the [Node SDK guide](sdks/node/index.md). - **Connecting an AI assistant:** Use the [hosted MCP server](mcp/index.md) through Claude, ChatGPT, Cursor, or another MCP client. - **Reacting to new or changed records:** Start with the [Webhooks guide](webhooks/index.md), then choose a [recipe](webhooks/recipes/index.md). If you are not sure, use the Quick Start Guide first; it teaches the request and response model that the SDKs and webhooks build on. ### Install an SDK Python: ```bash pip install tango-python ``` Node or TypeScript: ```bash npm install @makegov/tango-node ``` ### [Swagger documentation](https://tango.dev/api/) See the full documentation for the endpoints. ### [OpenAPI spec (JSON)](https://tango.dev/api/openapi.json) Full endpoint definitions, parameters, and response models in one fetch β€” for tools, scripts, and AI consumers. ### [API Reference](api-reference/index.md) Filtering, ordering, and pagination by endpoint (curated reference; Swagger remains canonical for full surface area). ### [Data Dictionary](data-dictionary/index.md) Field definitions for API resources. ### [Rate limits](guides/patterns/rate-limits.md) Learn how to read rate limit headers, handle 429s, and retry responsibly. **Machine-readable:** For AI and scripts, use the [OpenAPI spec (JSON)](https://tango.dev/api/openapi.json), the [single-page HTML reference](https://docs.makegov.com/print_page/), or the [combined markdown](https://docs.makegov.com/all.md) (all docs in one file). ## Key Features ### πŸ” Flexible Authentication - **API Keys**: Simple server-to-server integration - **OAuth2**: For web applications and user tokens ### πŸ“Š Rich Data Model - **Comprehensive Coverage**: Contracts, grants, entities, opportunities - **Historical Data**: Years of federal spending data - **Real-time Updates**: Frequent data refreshes + optional webhooks for near-real-time notifications ### ⚑ High Performance - **Smart Filtering**: Efficient query optimization - **Pagination**: Handle large result sets - **Caching**: Fast response times - **Rate Limiting**: Fair usage policies ### πŸ” Advanced Search - **Full-text Search**: Search across titles and descriptions - **Complex Filtering**: OR/AND patterns for precise queries - **Geographic Search**: Location-based filtering - **Date Ranges**: Flexible temporal queries ### 🎯 Response Shaping - **Custom Field Selection**: Request only the data you need to reduce payload size - **Nested Expansions**: Include related objects (recipients, offices, transactions) in a single request - **Flattening Support**: Convert nested JSON to flat structures for easier consumption - **Flexible Aliasing**: Rename fields to match your application's naming conventions Learn more in the [Response Shaping Guide](guides/patterns/response-shaping.md). For field definitions, see the [Data Dictionary](data-dictionary/index.md). ### πŸ”” Webhooks Subscribe to event notifications when new data is available (awards, opportunities, entities, grants, forecasts). Learn more in the [Webhooks Partner Guide](webhooks/index.md). ### MCP (AI agents) Tango is available as a one-click install in both major assistant directories β€” the [Tango connector](https://tango.dev/claude) for Claude, and the [Tango app](https://tango.dev/chatgpt) for ChatGPT. Sign in with your Tango account; no API key to configure. Cursor and any other MCP-compatible client can connect to the same hosted server directly. The Tango MCP server exposes tools to discover, search, and get details on contracts, opportunities, entities, and more. Learn more in the [MCP (AI agents) guide](mcp/index.md). ## Data Sources Tango integrates data from authoritative federal sources: - **FPDS** (Federal Procurement Data System) - Contract awards and modifications - **USAspending** - Financial assistance and sub-award data - **SAM.gov** - Entity registrations and contract opportunities - **Grants.gov** - Federal grant opportunities - **Agency Systems** - Direct agency data feeds including the [Federal Hierarchy](api-reference/concepts/federal-agency-hierarchy.md) ### [Provenance](api-reference/concepts/provenance.md) Learn more about our data sources and how we use them in [Provenance](api-reference/concepts/provenance.md). ## [Changelog](CHANGELOG.md) See what's new and what's changed in each release in the [Changelog](CHANGELOG.md). --- --- description: The consumer-facing change history for Tango and the Tango API β€” what changed for API users, release by release. tags: [changelog, api] --- # Changelog This is the most up-to-date change log for [Tango](https://tango.makegov.com/) and the [Tango API](https://tango.makegov.com/api/). The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added ### Changed ### Deprecated ### Breaking ### Fixed ### Internal / Infra ## [5.17.0-1] - 2026-11-13 ### Changed - **The pricing page lists GSA eBuy and Teams as Medium and above.** A team lets colleagues share one plan's limits; contact us to set one up. - **Your profile and signup ask for your company** rather than your organization. - **If you're on a team, your usage summary and usage alerts measure the team's shared limits**, not only your own requests, and your profile shows the team as your company. - **Support emails and help links point to support@makegov.com.** ### Breaking - **GSA eBuy requires a Medium plan or above.** `/api/ebuy/requests/` and `/api/opportunities/?domain=ebuy` refuse a lower plan with 403 `tier_required`, and `/api/ebuy/access/` reports `reason: "tier_required"`. ### Fixed - **On the pricing page, a Medium subscriber's Small card offered an upgrade**; it now offers a downgrade. - **On the pricing page, an Enterprise subscriber was offered an upgrade to Small, Medium, and Large**; those cards now offer a downgrade. - **An Enterprise subscriber can no longer start a second, self-serve subscription from the pricing page**; changing an Enterprise plan goes through sales. - **An Enterprise subscriber can no longer cancel from the downgrade form**; ending an Enterprise plan goes through sales. ## [5.16.2-5] - 2026-11-12 ### Changed - **Terms of Service v2.0.0** β€” applies to accounts created from November 12, 2026, and to all accounts from December 1, 2026 ([terms](https://tango.makegov.com/terms/)). ## [5.16.2-3] - 2026-11-10 ### Changed - **MCP clients running on your own machine can now connect**: OAuth Dynamic Client Registration accepts loopback redirect URIs (`http://localhost`, `127.0.0.1`, `[::1]` on any port), so local agent hosts reach the Tango MCP server without any onboarding step. ### Fixed - **Opportunities an agency archives early no longer stay `active`**: an opportunity SAM.gov marks archived now reads `active: false` even when its scheduled archive date hasn't arrived. ## [5.16.2-2] - 2026-11-09 ### Fixed - **`/api/forecasts/` no longer lists forecasts an agency has withdrawn**: a forecast that drops out of its agency's latest published list is now hidden, and it returns if the agency republishes it, so forecast counts fall to match what agencies currently publish. ## [5.16.2-1] - 2026-11-06 ### Fixed - **Keyword search combined with a single agency no longer drops matches**: adding a date range or another filter (such as `uei`) could return an empty page while `count` reported results; those results now appear, on a later page if needed. ## [5.16.0-1] - 2026-11-03 ### Fixed - **Sorting subawards by `last_modified_date`** no longer times out. ## [5.15.0-1] - 2026-10-31 ### Added - **`?key=` filter on `/api/subawards/`** β€” one or more subaward keys (`key1|key2`), the same identifier the detail endpoint takes. - **Subaward entity and place ids** β€” every subaward carries `recipient_id`, `prime_recipient_id`, `recipient_parent_id` and `place_of_performance_id` (the entity and place records the response's details now come from), `pop_cd_original` and `pop_cd_current`, plus `amount_suspect` for an implausible reported amount. - **`?include_retired=true` on `/api/subawards/`** β€” subaward reports USAspending has retired carry `retired_at` and are omitted from lists unless asked for; a detail lookup always answers. ### Changed - **`fsrs_details.last_modified_date` is a timestamp** β€” the instant the winning feed last touched the report, rather than the text each feed published. - **Subaward `key` is now the report UUID** β€” `GET /api/subawards/{key}/` returns and takes the lowercase UUID that `fsrs_details.id` already exposed, instead of an integer; `fsrs_details.id` is lowercase. API version 5.15.0. - **Subaward `place_of_performance.state` is the state code, and `subaward_recipient.duns` is always null** β€” both now come from the place and entity records. ### Deprecated - **`fsrs_report_id` stays requestable as a shape leaf until 2027-04-30** β€” it answers `key` in its pre-5.15.0 uppercase spelling, off `expand(*)`; it leaves with the integer keys. - **Old integer subaward keys keep working until 2027-04-30** β€” `GET /api/subawards/{int}/` answers 301 to the UUID URL with `Deprecation` and `Sunset` headers, and `?key=` accepts integers; after the sunset both are removed. ### Breaking - **Seven denormalized recipient fields leave the subaward shape** β€” `prime_awardee_name`, `recipient_name`, `recipient_dba_name`, `recipient_duns`, `recipient_parent_name`, `recipient_parent_duns` and `recipient_business_types`; the names come from `prime_recipient` and `subaward_recipient`. ### Fixed - **Amended subawards no longer appear twice** β€” each subaward report is one record carrying its latest amount and date, so about 7,100 superseded copies disappear and subaward lists, counts and totals stop double-counting amended reports. - **About 1,800 subaward records that stopped updating in May are current again** β€” source amendments to them never reached the API; they now load like every other change. ## [5.14.0-1] - 2026-10-30 ### Added - **Award announcements at `/api/news/award_announcements/`**: one endpoint for the Department of War's daily contracts release and MakeGov-written announcements of new civilian IDVs and OTAs. Every row names its `source`, which you can filter on; generated text is written from FPDS data with a language model and is not government text. Available at every tier, with `alerts.award_announcement.match` for filter alerts. ## [5.13.0-1] - 2026-10-29 ### Added - **`fsc` filter on DIBBS RFQs, RFPs and awards**: filter by Federal Supply Class, the NSN's first four digits, with `|` for several (`?fsc=6515|6530`); it works in `dibbs_rfq` / `dibbs_rfp` alerts too (refs #4123). ### Fixed - List endpoints such as `/api/entities/` and `/api/opportunities/` could occasionally return a JSON array instead of the usual paginated object for a repeated request. They now always return the paginated object. ## [5.12.1-2] - 2026-10-27 ### Added - **Financial assistance awards** β€” `/api/assistance/grants/`, `/loans/`, `/direct_payments/` and `/other/` serve USAspending assistance awards with filters, search, response shaping, transactions and per-program listings. See [Financial assistance](https://docs.makegov.com/api-reference/assistance/). ## [5.11.1-3] - 2026-10-24 ### Fixed - **List counts are exact up to 10,000 results** β€” `count` on `/api/opportunities/`, `/api/notices/`, `/api/contracts/` and `/api/idvs/` used to be an estimate past 1,000 results, and on agency-scoped filters it ran far too low (1,401 for 17,677 VA notices). Past 10,000 it is still an estimate, labelled `approximate`, and never lower than 10,001. - **`?exact=true` on `/api/opportunities/` returns the exact count** β€” past 1,000 matches it returned the same estimate, labelled `exact`, and `next` stopped at the estimated row; it now counts every match and pages through all of them. ## [5.11.1-2] - 2026-10-23 ### Changed - **`/api/assistance_listings/` carries SAM.gov's current catalog** β€” 608 new programs, updated titles and text for renamed ones, and 165 retired programs that assistance awards still cite. ### Fixed - **Assistance listings return `popular_name`** β€” it was never loaded, so every listing came back without one. ## [5.11.1-1] - 2026-10-22 ### Changed - **A single rare or unknown word no longer returns unrelated opportunities** β€” `?search=` on `/api/opportunities/` and `/api/notices/` with one word that matches fewer than 10 opportunities now returns just those matches, and `count` reflects them, instead of adding ten loosely related titles. ### Fixed - **An office name that several offices share matches all of them** β€” `?agency=W6QK ACC-APG` could return nothing; one that is also its agency's name (`DEFENSE THREAT REDUCTION AGENCY`) now means the agency. `meta.resolved_filters` adds `orgs_sharing_name`. - **Subaward offices** β€” some subawards returned an error when `awarding_office` or `funding_office` was requested; they now return the same offices as their prime award. - **Quoted phrases and hyphenated words find awards** β€” `?search="child development center"` or `?search=F-35` on contracts, IDVs, OTAs and OTIDVs returned no results; they now return the awards whose descriptions contain them. - **`?group_by=department` on the metrics endpoints returns department codes** β€” entity, NAICS and PSC metrics returned `"department": null` on every row; each row now carries the funding department's numeric CGAC code (DoD is `97`). ## [5.11.0-1] - 2026-10-19 ### Added - **Obligations by fiscal year on contracts and OTAs** β€” `shape=obligations_by_fiscal_year(fiscal_year,obligated)` on `/api/contracts/`, `/api/otas/` and nested award shapes returns obligations per federal fiscal year, each rounded to cents; null when no transaction is dated. - **The same field is always null on IDVs and OT IDVs** β€” their transactions report a running lifetime total rather than each action's obligation, so there is no per-year split. - **See why an attachment has no `extracted_text`** β€” `attachments(extraction_status)` on `/api/opportunities/` and `/api/notices/` reports `pending`, `extracting`, `completed`, `failed` or `unsupported` per document. Free on every tier, returned only when named (not in `attachments(*)`). ### Changed - **Unextractable attachments now report `unsupported`** β€” ZIP, DWG, WordPerfect, Access and similar files newly processed read `unsupported` rather than `failed`, so `failed` means a real extraction failure. Older files may still read `failed`. ### Fixed - **`uei` on `/api/contracts/`, `/api/idvs/`, `/api/otas/` and `/api/otidvs/` accepts several UEIs joined by `|`** β€” a multi-UEI value used to return zero results with no error; it now returns awards to any of the listed recipients (up to 500 per request). ## [5.10.0-1] - 2026-10-16 ### Added - **Filter contracts and IDVs by commercial item acquisition procedures** β€” `/api/contracts/` and `/api/idvs/` accept `commercial_item_acquisition_procedures` (`A`–`E`, multi-value via `|`), so `=E` isolates DoD Section 803 CSO awards. ## [5.9.1-9] - 2026-10-13 ### Fixed - **Paging `/api/notices/` and `/api/opportunities/` returns every match exactly once** β€” on results over 1,000 rows, later pages could come back as `Invalid page` and same-day records could repeat or go missing. `count` above 1,000 is still an estimate unless you pass `exact=true`. - **Keyword search on nested award endpoints returns the scoped matches** β€” `search` with no other filter on `/api/idvs/{key}/awards/`, `/api/entities/{uei}/contracts/` and the other nested award lists returned an empty page, and the entity lists reported a table-wide count. - **Vehicle filters `vehicle_type`, `type_of_idc` and `contract_type` no longer return wrong rows for a multi-character value** β€” `vehicle_type=GWAC` returned vehicles of types `A` and `C`. `vehicle_type` now accepts a type name (`GWAC`, `IDC`, `FSS`, `BOA`, `BPA`) as well as its code. ## [5.9.1-7] - 2026-10-12 ### Fixed - **A list's `count` no longer lags the data behind it** β€” a count cached before new records loaded could be served for up to a day, so a search could return rows under `count: 0`. Counts are now recomputed once a load lands. ## [5.9.1-5] - 2026-10-12 ### Fixed - **More complete entity obligation totals** β€” `federal_obligations.total.awards_obligated` counts all years, including awards before FY2008 or without a funding agency, and the `total_awards_obligated_gte`/`_lte` filters follow; `total.subawards_count` drops subawards the source has removed. ## [5.9.1-1] - 2026-10-10 ### Added - **eBuy attachments can return their extracted text** β€” ask for it by name with `?shape=attachments(extracted_text)` on `/api/ebuy/requests/`. It is never part of a default response or `attachments(*)`, and an attachment with no text omits the key. ### Changed - **IDV `gsa_elibrary` no longer returns `extracted_text` or `source_data` unless named** β€” `gsa_elibrary(*)`, `gsa_elibrary()` and the default IDV list and detail shapes drop both keys; ask for them with `gsa_elibrary(extracted_text)`. ### Fixed - **Intermittent 502 Bad Gateway responses** β€” about 1 in 2,300 requests got a 502 from our load balancer before reaching the API; a connection-reuse mismatch between the load balancer and the API servers is fixed. ## [5.9.0-6] - 2026-10-08 ### Fixed - **Account usage includes today** β€” the Overview and Usage pages count today's requests as they happen instead of leaving them out until the next night's rollup. ## [5.9.0-5] - 2026-10-07 ### Fixed - **With `search`, an agency filter scopes to the organization `meta.resolved_filters` names** β€” a token matching both an inactive and a current organization could filter by one while reporting the other. ## [5.9.0-3] - 2026-10-07 ### Fixed - **More agency names resolve to the agency you meant.** `Air Force`, `Coast Guard`, `Army` and `State` resolved to an office or an unrelated body; `VA - U.S. Department of Veterans Affairs` and `Office β€” Department` values returned a `400`. - **`agency=ATF` returns ATF's Federal Register documents.** - **Attachment counts on new opportunities** β€” `meta.attachments_count`, `meta.files_count` and `meta.links_count` are set when an opportunity first syncs, instead of staying `null` until one of its attachments next changes. ## [5.9.0-2] - 2026-10-06 ### Fixed - **A few opportunities were missing attachments** β€” an attachment linked to a notice but not to the notice's opportunity was left off that opportunity's `attachments` list and out of its `meta` counts. About two dozen attachments on 11 opportunities are restored. ## [5.9.0-1] - 2026-10-06 ### Added - **Files and links are counted separately** β€” `meta.files_count` / `meta.links_count` on opportunities and `file_count` / `link_count` on notices count the files attached to a notice and the links listed on it. Any other attachment type counts only in the total, so the two need not sum to it. - **`meta.resolved_filters` reports how each agency value matched.** Every resolved entry carries `matched_by`: `key`, `code`, `name`, `alias` or `fuzzy`. A `fuzzy` match is the one to double-check against the organization name echoed beside it. ### Changed - **Agency filters no longer guess at a name they cannot place.** A value in `agency`, `awarding_agency` or `funding_agency` that is not a code, an abbreviation or a recognizable form of an organization's name used to resolve to the closest-looking organization and return its records. It now resolves to nothing: a `400` on most endpoints, and a text match on the endpoints that fall back to one. Check `meta.resolved_filters` if a saved query built on a loose name stops matching, and use a code or the organization's key for a stable reference. ### Fixed - **An agency's official name returns its records.** 25 agencies, including the Agricultural Marketing Service and the Food and Nutrition Service, returned nothing when filtered by full name while their abbreviation worked. - **An agency name copied from a response resolves to that agency.** `US CUSTOMS AND BORDER PROTECTION`, as `agency_name` prints it, resolved to an unrelated office. - **An agency's abbreviation resolves to the agency.** `NCD`, `PCLOB`, `ATF` and several others resolved to an unrelated office. ## [5.8.1-3] - 2026-10-06 ### Fixed - **Agency filters find more agencies by name and code.** A department's everyday name (`Department of Veterans Affairs`, and likewise Defense, State and Homeland Security) now works on every `agency` filter, and `/api/federal_register/?agency=` now finds the FAA and the Army. ## [5.8.1-1] - 2026-10-05 ### Changed - **Searching for an ID that matches nothing now returns no results** β€” `?search=` on `/api/opportunities/` and `/api/notices/` with a single award number or ID that appears nowhere used to return ten unrelated opportunities. - **Search results that contain your search terms now come before similar-but-not-matching results** β€” `?search=` on `/api/opportunities/` and `/api/notices/` lists matches first, including those found only in attachments. ### Fixed - **`/api/entities/` `state` and `zip_code` filters return all matching entities** β€” they previously missed most entities because addresses are stored in more than one key format; `state` input is now case-insensitive ## [5.8.0-4] - 2026-10-05 ### Added - **Budget accounts add `request_only` rows** β€” current-law accounts that appear in the President's Budget but have no Treasury data, such as NIH's request; obligations are null. Filter with `account_category=request_only`. - **Budget accounts add `proposed` rows** β€” recurring President's Budget requests for programs Congress never created, such as the EV Fund; obligations are null. For a current-law request total, filter `account_category__in=budgetary,request_only`. ### Fixed - **Budget account sorts put empty values last** β€” every `/api/budget/accounts/` `?ordering=` lists accounts with no value last, and pages no longer repeat or skip rows; the `/recipients/` and entity `/budget-flows/` drill-downs list rows with no contract spend last. - **Invalid `?ordering=` on `/api/budget/accounts/` now returns 400** β€” an unsupported field used to be silently ignored; the error lists the fields you can sort by. - **Malformed `funding_organization_id` on budget `/recipients/` now returns 400** β€” a value that isn't a UUID used to return a 500. ## [5.8.0-2] - 2026-10-02 ### Fixed - **`X-Results-CountType` no longer reports `approximate` for exact counts on repeated requests.** A list response served from cache always said `approximate`, so an exact count (entities, vehicles, recipient-filtered awards) read as an estimate the second time it was requested. A cached response now carries the count type computed when it was first served. ## [5.8.0-1] - 2026-10-02 ### Added - **Vehicles report how many companies hold them** β€” `/api/vehicles/` list and detail add `holder_count` (distinct companies holding one of the vehicle's contracts) and `order_winner_count` (distinct companies that have won a task order under it) to the default shape. - **Budget accounts say which period their figures run through: `data_through_period`** β€” the latest fiscal year is partial until it reaches 12. It is in the default shape of `/api/budget/accounts/` and filterable (`data_through_period`, `__gte`, `__lte`, `__isnull`). ### Deprecated - **Vehicle `awardee_count` is deprecated** β€” it is the same value as `order_winner_count` and will be removed in the next major API version. ### Fixed - **Alerts created during scheduled maintenance start paused and resume on their own** β€” while a maintenance window is in effect, a new alert comes back `paused` (`is_active: false`) instead of going live and delivering matches from the maintenance work; it resumes when the window closes. - **Award alerts report only awards the government changed after you created the alert** β€” contract, IDV, OTA and OT IDV alerts match an award only when its FPDS last-modified date is on or after the alert's creation, so reprocessing on our side never alerts you about older awards. - **A new alert's first delivery never reaches back into a maintenance window** β€” the first check still covers up to the previous 24 hours, but starts no earlier than the end of the latest maintenance window affecting that alert type. ## [5.7.0-1] - 2026-10-02 ### Added - **Budget accounts report source-data anomalies** β€” `/api/budget/accounts/` adds `source_anomalies` to the default shape, naming each problem found in the source data (such as capped File C contracts). - **Budget accounts carry `account_category`** β€” `budgetary` or `credit_financing`, filterable with `account_category`; credit financing accounts are served but left out of organization budget totals. ### Changed - **Budget account lists sort accounts without enacted budget authority last** β€” the default ordering puts null `enacted_ba` after every other account in an FY and breaks ties by id, so pages are stable. ## [5.6.0-1] - 2026-10-01 ### Added - **Budget responses carry data-as-of headers.** `/api/budget/accounts/` responses include `X-Tango-Data-As-Of` (the File A fiscal year and period, e.g. `2026-P10`) and `X-Tango-Data-Published-At`; both are omitted until a validated publication is live. ## [5.5.0-8] - 2026-10-01 ### Fixed - **Sorting Federal Register documents newest-first by `comments_close_on` or `effective_on` puts undated documents last**, so `ordering=-comments_close_on` returns the latest comment deadlines. ## [5.5.0-4] - 2026-09-30 ### Changed - **Sign-in codes now stay valid for 10 minutes**, up from 3, so a code that a mail filter holds up still works when it arrives; the email says how long it lasts. ### Fixed - **The "Account Already Exists" email now links to the sign-in page** instead of a password reset, since Tango accounts have no passwords. ## [5.5.0-3] - 2026-09-30 ### Added - **The OpenAPI schema marks tier gates.** A gated operation or filter parameter carries `x-tango-access-level`, the lowest access level that can use it, and an operation with tier-gated `shape` fields carries `x-tango-shape-access-level`. ## [5.5.0-1] - 2026-09-29 ### Added - **Award details on opportunities** β€” where SAM has posted an award notice, `/api/opportunities/` can return `awarded`, `award_date`, `award_amount`, `awardee` and `awardee_uei`, filterable with `?awarded=` and `?awardee_uei=`. Older records fill in gradually as they're reprocessed. - **Awards linked to solicitations** β€” when SAM's award notice references its solicitation, the award carries `solicitation_opportunity_id` and the solicitation gets `award_count` plus an `awards` expand of up to ten recent awards. Awards posted without that reference stay unlinked. - **Award details on notices** β€” `/api/notices/` accepts `award_date`, `award_amount`, `awardee` and `awardee_uei` in `shape`, and opportunity alert summaries include `awardee` when present. ## [5.4.0-2] - 2026-09-29 ### Fixed - **Resolving "Department of the Army", "Department of the Navy" or "Department of the Air Force" returns the military department** β€” the organization resolver used to return an unrelated USDA office for the Army and only DoD or a Navy sub-office for the other two. ## [5.4.0-1] - 2026-09-29 ### Changed - **Creating an alert whose agency matches nothing now returns a 400** β€” an agency filter where no `|`-separated term matches an organization used to be saved and never fire. Partial matches are still accepted, as are forecast, grant, exclusion and eBuy alerts, which fall back to the agency text. - **Alert agency values that can never match now return a 400** β€” a value over 150 characters, or one with no agency in it (`|||`, an empty string), used to be saved and never fire. Existing alerts are re-checked only when their filters change. - **Alert filters with a key the alert type doesn't support now return a 400 that names the key** β€” an unrecognized key next to a valid one used to be dropped silently, so the alert matched more than you asked for. - **A resumed alert starts matching from the moment you resume it** β€” records created or changed while it was paused are no longer delivered on resume. Query the matching API endpoint directly if you need that period. - **Tango names itself consistently in search results** β€” every page declares the site name `Tango by MakeGov`; the home page title now leads with it, Terms drops a redundant "for Tango", and the API reference at `/api/` is titled `API reference | Tango by MakeGov`. ### Fixed - **An agency abbreviation shared with a retired duplicate now covers both** β€” `agency=FNS` resolved to a retired FNS record, so Federal Register returned nothing and contract filters missed the live agency; it now resolves to the live agency and includes the retired one's records. - **Alerts keep working through very large data updates** β€” a batch of millions of changed records is now matched in chunks over the following evaluation cycles instead of failing until the alert was paused. Matches arrive late rather than never, and one large batch can arrive as several deliveries. - **Filtering awards by recipient name and the entity `past_performance` expansion pick up new award data again, within about half a day.** They had stopped updating on 2026-09-19. Entity candidates from `POST /api/resolve/` now track registration changes within about a day. ## [5.3.1-1] - 2026-09-28 ### Added - **SBIR topics carry their DoD DSIP cycle** β€” `/api/sbir/topics/` returns `cycle_name` (e.g. `DOD_SBIR_2026_P1_CBZ`) and filters on it exactly with `?cycle_name=`; DoD topics link to their DSIP solicitation by cycle, not only by solicitation number. ### Changed - **Sign-in, verification and usage-alert emails show the sender as Tango by MakeGov and address you by name** β€” usage alerts now come from `no-reply@makegov.com` (previously `noreply@tango.makegov.com`), so update allowlists keyed on the old address; other emails keep theirs. ## [5.3.0-4] - 2026-09-28 ### Changed - **Ordering `/api/vehicles/` by `latest_award_date` is much faster** β€” the value is precomputed per vehicle instead of worked out from every vehicle's IDVs on each request. ### Fixed - **A vehicle's `latest_award_date` is no longer null when one of its IDVs has no award date** β€” it is the newest award date among the IDVs that have one. - **Paging through `/api/vehicles/` no longer repeats or skips vehicles** β€” vehicles that tie on the `ordering` field come back in a fixed order, so each one appears on exactly one page. ## [5.3.0-2] - 2026-09-28 ### Fixed - **`agency=` on SBIR topics, exclusions and budget accounts now reports what it resolved to** β€” list responses carry `meta.resolved_filters` (the organization each token matched) and `meta.warnings`, like every other endpoint with an `agency=` filter. - **`agency=Corps of Engineers` now resolves to the Army Corps of Engineers instead of all of DoD** β€” an agency name no longer loses to a department that only mentions it in its description, on every endpoint that takes `agency` / `awarding_agency` / `funding_agency`. ## [5.3.0-1] - 2026-09-27 ### Added - **Filter eBuy requests and IT Dashboard investments by agency** β€” `/api/ebuy/requests/?agency=` and `/api/itdashboard/?agency=` match a department or agency and everything beneath it, like `agency` on awards, grants and forecasts; `|` combines several, and an unrecognized value falls back to the agency text. - **Filter budget accounts by agency** β€” `/api/budget/accounts/?agency=` accepts a name, abbreviation, or code and returns every account across that department's bureaus; `?shape=organization(*)` returns the resolved organization. - **Filter SBIR topics by agency, including its sub-agencies** β€” `/api/sbir/topics/?agency=` now rolls up the agency hierarchy (`HHS` includes NIH topics); topics and solicitations also expose an `organization(...)` expand. A value is matched as text only when it names no agency (or against topics not linked to one), so a short fragment like `DO` or `NS` that happens to resolve to some organization no longer substring-matches: pass a full abbreviation such as `DOD` or `NSF`. - **Filter exclusions by agency, including every component under it** β€” `/api/exclusions/?agency=DOD` now returns exclusions issued by DoD and its components (Navy, Army, DLA, …), and exclusion alerts accept the same `agency` filter. Each exclusion can also return its issuing agency with `?shape=...,organization(*)`. - **Filter Federal Register documents by agency** β€” `/api/federal_register/?agency=EPA` accepts the same agency names, abbreviations, codes and organization keys as other endpoints; a department such as `DOT` includes documents from its sub-agencies. ### Changed - **`agency` also matches records not yet linked to an organization** β€” on grants, forecasts, protests, eBuy, IT Dashboard, SBIR topics, exclusions and budget accounts, `agency=` now also returns records whose agency couldn't be linked to an organization when their agency text matches the value, so a value like `Judiciary` or `Corps of Engineers` finds those records instead of returning nothing. - **Attachment text comes from the search index** β€” `attachments(extracted_text)` is read from the index behind attachment search; attachments with under 20 characters of text, or not linked to an opportunity, no longer return it. ### Fixed - **Protests filed under the Government Printing Office's old name are linked to the Government Publishing Office**, so `/api/protests/?agency=GPO` includes them. ## [5.2.1-2] - 2026-09-26 ### Fixed - **Contract searches for uncommon terms no longer time out** β€” searches sorted oldest-first, or narrowed by award date or fiscal year, now return in well under two seconds instead of failing with a 504. ## [5.2.1-1] - 2026-09-25 ### Fixed - **Keyword search now finds closed opportunities** β€” `/api/opportunities/?search=…&active=false`, and `search` sent alongside `solicitation_number`, `notice_type` or `award_number`, used to return an empty page; it now searches closed opportunities as documented. - **Notice search honors `active`** β€” `/api/notices/?search=` returns every notice of a matching opportunity, filtered by `active` when you send it, including an open notice on an otherwise closed opportunity; without `active` it now includes closed notices. - **Narrowly filtered searches no longer miss matches** β€” `?search=` combined with a selective filter such as `solicitation_number` or a small agency, and opportunity search alerts, now find every match rather than only those in the top 1,000 overall. - **Search reports an outage instead of an empty result** β€” if the search service can't answer, `?search=` on `/api/opportunities/` and `/api/notices/` returns `503` with a `Retry-After` header rather than zero results. ## [5.2.0-1] - 2026-09-24 ### Added - **Federal Register documents are now an API resource** β€” `/api/federal_register/` serves rules, proposed rules, notices and presidential documents since 1994, filterable by CFR citation, agency, RIN, type, dates and open comment period, with full-text search. - **Federal Register alerts** β€” create an alert with `query_type=federal_register` to be notified (`alerts.federal_register.match`) when a matching document is published or updated. - **Check your eBuy access with `/api/ebuy/access/`** β€” returns whether `/api/ebuy/requests/` is enabled for your account, why not if it isn't, and which of your contracts it covers. It counts against your normal rate limits, not the eBuy daily budget. ### Changed - **eBuy request search also matches attachment text now** β€” `/api/ebuy/requests/?search=` finds a request through text extracted from its attachments (SOWs, pricing schedules, etc.); a match on the title or description still ranks first. ### Fixed - **eBuy alerts can be created now** β€” `/api/webhooks/alerts/` and `/api/webhooks/subscriptions/` rejected `query_type: "ebuy_request"` as "not a valid choice"; both accept it and deliver `alerts.ebuy_request.match`. ## [5.1.0-6] - 2026-09-24 ### Added - **More multiple-award BPAs show up as vehicles** β€” BPAs that FPDS reports without a solicitation number, such as NOAA's NMITS MAS BPAs, are now grouped into vehicles; they carry `is_synthetic_solicitation: true` and a null `solicitation_identifier`. ## [5.1.0-2] - 2026-09-23 ### Fixed - **Contract lists filtered by a smaller or retired agency load reliably** β€” `/api/contracts/?awarding_agency=…` or `?funding_agency=…` sorted by award date could time out for agencies with relatively few contracts, or whose most recent contract is years old; those requests, including later pages, now return quickly. ## [5.1.0-1] - 2026-09-23 ### Added - **eBuy requests are now a first-class endpoint β€” `/api/ebuy/requests/`** β€” search, filter and page the GSA eBuy requests your linked Schedule contract entitles you to, and download their attachments. Requires a paid plan and separate MakeGov authorization; reach out if interested. ## [5.0.1-2] - 2026-09-22 ### Fixed - **New accounts created with an emailed sign-in code get their plan right away** β€” accounts made this way since 4 September were left without a plan assigned and never received a welcome email; the plan is now granted as soon as the code is confirmed, and the affected accounts have been corrected. - **Plan upgrades apply immediately** β€” an API request sent while an upgrade was being applied could leave your account throttled at your previous plan's limits for up to five minutes; the new limits now take effect as soon as the change completes. - **Alert limits apply to your whole account** β€” your plan's alert allowance now counts alerts across all of your webhook endpoints, paused alerts included, instead of per endpoint; existing alerts are kept, but new ones are refused once the account is at its limit. ## [5.0.0-1] - 2026-09-21 ### Changed - **Awards are built on a rebuilt pipeline** β€” all four award types, their transactions and their search index now come from one chain that tracks amended and retracted actions, records where each value came from, and returns lists, filters and searches faster. ### Breaking - 🚨 **`employment_eligibility_verification` and `service_contract_inventory` are booleans on contract and IDV responses, not the strings `"Y"` and `"N"`.** Code that compares either field against `"Y"` has to switch to a boolean test. ## [4.27.0-1] - 2026-09-20 ### Added - **Attachment document roles** β€” `attachments(doc_role)` on `/api/opportunities/` and `/api/notices/` labels each document `requirement`, `instructions`, `pricing`, `terms`, `reference` or `unknown`, with `doc_role_alt` for a close second. Pro+, named explicitly (not in `attachments(*)`); see the [API reference](https://docs.makegov.com/api-reference/opportunities/). ### Breaking - **`/api/vehicles/?shape=opportunity(attachments(extracted_text))` now returns 400.** Attachment text is a Pro+ field everywhere it is served, but the vehicles endpoint applies no tier check, so this path returned document bodies to any caller. Request it through `/api/opportunities/` or `/api/notices/`, where the tier gate applies. - **`attachments(*)` no longer returns `extracted_text`** β€” name it (`attachments(extracted_text)`) to keep receiving document bodies on `/api/opportunities/`, `/api/notices/` and `/api/sled/opportunities/`. Every other attachment field is unchanged. ### Fixed - **Attachment bodies are no longer reachable on a Free plan** β€” `attachments(*)` on `/api/notices/` returned `extracted_text` that the named spelling correctly withheld. - **`/api/notices/` list responses with `attachments(...)` are faster** β€” each notice on a page was fetching its own attachments instead of riding the page's single query. ## [4.26.0-1] - 2026-09-18 ### Added - **Contract appeal decisions are now an API resource** β€” `/api/contract_appeals/` serves Civilian Board of Contract Appeals (CBCA) and Armed Services Board of Contract Appeals (ASBCA) decisions, filterable by board, docket number, appellant, judge, decision type and date, with full-text search. - **The full text of each appeal decision is available on Enterprise plans** β€” request `decision_text` in `shape`; other plans get the rest of the record plus an upgrade hint, and can still search the text. - **Contract appeal alerts** β€” create an alert with `query_type=contract_appeal` to be notified (`alerts.contract_appeal.match`) when a matching decision is published or updated. ## [4.25.3-6] - 2026-09-17 ### Breaking - **Court of Federal Claims protests now come from the court's own ECF/PACER system.** CoFC protests loaded from the earlier CourtListener feed (mostly cases filed before 2026) are removed with their documents, and CoFC protest `id`s change. ## [4.25.3-3] - 2026-09-13 ### Changed - **`first_seen_at` and `last_seen_at` on state and local opportunities now record when the portal was observed, not when we processed it.** Some values move earlier, by up to about 11 days; if you poll with `first_seen_after`, overlap your window by a few days. ### Fixed - **Daily and premium quotas reset reliably at midnight UTC.** Some accounts could previously be rate limited before reaching their full daily allowance. - **Looking up a notice or opportunity by an undashed ID no longer uses extra rate-limit quota.** The redirect to the dashed ID is returned even when you are at your limit. ## [4.25.3-2] - 2026-09-13 ### Added - **Securities and Exchange Commission forecasts.** `GET /api/forecasts/` now covers the SEC (`?agency=SEC`), whose forecast lists incumbent contracts nearing their end; the award date is that contract's end date, and the incumbent, dollar band, PSC, and business lead are in `raw_data`. ## [4.25.3-1] - 2026-09-13 ### Added - **`status_reason=delisted` and `delisted_at` on state and local opportunities.** A solicitation the portal stops listing before its deadline now reads `status=closed` with `status_reason=delisted`, and `delisted_at` says when we first saw it gone; if it is listed again, it reopens. ### Fixed - **Duplicate state and local opportunities are gone.** Duplicate records left behind when a portal changed its identifier are removed; old ids resolve to the current record with a `301`. ## [4.25.2-1] - 2026-09-10 ### Added - **`meta.jurisdiction_declared` on state and local opportunities.** It tells you whether the source itself stated the opportunity's `jurisdiction` β€” a portal field naming the issuer type, or a portal that serves exactly one government β€” or whether we determined it from the name of the issuing body. `false` means we determined it; `null` means nothing established a level at all. ### Changed - **`jurisdiction` is far more accurate, and the `state` bucket is smaller.** Opportunities whose jurisdiction had never actually been determined were being reported as state-level. They now report the level of the body that is really buying, so a great many university, school-district, city and county solicitations move from `state` to `education` or `local`, and a small number move to `unknown`. If you filter `?jurisdiction=state` you will see fewer results and they will be state agencies; `?jurisdiction=local` and `?jurisdiction=education` return several times what they did. ### Breaking ### Fixed - **Georgia school-district and university solicitations report the right jurisdiction.** They were reaching the API as state-level. - **Hawaii opportunities report the county, Department of Education or University of Hawaii that issued them** rather than all reporting as state-level. ## [4.25.1-1] - 2026-09-10 ### Added - **Document text on state and local solicitations, on the Small plan and above** β€” `?shape=attachments(extracted_text)` returns the extracted body of a solicitation's documents. Three things to know. **Ask for the field by name**: `attachments(*)` does not include it, so add `extracted_text` to the expand when you want it. **The key is absent, not null,** whenever the text is not being served to you β€” on a Free plan it is withheld and listed in `meta.upgrade_hints`, and where we have no text for a document it simply carries no key, so read it with a default rather than assuming it is there. And **a document flagged `is_contested` never returns text, on any plan**: the file we retrieved for it does not match what the solicitation listed, so we cannot vouch that its text belongs to this record. Every fact _about_ a document stays free on every plan β€” name, size, page count, character count and extraction status β€” so you can tell whether a body is worth fetching before you fetch it. Searching document text is also free and unchanged: `?search=` matches inside attachments on every plan and returns matching solicitations without any of their text. ## [4.25.0-1] - 2026-09-10 ### Added - **State, local and education solicitations are now an API resource** β€” `/api/sled/opportunities/` and `/api/sled/forecasts/`, with filters for state, level of government, status, agency, category codes, deadlines and documents. - 🚨 **Beta, and complete only for what is currently open.** Every state and territory jurisdiction we read is covered for open solicitations; historical ones are still being backfilled. Field names, filters and response shapes may change while this is in beta. ### Changed - **Solicitation-number filters match every spelling** β€” contracts, IDVs, protests, opportunities and notices now find a number written the FPDS way (`N6600120R0002`) or the SAM.gov and GAO way (`N66001-20-R-0002`), in any case, and accept `|`-separated values. ### Fixed - **CALC labor-category rates honour your plan.** The `idv` and `recipient` expansions on `/idvs/{key}/lcats/` and `/entities/{uei}/lcats/` require a paid plan and were being returned to Free callers. - 🚨 **A daily rate limit could outlast the day it counted.** A daily counter could stop resetting at midnight UTC, leaving an account rate-limited indefinitely; it now re-arms its own reset on every request. ## [4.23.1-2] - 2026-09-04 ### Fixed - 🚨 **Signing in from `tango.dev` works again.** The redesign moved sign-in to `/`, which meant the mirror served the page itself rather than handing you to `tango.makegov.com` β€” so the bot check failed to load and the sign-in code was never sent. Both addresses now behave the same. ## [4.23.1] - 2026-09-04 ### Added - **A comprehensive redesign of everything you reach while signed in.** The account page is now five sections β€” Overview, API, Usage, Billing and Settings β€” each with its own sub-navigation and its own address, replacing the single page everything used to stack onto. - **Overview** opens on what you have actually used: requests today against your limit, thirty days of history, your plan, and your keys. - **Usage** shows requests per day, a breakdown by resource, and how close you are to each of your limits, over the period you choose. - **Billing** gives your subscription, your invoices and the card you are charged on their own pages. If MakeGov invoices you directly, every page says how your account actually bills rather than hiding the tab. - **Settings** holds your profile β€” your name and organization β€” and your notification preferences. - **Light and dark mode** is a control in the account page's top bar. Leave it on System to follow your operating system; the choice is remembered in your browser. - **The OAuth application pages** match the new account page too β€” registering, editing and deleting an application, and reviewing the tokens you have authorized. - **Sign in, sign up and the pages around them** are redesigned, along with the Terms of Service. - **You can withdraw marketing consent** β€” Settings β†’ Notifications shows your current answer, when it was recorded, and lets you change it. It is Tango's own record; if you are already on a Mailchimp list, coming off that list is a separate step. ### Changed - **Signing in now lands you on your account Overview.** The welcome page is gone β€” `/welcome/` redirects there, and a brand-new account starts on Overview too. - 🚨 **Sign in moved to `/`, and creating an account moved to `/start/`.** The old `/accounts/login/` and `/accounts/signup/` addresses redirect and keep any query string, so existing links and bookmarks still work. ## [4.23.0-1] - 2026-09-03 ### Added - **Entities can now return employee count and hiring locations** β€” request `workforce` in your `shape` on any entity endpoint: ```text /api/entities/{uei}/?shape=uei,legal_business_name,workforce(*) ``` ```json "workforce": { "number_of_employees": "100 to 499", "locations": ["CA", "TX", "NY"], "location_count": 58, "last_verified": "2026-08-01" } ``` `number_of_employees` is a published size band, not an exact figure. `locations` lists the states where the company hires, which is often wider than the single address on its registration β€” about 17,000 companies span more than one state, and some span forty. - **`last_verified` tells you how old the employee count is** β€” it comes back inside `workforce` for a reason: it is the date the company itself last attested to these figures, and it ranges from days to over a decade. Read the count with the date, never on its own. `workforce` is `null` for a company we could not confidently match, which is most of them β€” roughly 138,000 entities carry one today. ## [4.22.0-28] - 2026-09-01 ### Added - **Budget flows now return the 10 largest contracts per row** β€” on `/api/entities/{uei}/budget-flows/` and `/api/budget/accounts/{id}/recipients/`, so a big vendor's response stays a usable size. - **A row whose contracts were cut sets `contracts_truncated` and lists its full `piids`** β€” fetch any one you need with `/api/contracts/?uei={uei}&piid={piid}`. ### Fixed - 🚨 **Budget flows listed contracts that weren't the vendor's** β€” on both budget drill-downs, `contracts` matched on PIID alone, pulling in other companies' awards that shared one. Each row now carries only that recipient's contracts. - **Budget-flow responses are dramatically smaller** β€” for a large vendor a single page dropped from thousands of contracts to the handful actually belonging to it. ## [4.22.0-15] - 2026-08-17 ### Added - **Premium endpoints now report their own budget** β€” in `X-RateLimit-Premium-*` headers, including on a 429 (see [Rate limits](https://docs.makegov.com/guides/patterns/rate-limits/)). - **Your account page now shows your premium query budgets** β€” usage, reset, and how to ask for more (see [Rate limits](https://docs.makegov.com/guides/patterns/rate-limits/)). ### Breaking - 🚨 **`GET /badges/version.svg` has been removed.** The endpoint returned an SVG version badge; if you embedded it, it now returns 404. The same versions are still available as JSON from `/api/version` (the API contract version) and `/healthz` (the deployed build). ## [4.22.0-12] - 2026-08-14 ### Changed - **The Micro plan is no longer offered.** Small is now the entry paid plan. If you're on Micro, your price, limits, and features are unchanged. Where the API named Micro as the tier to upgrade to, it now names Small: `required_tier` in a 403 and in `meta.upgrade_hints`, the tier named when a custom cron alert schedule is refused, and the plan suggested by usage recommendations. One knock-on for Micro subscribers: a 403's `current_tier` now reads `Small` rather than `Micro`, because Micro and Small share one access level and that field names the level, not your plan. - **Upgrading your plan is now charged when you upgrade.** The prorated difference for the rest of the billing period is billed at the moment you switch, rather than appearing on your next invoice. If that payment is declined, your plan stays as it was and nothing changes. Downgrades are unchanged β€” the credit still applies to your next invoice. - **Your daily request allowance resets once per day when you move to a higher plan.** Previously every upgrade cleared the day's usage; a second upgrade on the same day now keeps it. The higher plan's limit still applies immediately either way. ## [4.22.0-6] - 2026-08-11 ### Fixed - **Filtering by a department's 4-digit agency code now covers the whole department.** Codes like `7500` (HHS) and `9700` (DOD) matched only the department's own top-level office, so an agency filter that should have returned the department's full contract activity came back empty or errored. Sub-agency codes such as `7530` (CMS) were unaffected. Department abbreviations (`HHS`) and 3-digit codes (`075`) always worked and still do. ## [4.22.0-5] - 2026-08-10 ### Fixed - **Search results now show the matching passage from an attachment far more often.** When `?search=` matched text inside a solicitation's documents, most results still came back without a `snippet` β€” the excerpt was drawn from a much smaller set of documents than the search itself covered, so the passage that caused the match usually could not be quoted. Snippets now come from the same document set the search runs against, so a result that matched on attachment text should carry the excerpt showing why. Request and response formats are unchanged: `snippet` is the same optional field, just populated far more often. ## [4.22.0-3] - 2026-08-08 ### Changed - **A Claude or ChatGPT connector left unused for 90 days now asks you to reconnect.** Access is unchanged while you keep using it β€” connectors refresh in the background every day β€” but one that sits idle for a full quarter has its authorization retired and prompts you to approve it again the next time you use it. ## [4.22.0] - 2026-08-07 ### Added - **The joint venture behind an SBA Mentor-ProtΓ©gΓ© agreement is now identified where we can find it.** SBA publishes only the two firms in an agreement β€” it names no joint venture at all β€” so the JV is recovered by matching SAM registrations, and it appears as a `mentor_protege_jv` relationship from the JV to each of its two members. Viewed from the JV, each partner's `relation` is `member`; viewed from a partner, the JV's `relation` is `joint_venture`. About 690 of roughly 1,900 current agreements resolve to a JV; the rest are not identifiable from published data, and some pairs never formed one. **These links are inferred, and they say so.** Every one carries `source: "inferred"` β€” never the `sba` used for the agreement itself β€” plus `verification_method` naming the evidence (`document_verification` where the JV's own website names both partners, `exact_match` where SAM records a partner as the JV's immediate owner, `name_match` where the JV's legal name is built from both partners' names) and a `confidence` tier. Treat them as a strong lead, not as a fact SBA published. The `mentor_protege` relationship is unchanged and remains exactly what SBA asserts. - **Find an IT investment by an identifier that no longer exists.** Agencies retire an IT investment by folding it into a successor, which leaves any UII you have on file β€” in a citation, a saved query, a bookmarked URL β€” pointing at nothing. `GET /api/itdashboard/?previous_uii=015-000000100` now returns the investment(s) that absorbed it, on every tier, and full-text search covers retired identifiers too, so `?search=015-000000100` finds the successor. ### Changed - **A retired UII on `GET /api/itdashboard/{uii}/` now resolves instead of returning 404.** If exactly one current investment absorbed it, the request redirects (`301`) to that investment, preserving your query string β€” so a client that follows redirects simply gets the right record. If the source split it across several successors, you get a `300` listing each candidate with its title and URL rather than an arbitrary pick. An identifier that was never a real investment still returns `404`. ## [4.21.0] - 2026-08-03 ### Added - **Agency filters now tell you what your search term matched.** List responses that use an agency filter (`awarding_agency`, `funding_agency`, `agency`) include a `meta.resolved_filters` block naming, for each value you passed, the organization it resolved to β€” its name, identifier, hierarchy level, and CGAC code β€” or `null` if it matched nothing. Agency matching is fuzzy, so a term like `HUD` could previously land on an unrelated organization and quietly scope your query to it; you would get a confident, plausible, wrong answer with no way to tell. Now you can see the match and catch it. Anything ignored or matched loosely is also listed in `meta.warnings`. The block appears on successful responses only. ### Changed - **An agency filter that matches nothing now returns a 400 instead of an empty list.** If _every_ value you pass to `awarding_agency`, `funding_agency`, or `agency` fails to match an organization, the request is rejected with a message naming the value, rather than returning zero results β€” which was indistinguishable from "no such records exist". `GET /api/contracts/`, `/api/idvs/`, `/api/otas/`, and `/api/otidvs/` already behaved this way; this brings `/api/subawards/`, `/api/opportunities/`, `/api/notices/`, and `/api/vehicles/` into line. **If some of your values match and others don't, nothing changes** β€” the matching ones still apply and the rest are reported in `meta.warnings`, so multi-value searches like `?agency=7530|7523` keep working exactly as before. `/api/forecasts/`, `/api/grants/`, and `/api/protests/` are unaffected: an unmatched value there still searches their agency text field, so it is a valid search rather than a dropped one. - **Multi-value agency filters work correctly on subawards and contracts.** `?awarding_agency=A|B` was not being split into separate values on `GET /api/subawards/`, or on `GET /api/contracts/` in its default mode β€” the whole `A|B` string was matched as one term. On contracts that returned an empty list; on subawards it matched a single unintended organization and returned results scoped to it. Both now return the union of both organizations, as documented. ### Fixed - **Performance improvements for contract searches.** Some vendor-scoped searches that could previously time out now return normally. Results, ordering, and pagination are unchanged. ## [4.20.0] - 2026-08-02 ### Added - **Department of Education forecasts.** `GET /api/forecasts/` now covers the Department of Education β€” several hundred upcoming requirements, refreshed daily, filterable with `?agency=ED` (or combined, e.g. `?agency=ED|HHS`). Education publishes its forecast as a spreadsheet rather than a feed, so the available fields differ a little from other agencies: you get the contract name as the title, NAICS code, anticipated award date, fiscal year, set-aside, contract type, and the contracting point of contact, plus the funding office, incumbent, and dollar ranges in the record's raw data. There is no free-text requirement description, so `description` is `null` on these records and keyword search matches on the title. Anticipated award dates are the first day of Education's target **federal fiscal quarter** β€” a target of FY2026 Q1 comes back as `2025-10-01`. - **Entity relationships now report the relationship type and its source.** Each entry in the `relationships` expand carries `type` (`prime_sub`, `parent_subsidiary`, `ultimate_parent`, `predecessor`) and `source` (`sam`, `subawards`), both selectable via `shape`. Match on `type` rather than `relation` β€” it is the stable key. - **SBA Mentor-ProtΓ©gΓ© agreements are now available as entity relationships.** Firms in an active SBA Mentor-ProtΓ©gΓ© agreement carry a `mentor_protege` relationship linking mentor to protΓ©gΓ©, with the approval date in `relationship_date`. Viewed from the mentor the partner's `relation` is `protege`; viewed from the protΓ©gΓ© it is `mentor`. Covers roughly 1,900 current agreements, refreshed as SBA republishes. Note that SBA publishes only currently-active agreements, so an agreement that expires or is terminated stops appearing rather than being marked inactive β€” and SBA's data does not identify the joint venture formed under an agreement, only the two firms. ### Changed - **`relation` no longer returns `affiliate` for subcontracting or predecessor ties.** The value collapsed two unrelated relationship types and both directions of a one-way tie, so it could not distinguish "hired this company as a subcontractor" from "was hired by them." It now names the partner's role: `subcontractor` / `prime` for subcontracting, `predecessor` / `successor` for corporate succession. This affects the large majority of relationship entries β€” **if you match on the string `affiliate`, switch to the `type` field**, which is stable and won't churn again. - **An entity linked by its ultimate parent now reads `descendant` instead of `child`.** We only record an ultimate-parent tie when the ultimate owner differs from the immediate owner, so the other end of that tie is never a direct subsidiary β€” it sits at least one company further down the ownership chain. `child` remains correct for immediate parent/subsidiary ties. - **`relationships` entry counts can differ by requested shape.** Entries are de-duplicated after your `shape` selection is applied, so asking for a narrower shape (e.g. `shape=relationships.uei`) can return fewer entries than `shape=relationships` for a company with several distinct ties to the same partner. ### Fixed - **Duplicate entries removed from the `relationships` expand.** Two companies that had each subcontracted to the other produced two identical entries; they now appear as the two distinct ties they are. - **Attachment-text search results are current again.** Between 2026-07-21 and this release, `GET /api/opportunities/?search=…` matched attachment text against a stale index: text extracted from attachments in that window was not searchable, and some attachments that had since dropped out (extraction failed, unlinked from their opportunity) still produced matches. Roughly 36,000 attachments were affected. Newly changed attachments are indexed on the normal refresh cadence again; no client change is needed. ## [4.19.0-4] - 2026-07-28 ### Added - **`X-Tango-API-Version` response header.** Every API response now returns a stable API version (starting `4.19.0`) so you can pin against the contract you built for, independent of our deploy version. ### Changed - **`/api/version` and the Swagger/OpenAPI `version`** now report the API version (`4.19.0`) rather than the build number. ## [4.19.0] - 2026-07-22 ### Added - **Period-of-performance dates on budget drill-down contracts.** The contracts hydrated inline by `GET /api/budget/accounts/{id}/recipients/` and `GET /api/entities/{uei}/budget-flows/` now include a nested `period_of_performance` object (`start_date`, `current_end_date`, `ultimate_completion_date`) alongside the existing `key`, `piid`, `naics_code`, `psc_code`, `obligated`, and `award_date`. You can now tell which of an account's contracts are ending soon β€” the natural "about to recompete / about to end" question β€” directly from the drill-down, without a follow-up lookup on `/api/contracts/`. Dates are `null` where FPDS doesn't carry them. ## [4.18.7] - 2026-07-21 ### Fixed - Bug fixes associated with an enterprise bulk data endpoint. ## [4.18.0] - 2026-07-17 ### Added - **New endpoints: `/api/sbir/topics/` and `/api/sbir/solicitations/`.** Search and filter SBIR/STTR topics across every participating agency (DoD, NIH, NSF, NASA, DOE, DOT and more), plus the DoD DSIP solicitation cycles they belong to. Filter topics by `activity` (`open` / `closed`), `agency`, `year`, `program`, solicitation or topic number, and open/close/release date ranges; order by any date or by `activity`. Each topic links to the parent solicitation it belongs to β€” a DSIP cycle, a SAM.gov notice, or a Grants.gov announcement β€” so you can follow a topic through to the opportunity or grant that funds it. BAA PDFs are available as a `documents(*)` expand on a solicitation. Response shaping (`shape`) is supported on both endpoints. ## [4.17.0] - 2026-07-14 ### Added - **New endpoints: `/api/dibbs/rfqs/`, `/api/dibbs/rfps/`, and `/api/dibbs/awards/`.** Search the DLA Internet Bid Board System (DIBBS) β€” small-purchase requests for quote, large solicitations (RFP/IFB), and awards from the Defense Logistics Agency. Available on every plan, including Free. - `?open=true` returns the RFQs and solicitations **still accepting responses today**, derived from the closing date on each record. Each result also carries `is_open`. - DIBBS is an NSN and part-number world, so `nsn` and `part_number` filter every resource, alongside `solicitation`, `organization`, and full-text `search` across nomenclature and identifiers. RFQs add `set_aside`, `status_code`, `quantity` ranges, and `return_by_date` / `issue_date` ranges; solicitations add `buyer_code` and `issued_date` / `closes_date` ranges; awards add `award_number`, `delivery_order_number`, `awardee_cage`, `entity` (awardee UEI), `award_date` / `posted_date` ranges, and a `total_contract_price` range. - Awards carry the resolved `awardee` entity when the awardee's CAGE code matches a registered entity; `awardee_cage` is always present either way. - **Read this before you total anything.** An award record is a **line item**, not a whole award: a delivery order covering many items appears as one record per item, and `total_contract_price` is the **order's** total repeated on every one of them. Summing it across records will badly overstate spend β€” one real order spans 483 line items that all read $9,000,000.00, so a naive total reports $4.35 billion for it β€” and inflates DIBBS spend overall from $6.0 billion to $33.0 billion. To total spend, count each order once. - Detail lookup is by `uuid`. Response shaping (`?shape=`) is supported on both list and detail. - **New alert types: `alerts.dibbs_rfq.match` and `alerts.dibbs_rfp.match`.** Subscribe to a saved DIBBS filter β€” say, an NSN or part number you supply β€” and get notified when a matching quote request or solicitation is newly posted or updated. Note that an RFQ or solicitation simply reaching its closing date is not itself a change to the record, so it does not trigger an alert. Alerts cover quote requests and solicitations; awards are not alertable. - **New endpoint: `/api/exclusions/`.** Search SAM.gov exclusions β€” debarments, suspensions, and other exclusions from federal awards. Available on every plan, including Free. - `?active=true` returns the exclusions **in force today**, derived from the dates on each record. Each result also carries `is_currently_excluded`. - Filter by `classification_type`, `exclusion_type`, `exclusion_program`, `excluding_agency_code`, `excluding_agency_name`, `uei`, `cage_code`, `npi`, `entity_uei`, `delisted`, and `activate_date` / `termination_date` / `update_date` ranges; full-text `search` across names, excluding agency, and comments. - Detail lookup is by `exclusion_key`. Response shaping (`?shape=`) is supported on both list and detail. - **New alert type: `alerts.exclusion.match`.** Subscribe to a saved exclusions filter and get notified when a matching exclusion is newly issued, revised, or lifted. Note that an exclusion simply reaching its termination date is not itself a change to the record, so it does not trigger an alert. ## [4.16.0] - 2026-07-13 ### Added - **New endpoint: `/api/exclusions/`.** Search SAM.gov exclusions β€” debarments, suspensions, and other exclusions from federal awards. Available on every plan, including Free. - `?active=true` returns the exclusions **in force today**, derived from the dates on each record. Each result also carries `is_currently_excluded`. - Filter by `classification_type`, `exclusion_type`, `exclusion_program`, `excluding_agency_code`, `excluding_agency_name`, `uei`, `cage_code`, `npi`, `entity_uei`, `delisted`, and `activate_date` / `termination_date` / `update_date` ranges; full-text `search` across names, excluding agency, and comments. - Detail lookup is by `exclusion_key`. Response shaping (`?shape=`) is supported on both list and detail. - **New alert type: `alerts.exclusion.match`.** Subscribe to a saved exclusions filter and get notified when a matching exclusion is newly issued, revised, or lifted. Note that an exclusion simply reaching its termination date is not itself a change to the record, so it does not trigger an alert. ### Fixed - **Agency filters now accept an organization UUID.** `agency` on opportunities, `awarding_agency` and `funding_agency` on contracts and subawards, and the vehicles agency filter previously accepted only a name, abbreviation, or agency code β€” passing an organization UUID matched nothing and returned an empty result set rather than an error. Organization UUIDs are exactly what the organizations endpoints return, so the natural "look up an organization, then filter by it" workflow silently produced zero results. All of these filters now accept a name, abbreviation, 3-digit CGAC code, 4-digit FPDS code, or an organization UUID, and every form rolls up to descendants β€” filtering by a department returns records from all of its sub-agencies and offices. - **Documented that `/api/opportunities/` returns only active opportunities by default.** The endpoint restricts results to active opportunities unless the request includes `active`, `solicitation_number`, `notice_type`, or `award_number`, any of which searches the full dataset. Sending `active=false` returns closed opportunities. The `active` parameter was missing from the API reference entirely, so a search scoped to an organization whose opportunities have all closed appeared to return nothing at all. ## [4.15.0] - 2026-07-12 ### Added - **SBA OHA decisions are now available through the protests endpoint.** Decisions from the Small Business Administration's Office of Hearings and Appeals join GAO and the Court of Federal Claims as a third venue. Filter to them with `?source_system=sba_oha`, or exclude them the same way. As with every other venue, the endpoint serves decisions from 2015 onward β€” roughly 1,350 OHA cases, most of them size and NAICS appeals, with new decisions arriving daily. - **Five new protest fields, available on request via `shape`.** `challenged_party` (the firm whose size or status was challenged), `naics_code` (the code at issue in the appeal), `size_standard` (as written, for example `$33.5 million` or `1,000 employees`), `outcome_reason` (why a case was dismissed β€” untimely, moot, withdrawn, lack of jurisdiction, lack of standing, insufficient specificity), and `judge` (the authoring administrative judge). These are populated for SBA OHA decisions and are null for GAO and Court of Federal Claims records, so they are not part of the default response β€” request them explicitly with `?shape=`. They are available on every plan. - **A `naics_code` filter on the protests endpoint**, for finding the size and NAICS appeals that turned on a particular code: `?naics_code=541512`. ### Changed - **The protests `outcome` field can now return `Granted`, `Remanded`, `Reversed`, or `Vacated`.** These come from SBA OHA decisions. GAO and Court of Federal Claims records continue to use only `Denied`, `Dismissed`, `Withdrawn`, and `Sustained`, so existing filters on those four values are unaffected β€” but code that treats the set of four as exhaustive should be widened. ### Fixed - Fixed how rate-limited requests are counted against your daily quota and how retry times are reported. ## [4.14.8] - 2026-07-09 ### Changed - Stripe Checkout now asks for your name and billing address, so invoices and receipts carry the right details. ### Fixed - **Agency filters now accept an organization UUID.** `agency` on opportunities, `awarding_agency` and `funding_agency` on contracts and subawards, and the vehicles agency filter previously accepted only a name, abbreviation, or agency code β€” passing an organization UUID matched nothing and returned an empty result set rather than an error. Organization UUIDs are exactly what the organizations endpoints return, so the natural "look up an organization, then filter by it" workflow silently produced zero results. All of these filters now accept a name, abbreviation, 3-digit CGAC code, 4-digit FPDS code, or an organization UUID, and every form rolls up to descendants β€” filtering by a department returns records from all of its sub-agencies and offices. - **Documented that `/api/opportunities/` returns only active opportunities by default.** The endpoint restricts results to active opportunities unless the request includes `active`, `solicitation_number`, `notice_type`, or `award_number`, any of which searches the full dataset. Sending `active=false` returns closed opportunities. The `active` parameter was missing from the API reference entirely, so a search scoped to an organization whose opportunities have all closed appeared to return nothing at all. - If you cancelled a plan and later wanted to come back, the pricing page could show your old plan as still current and refuse to let you subscribe again. You can now resubscribe normally. - Accounts billed by invoice rather than through Stripe no longer show as "Free" on the pricing page. ## [4.14.6] - 2026-07-08 ### Changed - Agency filters (`?awarding_agency=`, `?funding_agency=`, `?agency=`) resolve substantially faster, especially the first request for an agency code after a deploy. - When a recipient name search times out, the request now fails fast with a `504` instead of retrying against a slower table. Previously such a request could take up to roughly 50 seconds before returning results. ### Fixed - Agency and recipient filters now return a `504` when the database times out, matching every other endpoint. Previously these filters reported a timeout as an empty result set, which was indistinguishable from a search that genuinely had no matching records. Requests with an unrecognized agency or recipient value still return an empty result set, as before. - Webhook alerts filtered by agency could stop delivering shortly after being created, and would not recover on their own. Newly created agency alerts now begin delivering as expected. ## [4.14.4] - 2026-07-07 ### Fixed - Budget account narratives without a subaccount granule now appear in a budget account's `narratives` β€” around 3,500 of these were previously dropped on every data refresh and never surfaced ## [4.14.2] - 2026-07-06 ### Fixed - Planned-maintenance windows now reliably appear on [status.makegov.com](https://status.makegov.com/) β€” some windows announced in 4.14.0 were silently failing to publish - Alerts stay reliable during very large data refreshes β€” an alert evaluating against an unusually large batch of changes could time out and stop delivering; evaluation now processes those batches incrementally - If an alert genuinely can't be evaluated for a sustained period, we now pause it and email you, instead of letting it fail silently β€” resuming the alert clears the error state ## [4.14.0] - 2026-07-05 ### Added - Planned API maintenance now appears on [status.makegov.com](https://status.makegov.com/) as a scheduled-maintenance window (with the expected restore time) instead of unexplained downtime ### Changed - **Raised webhook alert limits on larger plans.** Alert evaluation runs in parallel batches behind the scenes, so match checks stay on schedule at high alert counts. ### Fixed - **Webhooks**: pausing and resuming an alert via `PATCH /api/webhooks/alerts/{id}/` with `is_active: false`/`true` now works. Previously the request returned 200 but the alert kept evaluating (or stayed paused); the alert's `status` field now correctly reflects `"paused"`/`"active"` after the update. Deactivating an alert also takes effect immediately for matches already being processed when it was paused. ## [4.13.0] - 2026-07-04 ### Changed - **Award list endpoints now cap `?limit=` per plan** β€” 100 results per page on standard plans (higher on Enterprise). Requests above the cap return at most that many rows and set an `X-Results-Limit-Clamped` header; use the `next` cursor to page through the rest. ## [4.12.7] - 2026-06-26 ### Changed - Each matched webhook event is now delivered as its own HTTP request with one top-level `delivery_id`. Previously events for the same endpoint could be combined into a single request, so a receiver expecting more than one event in the `events` array now gets one per request. ### Fixed - Webhook delivery payloads now include the top-level `delivery_id` described in the payload format and Slack how-to β€” a UUID that stays the same across retries, so you can use it as an idempotency key to dedupe deliveries. - The "Send test" delivery and sample payload endpoint now return events in the same shape as real alert deliveries (`event_type`, `query_type`, `filters`, `matches`), so you can validate your receiver against a representative payload. Test deliveries stay marked with `test: true`. ## [4.12.4] - 2026-06-23 ### Fixed - Made LinkedIn (and other social) sign-in more resilient. When the identity provider was temporarily rate-limiting us, some login attempts failed with an error; sign-in now stays working through those brief provider hiccups. ## [4.12.1] - 2026-06-18 ### Fixed - Fixed alerts that trigger a Claude Code routine: these deliveries were failing to start the routine, and now send the correct request format so the routine runs reliably with the matched results as context. These deliveries are also sent once and not retried, so a transient hiccup can no longer start the same routine twice. ## [4.12.0] - 2026-06-18 ### Added - Manage your webhook endpoints right from your account page β€” create, edit, and enable or disable them without touching the API. Endpoints that fail to deliver for a sustained period are now disabled automatically, and we email you a heads-up with a link to re-enable. ### Changed - Webhooks are now available on all plans. ## [4.11.0] - 2026-06-18 ### Added - Webhook endpoints can now send custom request headers (such as an `Authorization` header), so alerts can deliver to authenticated destinations β€” including triggering a Claude Code routine when an alert matches. Header values are stored encrypted and are never returned in API responses. ### Changed - Contract data ingestion now runs as one ordered pipeline with a freshness alert, so a stalled refresh is caught within a day instead of silently serving stale data. ## [4.10.0] - 2026-06-17 ### Changed - Webhook alerts are now evaluated against our data lake β€” faster, and no longer paused or throttled for matching too broadly. ### Breaking - The alert filter preflight endpoint (`POST /api/webhooks/subscriptions/check-filter/`) has been removed, along with the automatic pausing of broad alerts. - The `weekly` alert frequency has been removed; use a `custom` cron expression for a weekly cadence. ## [4.9.0] - 2026-06-16 ### Added - Webhook alerts that match too broadly are now paused automatically and you'll get an email explaining how to narrow the filter (use a sub-agency instead of a whole department, add NAICS/PSC/keyword constraints, or split it into several alerts) and a link to re-enable it. A "firehose" filter that matches tens of thousands of records can't be evaluated efficiently, so it's safer to flag it than to let it flood your endpoint. Creating or updating an alert with a too-broad filter is now rejected up front, and a new `POST /api/webhooks/subscriptions/check-filter/` endpoint lets you preview how many records a filter would match before you save it. ### Fixed - Webhook alert evaluation is faster and no longer times out on broad filters; entity, grant, and forecast alerts evaluate against an index instead of a full table scan. ## [4.8.0] - 2026-06-10 ### Added - `/api/forecasts/` now includes USDA procurement forecasts (`source_system=USDA`, ~2,400 records). ### Changed - Labor-category rates (`/api/idvs/{key}/lcats/`, `/api/entities/{uei}/lcats/`) now refresh daily. One-time effect: `modified` timestamps reset table-wide at cutover. - `opportunity_history` on `/api/grants/` detail responses is now populated; it was previously always `null`. - Forecast `modified` timestamps now update only when a forecast actually changes, so `modified_after` filters and webhook alerts reflect true changes. - `/api/protests/`: ~9,900 recovered historical GAO protests are restored, and existing cases carry fresher outcome and decision data. ### Internal / Infra - GSA eLibrary contract metadata refreshes daily through the new ingest pipeline. The `sins` array may list codes in a different order (it is semantically a set), and `last_updated` now tracks GSA's newest published value, including downward corrections. - On `/api/contracts/`, object-valued code/description fields such as `tradeoff_process`, `fair_opportunity_limited_sources`, and `subcontracting_plan` can now be named bare in a `shape` (e.g. `?shape=piid,tradeoff_process`) and behave exactly like `tradeoff_process(*)`, matching how `competition` already works. Previously a bare reference returned a 400 with reason `unknown_field` even though the field was listed in `available_fields`. Shape errors for fields that genuinely require sub-selection now report the reason `requires_subselection` instead of `unknown_field`. ## [4.7.9] - 2026-06-09 ### Changed - **More trustworthy company-match confidence.** Name resolution no longer reports high confidence for near-miss matches (similar-looking but different companies); confidence tiers now require the returned company's name to actually account for what you searched. - **Substantially more accurate company name resolution.** Searching by short names ("Booz Allen"), common abbreviations (GDIT, HII, SAIC), or ticker symbols (LMT, MSFT) now reliably finds the right company, and vendors with several registrations under one parent company return a single, correct match instead of duplicates. ## [4.7.6] - 2026-06-08 ### Changed - **Upgraded `dj-stripe` 2.9.1 β†’ 2.10.3 (#2520).** Under-the-hood plumbing change to the library that mirrors Stripe data into Tango's database: each Stripe object is now stored as a single JSON blob with the same Python attribute names exposed via property accessors. No user-visible change to checkout, billing, or self-serve plan management. Unlocks the queryable churn-feedback work introduced in #2519 β€” we can now ask the database for "subscriptions cancelled because of price" instead of reading each one from the Stripe dashboard. Deploy includes a one-time `djstripe` migration + `manage.py sync_stripe_data` re-sync from the Stripe API (sub-minute given current data volume). ### Internal / Infra - **IT Dashboard ingest moved to the lakehouse pipeline.** Behind-the-scenes plumbing change β€” federal IT investments now load through the Parquet-based sync pipeline. No change to `/api/itdashboard/` responses. ## [4.7.4] - 2026-06-05 ### Added - **Your name on sign-up.** The sign-up form now asks for your first and last name, so Tango can greet you by name and personalize your welcome email. ### Changed - **Refreshed sign-in & sign-up pages.** The login, sign-up, and email-verification screens got a visual and copy polish for a clearer, more consistent passwordless experience. ### Fixed - **Clearer "create your account" page.** When you enter an email that doesn't have an account yet, the account-creation page no longer shows confusing "already have an account? sign in instead" wording. ## [4.7.3] - 2026-06-04 ### Added - **DoD contract-attribution signals on budget accounts.** `/api/budget/accounts/` now returns three new fields by default: `attribution_status`, `attribution_confidence`, and `contract_obligated_estimated`. The underlying USAspending File C data captures only a small share of the Department of Defense's contract obligations, so DoD federal accounts previously looked identical to accounts with no contract activity at all (`contract_obligated` came back `null`), dropping them out of any contract-share filter or ranking. Use `attribution_status` to tell "no contracts" apart from "no source data," and fall back to `contract_obligated_estimated` (an FPDS-based estimate) where the primary figure is missing. All three are `null` for account-years that haven't been backfilled yet. ## [4.7.2] - 2026-06-03 ### Added - **Bot protection on sign-up and email sign-in code requests.** The sign-up form and the "Email me a sign-in code" form on the login page now include a quick Cloudflare Turnstile challenge to keep automated traffic out. You may see a brief verification check before submitting. - **Microsoft sign-in + passwordless email sign-in.** You can now sign in (and sign up) with a Microsoft work or school account, or with just your email and a one-time sign-in code β€” no password and no social provider required. The new "Email me a sign-in code" entry point appears on the login page alongside the social buttons. ### Breaking - **Email sign-up is now open.** Previously Tango required a social provider (Google, GitHub, LinkedIn) to create an account. Sign-up with email + one-time code is now supported, so the `/accounts/signup/` page is reachable. If your integration assumed every Tango user is backed by a social identity, expect to see passwordless email accounts as well. ## [4.7.0] - 2026-06-02 ### Changed - **Entity descriptions are now derived at render time.** `GET /api/entities/{uei}/?shape=…(*)` keeps returning `{code, description}` for `entity_structure`, `entity_type`, `profit_structure`, `organization_structure`, `purpose_of_registration`, and `country_of_incorporation` β€” same payload shape, same values for known codes. Behind the scenes, the description is now derived from a built-in code-to-label map (or, for country, django-genc's country table) rather than read from a stored `*_desc` column. For codes outside the known set, `description` comes back as `null`. `state_of_incorporation(*)` has no map and now consistently returns `{code, description: null}` for every state. ### Breaking - **Entity flag fields now serialize as bool.** Four fields on `/api/entities/{uei}/` change wire type: `registered`, `registration_status`, `uei_status`, `public_display_flag`. JSON `true` / `false` / `null` replace the previous string tokens (`"Active"` / `"Inactive"` / `"Y"` / `"NPDY"` / `"Not Active"`). Webhook alerts (`alerts.entity.match`) ship `registration_status` in the match summary and are subject to the same change. Mapping: `registration_status` `"Active"` β†’ `true`, `"Inactive"` β†’ `false`; `uei_status` `"Active"` β†’ `true`, `"Not Active"` β†’ `false`; `public_display_flag` `"Y"` β†’ `true`, `"NPDY"` β†’ `false` (a non-obvious source token β€” interpret as "Not Publicly DisplaYed"); `registered` `"Y"` β†’ `true`, any other value β†’ `null` (no `"N"` token was observed in production data for this field). Any unmapped source value on any of the four β†’ `null`. None of the four publicly-surfaced fields ever emitted a literal `"N"` token, so no `"N"` β†’ `false` mapping exists on the public surface. **Action for integrators:** webhook filters and client code that compared these fields to string tokens (e.g. `registration_status === "Active"`) need to switch to bool comparison (`registration_status === true`). The 7 `*_desc` top-level fields (`purpose_of_registration_desc`, `entity_structure_desc`, `entity_type_desc`, `profit_structure_desc`, `organization_structure_desc`, `state_of_incorporation_desc`, `country_of_incorporation_desc`) are removed from the default entity payload β€” use the `?shape=…(*)` expansion for any of these to keep getting `{code, description}` derived at render time. - **`source_type` removed from `/api/entities/` output.** The field was auto-set to `"sam"` for every row and duplicated information already exposed via `source`. Any client reading `entity.source_type` should switch to `entity.source`. - **Stricter value sets on two entity enums.** `evs_source` is now constrained to `{"D&B", "E&Y"}` (or null), and `exclusion_status_flag` to `{"Y", "N", "D"}` (or null). Out-of-set legacy values were coerced to `null` during the upgrade. Field shape is unchanged β€” values still serialize as strings. `exclusion_status_flag = "D"` means "delinquent" and is kept intentionally alongside `"Y"` / `"N"`; a matching data-dictionary update at docs.makegov.com is tracked as a follow-up. ### Removed - Internal `field_provenance` JSONB column on entities (and the related CDC changelog tables) is gone. The column was never exposed via the API; field-level arbitration is handled upstream now. (#2376) - The internal `load_entities` / `load_dsbs` SAM ingest loaders are gone. Entity data now flows entirely through the parquet-driven `sync_entities` family β€” no API surface change. (#2296) ## [4.6.12] - 2026-06-01 ### Fixed - **Upgrading your plan now gives you the full daily request allowance right away.** Previously, requests already made on your old tier counted against your new tier's daily budget immediately after an upgrade, so a paid plan could start the day with less headroom than expected. Upgrading to a higher tier now starts you on a clean daily budget. Additionally, requests rejected for exceeding your daily limit (HTTP 429) no longer count toward your daily usage. ## [4.6.11] - 2026-05-29 ### Fixed - **Webhook alerts now deliver reliably again.** Filter-based webhook alerts β€” opportunity, contract, entity, grant, and forecast matches β€” had stopped being evaluated, so matching records were not delivered to your endpoints. Alert evaluation has been corrected and delivery has resumed. ## [4.6.10] - 2026-05-28 ### Changed - **Webhook deliveries now identify themselves.** Outbound webhook requests from Tango β€” including test deliveries β€” now send a `User-Agent` header of the form `MakeGov-Tango-Webhooks/ (+https://docs.makegov.com/)` instead of a generic HTTP-client default. Receivers can use this to recognize, allowlist, and log MakeGov webhook traffic. ## [4.6.8] - 2026-05-26 ### Added - **Federal budget data is now in the API.** A new family of `/api/budget/` endpoints exposes the full federal-account budget lifecycle β€” request β†’ enacted β†’ apportioned β†’ obligated β†’ outlayed β€” for ~2,000 federal accounts per fiscal year across FY17–FY26. Each account includes pre-computed execution ratios, year-over-year and 5-year trends, the contract/assistance/unlinked breakdown, and links to the underlying OMB Appendix. - **List & search**: `GET /api/budget/accounts/?search=acquisition+services+fund&fiscal_year=2024` matches account title, agency, or bureau. Rich filters support pipeline detection (`?apportioned_to_enacted_pct__gte=0.9&obligated_to_apportioned_pct__lte=0.3`), forward-look (`?ba_growth_next_year_pct__gte=0.5&contract_share_of_obligated_capped__gte=0.5`), and request-vs-actual (`?actual_vs_requested_contract__lte=0.5`). - **Drill-down**: each account exposes `/recipients/` (top contract recipients with hydrated contract details inline) and `/quarters/` (TAS-level quarterly obligation/outlay flow, FY21+) β€” both paginated with the standard `count / next / previous / results` envelope. `?shape=*,appendix(*)` adds the President's Budget Appendix object-class breakdown and `?shape=*,narratives(*)` adds the narrative + appropriations text. Both shape leaves return `null` when no data is available for the account-year, so consumers branch on truthiness once. - **Budget as context, not just a destination.** Budget data is embedded where the question is usually being asked: - Organizations get two opt-in budget shape leaves. `GET /api/organizations/{key}/?shape=name,budget_appropriation(*)` returns the "what Congress appropriated" rollup for departments. `GET /api/organizations/{key}/?shape=name,budget_spending(*)` returns the "what this office (and its subtree) is spending on contracts" rollup, walking down the hierarchy so middle-tier orgs aggregate their descendants automatically. Ask for one, the other, or both β€” each has a fixed shape. Both support `?shape=...,budget_appropriation[fiscal_year=2024](https://github.com/makegov/tango/blob/main/*)` for historic views. - Entities get `GET /api/entities/{uei}/budget-flows/` β€” the federal accounts that paid this vendor, paginated, with the surrounding account context (agency, enacted BA, contract share), the funding office hierarchy, and the contracts hydrated inline (key, NAICS, PSC, obligation, award date). ### Fixed - **Procurement forecast refreshes no longer stall when one agency publishes a non-JSON document.** A binary publication from one agency was causing the entire combined-format forecast refresh to fail, leaving other agencies' forecasts (HHS, GSA, DOI, DOL, DOT, VA, NRC, DOE, DHS, COMMERCE, ENERGY, TREASURY) out of date. Unsupported document formats are now skipped per-agency with a warning; remaining agencies refresh normally. ## [4.6.7] - 2026-05-24 ### Added - **Entity metrics now include award counts per period.** `GET /api/entities/{uei}/metrics/{months}/{period_grouping}/` results now carry `awards_count` (distinct prime awards) and `subawards_count` (distinct subawards) alongside the existing `awards_obligated` and `subawards_obligated` dollar sums. Counts participate in `?group_by=agency` / `?group_by=department`, so a single call returns per-agency award counts for a UEI β€” no more N+1 calls to the contracts / subawards endpoints. Counts are aggregated per month at the source; if you request a coarser `period_grouping` (`quarter`, `year`), the counts in each bucket sum the underlying monthly counts β€” read them as "award-months of activity" in that window rather than a global distinct count. ### Fixed - **Attachment-text search is reliably fast on common terms.** `GET /api/opportunities/?search=…` with attachment-text search enabled previously could take several minutes on cold cache for broad terms (e.g. `data governance`) β€” long enough to hit the API timeout. Cold-path wall time on those searches now drops by roughly 30Γ— (e.g. ~5 min β†’ ~10 s for `data governance`), comfortably under the timeout. The set of matching opportunities and per-page results are unchanged. - **`GET /api/opportunities/?search=` is reliably fast on common terms.** Searches matching thousands of opportunities (e.g. `data governance`, `department of state`) β€” including paired with `ordering=-last_notice_date` / `response_deadline` / `first_notice_date`, deep pagination (`?page=10`), and field-selection via `shape=` β€” previously could hit the API timeout when the database cache was cold. Cold-path wall time on these searches now drops by roughly 6-7Γ— and stays well under the timeout. The set of matching opportunities and the per-page results are unchanged. **One caveat for clients that exhaustively crawl results via `?page=N` while attachment-text search is enabled**: the approximate `count` field can come back lower than before, which lowers the maximum `?page=` you can navigate to. If you want the precise total β€” or need to crawl all matches without missing pages β€” pass `?exact=true` (this was already the documented way to opt out of approximate counts; nothing about its behavior has changed). ## [4.6.6] - 2026-05-23 ### Added - **Follow one or many resources with a single webhook alert.** Webhook alerts for opportunities, contracts (including IDVs / OTAs / OTIDVs), grants, and forecasts now accept the same identifier you get from each resource's detail endpoint β€” and you can pass several at once. Use `opportunity_id`, `key` (for contracts and IDV / OTA / OTIDV), `grant_id`, or `id` (for forecasts) in your alert's `filters`, either as a single value or as a pipe-OR list (e.g. `"key": "key1|key2|key3"`). One alert that follows a set of resources is more efficient than one alert per resource, and counts as a single subscription against your tier's alert limit. Up to 500 IDs per filter; the same identifiers are also accepted on the corresponding list endpoints (e.g. `GET /api/contracts/?key=k1|k2|k3`). ## [4.6.5] - 2026-05-22 ### Breaking - **Entity flag fields now boolean.** `registered`, `registration_status`, `uei_status`, `public_display_flag`, `bonding_flag`, `disaster_registry_flag`, `debt_subject_to_offset`, `credit_card_usage`, `edi_information_flag` now serialize as JSON `true`/`false`/`null` instead of string tokens (`"Active"` / `"Inactive"` / `"Y"` / `"N"` / `"NPDY"` / `"NA"`). Webhook subscribers filtering on `registration_status === "Active"` need to switch to `=== true`. Seven `*_desc` companion fields (`purpose_of_registration_desc`, `entity_structure_desc`, `entity_type_desc`, `profit_structure_desc`, `organization_structure_desc`, `state_of_incorporation_desc`, `country_of_incorporation_desc`) are dropped from the top-level entity payload β€” use the `?shape=…(*)` expansions to get `{code, description}` derived at render time. ### Fixed - **`GET /api/opportunities/?search=` no longer times out on common terms.** Searches like `data governance` or `department of state` previously could return a gateway timeout; they now return results reliably. ## [4.6.2] - 2026-05-18 ### Added - **`GET /api/opportunities/?search=` matches attachment text.** `?search=` now searches text from opportunity attachments in addition to notice titles and descriptions. Matched results include a `snippet` centered on the hit. ## [4.6.1] - 2026-05-13 ### Fixed - **`GET /api/vehicles/?search=` matches text from member-IDV descriptions.** Vehicles whose `solicitation_identifier` is a single run-on token (e.g. `RFPCMS2016SPARC`) now match substring queries like `?search=SPARC` via the underlying IDV descriptions. The endpoint's default ordering (`solicitation_identifier, agency_id, uuid`) is unchanged. (issue #2224) ## [4.6.0] - 2026-05-12 ### Added - **Shape aliases: `naics_code(...)` and `psc_code(...)` now work as expand forms.** `?shape=naics_code(code,description)` is accepted as a synonym for `naics(...)` on `/api/contracts/` and `/api/idvs/` (the only award endpoints with a NAICS expand). `?shape=psc_code(code,description)` is accepted as a synonym for `psc(...)` across all award endpoints (`/api/contracts/`, `/api/idvs/`, `/api/otas/`, `/api/otidvs/`). The expanded object comes back under the canonical key (`naics` / `psc`). Bare scalar `naics_code` / `psc_code` is unchanged β€” it still returns the raw code value. (issue #2257) - **`POST /api/webhooks/endpoints/test-delivery/` now accepts `endpoint`.** The canonical field name matches `POST /api/webhooks/subscriptions/`, so SDKs and docs can use one identifier across both calls. The legacy `endpoint_id` field is still accepted as a deprecated alias; if both are provided, `endpoint` wins. `endpoint_id` will be removed in the next major release. (issue #2252) - **`POST /api/webhooks/alerts/` accepts an optional `endpoint` (UUID) field.** Multi-endpoint accounts can disambiguate without dropping to `/api/webhooks/subscriptions/`; single-endpoint accounts can still omit it. (issue #2256) ### Breaking - **Subject-based webhook subscriptions removed (#2267).** Subscriptions now match by saved filters (`/api/webhooks/alerts/`) only β€” `subject_type`, `subject_ids`, and the legacy `resource_ids` / `entity_type` / `entity_ids` / `change_types` fields are no longer accepted by `POST /api/webhooks/subscriptions/` (or `PATCH`). Existing integrations that still send these fields will see them silently dropped. See the alerts guide on [docs.makegov.com](https://docs.makegov.com/) for migration. ### Fixed - **OpenAPI now matches runtime for `ordering`.** `/api/notices/` no longer advertises `ordering` (the endpoint never accepted it β€” every value 400s), and `/api/subawards/` advertises its `ordering` enum as `last_modified_date` / `-last_modified_date` only. SDKs generated from the schema no longer surface an `ordering` kwarg on notices, and the subawards kwarg is typed to the actual allowlist. (issue #2254) - **OpenAPI `ordering` now has a real `enum` on the remaining endpoints.** Completes the schema/runtime parity work started in #2258: `/api/contracts/`, `/api/idvs/`, `/api/opportunities/`, `/api/forecasts/`, `/api/vehicles/`, `/api/vehicles/{uuid}/orders/`, and `/api/gsa_elibrary_contracts/` now declare an explicit `enum` matching each viewset's runtime allowlist (`ordering_fields` βˆͺ `ordering_fields_map.keys()` + their `-` variants). SDK generators emit a typed kwarg instead of a free-form `str`, so invalid values fail at type-check time rather than as a runtime 400. (issue #2262) - **`POST /api/webhooks/alerts/` no longer returns a sibling endpoint's subscription row** when the same user has the same filter `(query_type, filters)` on two different endpoints. The post-create lookup is now scoped by the resolved endpoint instead of user β€” a latent dedup bug that became reachable once multi-endpoint disambiguation was added. (issue #2256) - **`GET /api/webhooks/endpoints/sample-payload/` no longer 500s.** The endpoint previously referenced a subject-type attribute that was removed when subject-based webhooks were deprecated. Returns the alert-only sample set as expected. ## [4.5.2] - 2026-05-11 ### Changed - **Public docs moved to [docs.makegov.com](https://docs.makegov.com/).** The in-app MkDocs site at `tango.makegov.com/docs/*` is gone; legacy URLs 301-redirect to the new host path-preserving (`/docs/getting-started/pricing/` β†’ `docs.makegov.com/getting-started/pricing/`, etc.). Bookmarks keep working. Pricing-tier upgrade responses (`upgrade_url`) and the welcome-email "Docs" CTA now point at the new host directly. ### Fixed - **`/api/otas/` and `/api/otidvs/` pagination no longer 400s on page 2.** Cursor-based pagination on these endpoints used to return HTTP 400 whenever the page-1 anchor row had a NULL `award_date` β€” common on OTAs/OTIDVs because many leading rows have no resolvable award date. Page 2 now succeeds and returns the next slice as expected. No client changes required. (issue #2139) ## [4.5.1] - 2026-05-09 ### Changed - **`/api/notices/`: `?shape=office(organization_id)` is now valid.** The office payload on notices gains `organization_id` as a 7th key, matching the surface already exposed on `/api/opportunities/` and the awards endpoints. The other six keys (`office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`) are unchanged. ### Performance - **`/api/notices/` is materially faster.** The `office` expand no longer fetches full `Organization` rows on every request. Uncached `?limit=100` drops from ~0.36 s to ~0.07–0.1 s. No query parameter changes needed; same shapes work faster. (issue #2236) ## [4.5.0] - 2026-05-09 ### Fixed - **`?shape=case_id,dockets` no longer 500.** Naming `dockets` as a leaf in the protests shape β€” without an inner expand like `dockets(case_number)` β€” used to raise an internal serializer error. The leaf is now equivalent to `dockets(*)` and returns the default docket projection. Detail endpoint mirrors list. (issue #2222) ### Performance - **Five more endpoints are materially faster.** The organization expand on `/api/forecasts/`, `/api/grants/`, `/api/itdashboard/`, `/api/opportunities/` (the `office` expand), and awards (`/api/contracts/`, `/api/idvs/`, `/api/otas/`, `/api/otidvs/`) no longer fetches full `Organization` rows from the database. Uncached `?limit=100` timing across eight endpoints: ~8.7 s total β†’ ~1.9 s total (βˆ’78%); opportunities alone 3.4 s β†’ 0.4 s (βˆ’88%), forecasts 2.1 s β†’ 0.15 s (βˆ’93%). No query parameter changes needed β€” same shapes work faster. (issue #2225, PR #2233) - **`/api/contracts/`, `/api/idvs/`, `/api/otas/`, `/api/otidvs/`: `?shape=awarding_office(organization_id)` and `?shape=funding_office(organization_id)` are now valid.** The office payload gains `organization_id` as a 7th key (the other six β€” `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` β€” are unchanged). Rows that hit the legacy JSON fallback return `{"organization_id": null, ...}`. - **`/api/protests/` is materially faster.** End-to-end on a default `?limit=100` request, latency drops from ~3.8 s to ~80 ms. No API changes; same response shape. ## [4.4.0] - 2026-05-08 ### Added - **Agency filter accepts more identifier forms.** The `agency` / `awarding_agency` / `funding_agency` filters on every endpoint that exposes one now resolve the same way: hand them a name, abbreviation, or code (CGAC, FPDS, AAC, and others) and Tango figures out the matching agency subtree. See the new [Agency search guide](https://docs.makegov.com/guides/patterns/agency-search/). (issue #2207) ### Changed - **Trimmed `?ordering=` whitelist on `/api/vehicles/`.** Removed `awardee_count` and `vehicle_contracts_value` from the v4.3.0 ordering surface β€” both were `Subquery` annotations on `VehicleStats` with no backing index, and their matching `*_min/max` filters were intentionally deferred. The remaining surface is `vehicle_obligations`, `latest_award_date`, `total_obligated`, `award_date`, `last_date_to_order`, `fiscal_year`, `idv_count`, `order_count`. (issue #2202 follow-up) ### Breaking - **Comma `,` is no longer an `AND` separator in filter values; multi-value uses `|` only.** Across every endpoint that accepts smart-text filter values (`naics`, `psc`, set-asides, business types, entity / agency text searches, etc.), a comma is now a literal character in the token value rather than an `AND` separator. `?awarding_agency=HHS,DOD` was previously treated as `HHS AND DOD` (which was always empty β€” a single record can't equal two different values) and is now treated as a single literal value `"HHS,DOD"` (also always empty, but for the literal reason). For union semantics use `|`: `?awarding_agency=HHS|DOD` returns rows in either subtree. For intersection semantics, repeat the query parameter or use multiple separate filter parameters β€” `AND`-joining values inside one parameter has no clear use case in this API. Mixed inputs like `?field=A,B|C` no longer raise a `400 "Cannot combine AND and OR in the same query"` error; they're parsed as `"A,B"` OR `"C"`. The change also fixes the long-standing footgun where federal entity / agency names containing literal commas (`"ENERGY, DEPARTMENT OF"`, `"GENERAL DYNAMICS, INC."`) silently produced empty results when pasted into a filter. Out of scope: `/api/gsa_elibrary_contracts/?sin=`, `?uei=`, `?search=` continue to honor the prior comma-as-AND grammar (separate code path). (issue #2214) ### Removed - **AND-via-comma is fully removed from documentation, swagger, and help text.** Comma-as-AND no longer works anywhere downstream of `BaseSmartFilter` / `BasePerformantFilter` and the swagger / public docs no longer advertise it. Multi-value uses `|` (OR) only. Consumers using `,` for intersection semantics should migrate to multiple distinct query parameters (e.g. `?naics=541511&fiscal_year=2024` rather than trying to AND values inside a single param). The swagger description-builder (`make_description`) now raises `ValueError` if a future internal call site passes `"conjunctive": True`, so the option cannot be reintroduced silently. Public docs (`docs/guides/patterns/agency-search.md`, `docs/webhooks-user-guide.md`, `docs/index.md`, forecasts API user guide) rewritten to drop OR-vs-AND framing in favor of OR-only language. (issue #2214) ### Fixed - **Multi-value `?agency=A|B` returned zero results.** Pipe-separated values on `agency` / `awarding_agency` / `funding_agency` now correctly return the union of both subtrees (`?awarding_agency=HHS|DOD` returns rows from either) on every endpoint. Single-value queries are unchanged. (issue #2210, also reported externally as `makegov/tango-public#51`) - **Numeric Federal Hierarchy keys (`fh_key`) now resolve to the canonical agency.** Previously, passing an L2 `fh_key` (e.g. NIH's `100019747`) could resolve to a deep descendant office (an L3 within NIH whose name happened to contain "AGENCY") instead of NIH itself. The agency now picks the canonical match and the subtree expansion gives the full agency's records. Same behavior change applies to numeric CGAC-style codes when the leading zero is stripped (`?agency=89` now resolves to DOE rather than a sub-office under DOE). - **Long pipe-separated agency queries no longer return HTTP 400 on award endpoints.** `?awarding_agency=DOD|HHS|VA|DHS|DOE|TREAS|USDA|DOJ|DOT|GSA` (and similar 10-token OR queries) now return HTTP 200 with the union of every named department's awards on `/api/contracts/`, `/api/idvs/`, and other award endpoints. Empty / pipe-only inputs (`|||`) and all-unresolvable inputs (`FAKE1|FAKE2|FAKE3`) likewise return HTTP 200 with an empty result set rather than 400. A single typo'd agency name still returns 400 (e.g. `?awarding_agency=DEPRTMENTOFENERGY`). - **Single-word agency abbreviations no longer accidentally match an unrelated office.** Some L3+ offices in the Federal Hierarchy data have a `name` literally equal to a department abbreviation (e.g. an L3 office named `"HHS"`); previously, querying `?agency=HHS` could match that office instead of the canonical L1 HHS department, returning a narrow result set. Abbreviations now consistently resolve to the canonical agency. Multi-word canonical names like `?agency=ENERGY, DEPARTMENT OF` are unchanged. - **`?agency=A|B` on `/api/forecasts/`, `/api/grants/`, `/api/protests/` no longer over-matches via partial-text fallback.** Where a token resolves cleanly to an agency, only that agency's subtree is matched. The previous behavior fell back to a partial-text match on the legacy text column when paired with multi-value input, which over-matched compound codes (e.g. `?agency=HHS|...` on grants matched every grant with `"HHS-..."` in its `agency_code` β€” 1500+ instead of 40). Unresolvable tokens still fall back to the legacy text column as before. ## [4.3.0] - 2026-05-07 ### Added - **Vehicle list filtering (`/api/vehicles/`).** New query parameters cover enum / code fields (`vehicle_type`, `type_of_idc`, `contract_type`, `set_aside`, `who_can_use`), reference codes (`naics_code`, `psc_code`, `program_acronym`), org hierarchy (`agency`, `organization_id`), numeric ranges (`total_obligated_min/max`, `idv_count_min/max`, `order_count_min/max`), and dates (`fiscal_year`, `award_date_after/before`, `last_date_to_order_after/before`). `vehicle_type`, `type_of_idc`, and `contract_type` accept pipe-separated multi-value selections via the `OR` smart-filter grammar (e.g. `?vehicle_type=A|B|C`). The `?ordering=` whitelist is expanded with `total_obligated`, `award_date`, `last_date_to_order`, `fiscal_year`, `idv_count`, `order_count`, `awardee_count`, and `vehicle_contracts_value` alongside the existing `vehicle_obligations` and `latest_award_date`. Examples: `GET /api/vehicles/?vehicle_type=A`, `GET /api/vehicles/?vehicle_type=A|B`, `GET /api/vehicles/?naics_code=541512&total_obligated_min=1000000`, `GET /api/vehicles/?ordering=-total_obligated`. (issue #2202) - **Awardee search (`/api/vehicles/{uuid}/awardees/?search=`).** Filter the awardees response by entity-aware full-text search across IDV fields (PIID, key, solicitation identifier, NAICS, PSC) and the recipient entity (legal name, address, etc.). Examples: `GET /api/vehicles/{uuid}/awardees/?search=ACCENTURE`, `GET /api/vehicles/{uuid}/awardees/?search=GS-35F-0119Y`. The response count reflects filtered results. (issue #2202) - **`/api/forecasts/`: new `organization` shape expand.** Each forecast row is now linked to a canonical `agencies.Organization` resolved deterministically from the existing `agency` text field (12 distinct production acronyms β€” `HHS`, `DHS`, `DOI`, `GSA`, `DOE`, `DOT`, `VA`, `DOL`, `NRC`, `NSF`, `COMMERCE`, `TREASURY`). Use `?shape=organization(*)` for the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). The `organization` expand is also in the default response shape (no `?shape=` needed). The legacy `agency` text field and filter are unchanged. - **`/api/grants/`: new `organization` shape expand.** Each grant opportunity is now linked to a canonical `agencies.Organization` resolved from the free-text `agency_code` field β€” the resolver walks compound codes like `HHS-NIH11` / `HHS-FDA` / `HHS-CDC-GHC` / `DOS-ECA` / `USDOJ-OJP-BJA` segment-wise to the most-specific aliased sub-agency (NIH, FDA, CDC, the State Dept bureau, BJA, etc.) rather than collapsing to the parent department. Codes whose only recognizable token is the dept prefix (`DOS-MEX` country codes, etc.) resolve to the L1 department. `?shape=organization(*)` returns the canonical 7-key office payload; `organization` is in the default response shape. The legacy `agency` text field and filter are unchanged. - **`/api/itdashboard/`: new `organization` shape expand** (free tier β€” same gating as `agency_name`). Each IT Dashboard investment is now linked to a canonical `agencies.Organization`, resolved deterministically from `(agency_code, bureau_code)` (preferred) and `(agency_name, bureau_name)` (fallback). `?shape=organization(*)` returns the canonical 7-key office payload. A small minority of investments (e.g., U.S. Army Corps of Engineers) currently resolve to `null` due to gaps in the canonical org data β€” tracked in #2176. - **`/api/protests/`: new `organization` shape expand** (free tier β€” same gating as the existing `agency` text field). Each protest case is now linked to a canonical `agencies.Organization` resolved deterministically from the free-text `agency` field β€” handles hierarchical names (`Department of the Army : NAVSEA : Surface Warfare`), DoD branches (Army / Navy / Air Force resolve to their AGENCY-typed orgs under DoD, not to DoD itself), and synthetic GAO buckets (`Independent Government Entities` / `Legislative Agencies` skip the dept lookup). `?shape=organization(*)` returns the canonical 7-key office payload. The deterministic FK is the canonical "what agency is this protest against?" signal β€” distinct from (and complementary to) the existing Bayesian `?shape=resolved_agency(*)` expand which returns a best-guess match with confidence and rationale. Both signals can be requested in the same call. ### Changed - **`organization` is now in the default response shape** for `/api/forecasts/`, `/api/grants/`, `/api/itdashboard/`, and `/api/protests/`. Previously opt-in via `?shape=organization(*)`; now always present. Renders as the canonical 7-key office payload β€” same shape as `awards`, `opportunities`, and `vehicles`. Drop `organization` from your `?shape=` parameter if you don't want it. - **`/api/opportunities/` `office` payload now includes `organization_id`** (was 6 keys, now 7). Additive change β€” same UUID is resolvable as before, just no longer requires a separate query to round-trip from the office to the underlying Organization. Other six keys (`office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`) unchanged. - **Bare `?shape=` syntax now works on every dataset that has the expand registered** with `relation="select"` or `"prefetch"`. Previously rejected with a 400 `unknown_field` error on most endpoints β€” `?shape=organization` returns 200 on forecasts / grants / itdashboard / protests / vehicles / opportunities. The parens form (`organization(*)`) was always working and is unchanged. ## [4.2.2] - 2026-05-05 ### Fixed - **`?shape=opportunity(...)` on `/api/vehicles/` now returns the full Opportunity shape instead of a 400.** The v4.2.1 implementation shipped a 4-field stub that only allowed `opportunity_id`, `solicitation_title`, `solicitation_description`, and `solicitation_date`. Any consumer requesting a field the pre-cutover `vehicle.opportunity` FK exposed β€” `title`, `sam_url`, `first_notice_date`, `office(...)`, or any other Opportunity field β€” received a 400 from shape validation. The fix resolves the full `Opportunity` by `solicitation.opportunity_id` and routes through the complete Opportunity shape so every field and nested expand (including `office(office_code,office_name,agency_code,agency_name,department_code,department_name)` and `set_aside(code,description)`) works as it did pre-cutover. Available on both list and retrieve; opt-in via `?shape=opportunity(...)` (not in the default response shape). On list pages, all Opportunity rows for the page are fetched in a single batched query, so `opportunity(...)` is safe to request alongside other shapes. Closes #2193. - **`solicitation_identifier` no longer leaks the internal `ACRO:` storage prefix on synthetic GWAC vehicles.** Previously, certain GWAC vehicles returned values like `"solicitation_identifier": "ACRO:SEWP"`. The `ACRO:` prefix is an internal storage detail (collision avoidance with real solicitation numbers in the unique index); the API response now strips it, so SEWP-family vehicles surface as `"SEWP"`, `"SEWP IV"`, `"SEWP V"`, etc. Use `is_synthetic_solicitation` (boolean) and `program_acronym` (string) to identify GWAC-recovery vehicles. Refs #2193. ### Changed - **`Deprecation: true` HTTP header removed from `/api/vehicles/`.** v4.2.1 added an unconditional `Deprecation: true` header on every list and retrieve response, advertising deprecation of `agency_details`, `competition_details`, and `?shape=opportunity(...)`. We're walking it back: there are no committed first-class replacements for `agency_details.funding_office` or for unique `competition_details` keys (`extent_competed`, `set_aside`, `solicitation_procedures`, `number_of_offers_received`), no sunset date, and `?shape=opportunity(...)` is now restored to full pre-cutover parity. The fields continue to work; tooling that was watching for the header should expect it to be absent until we publish a real migration plan. ### Breaking - **`?shape=opportunity(solicitation_title)` / `opportunity(solicitation_description)` / `opportunity(solicitation_date)` no longer validate.** These three fields are top-level Vehicle fields, not Opportunity model fields β€” the v4.2.1 stub erroneously accepted them inside `opportunity(...)`. Use `?shape=solicitation_title,solicitation_description,solicitation_date` (top-level, no nesting) instead β€” these come back in the default list shape and are cheaper than the full `opportunity(...)` expand. `opportunity(opportunity_id)` continues to work β€” `opportunity_id` is also an Opportunity model field, AND it's available as a top-level Vehicle field. SDK consumers (`tango-python`, `tango-node`) verified clean. If you adopted the v4.2.1 stub shape between #2177 and #2193 landing, move the three companion fields to top-level. ## [4.2.1] - 2026-05-03 ### Added - `/api/vehicles/` responses now include `is_synthetic_solicitation` (boolean). True for a small set of GWAC vehicles where the underlying IDVs lacked a real solicitation identifier but had a recognizable `program_acronym` (`8ASTARS`, `SEWP IV`, `COMMITS NEXGEN`, etc.) β€” the API keys the vehicle off the program acronym so these GWACs surface in results instead of being dropped. SAM enrichment (`solicitation_title`/`description`/`date`/`opportunity_id`) is always null on synthetic rows. Use this flag to distinguish them in your own filtering or display logic. - `/api/vehicles/` responses now include three new top-level fields on both list and retrieve: `program_acronym` (the vehicle's program acronym, e.g. `"OASIS+"`, when present), `idv_count` (number of IDVs in the vehicle), `total_obligated` (sum of obligations across the vehicle's IDVs). Retrieve responses also include a nested `metrics` object with 12 new metrics: `competed_rate`, `award_concentration_hhi`, `order_concentration_hhi`, `top_recipient_share`, `avg_offers_received`, `avg_order_value`, `max_order_value`, `using_agency_count`, `recent_obligations_24mo`, `recent_orders_24mo`, `days_since_last_order`, `obligation_to_ceiling_ratio`. Request the bag via `?shape=metrics(*)` or specific keys via `?shape=metrics(competed_rate,top_recipient_share)`. - **`organization` field on `/api/vehicles/` list and retrieve responses** β€” the awarding Organization expanded to the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). The same payload now also populates `agency_details.awarding_office` on both list and detail responses (was previously null on list and sometimes null on detail when per-IDV office signals were missing). Cached for 1 year per Organization. - **`description` (string) and `descriptions` (array)** on `/api/vehicles/` are populated again. Both had been returning null since v4.2.0; that's now fixed. The legacy compose-a-single-string behavior (`description` returns the longest common substring across `descriptions`) is unchanged. ### Changed - **Response keys are now alphabetized** at every nesting level on `/api/vehicles/` list and detail. Leaves and nested expand objects interleave by key name. The order is stable and independent of the order keys appear in your `?shape=` parameter β€” `?shape=uuid,organization` and `?shape=organization,uuid` produce the same JSON. Affects every shape-using endpoint (vehicles, contracts, opportunities, entities, etc.) β€” if you've been relying on response-key order, switch to explicit key access. The OpenAPI schema (Swagger UI) and SDK type definitions are unchanged. ### Changed (internal data path; API surface preserved) - `/api/vehicles/{uuid}/` `agency_details` and `competition_details` JSON blobs and the `?shape=opportunity(...)` expand are now recomputed at request time (from the vehicle's IDVs and the `awards_vehicle_solicitation` companion respectively) instead of being stored columns. **No deprecation announced**: see the #2193 / 4.2.2 entry for the walk-back. The fields keep working. List responses include `agency_details.awarding_office` populated from the same source as the top-level `organization` field β€” `agency_details.funding_office` is null at the vehicle grain (see below). - **Top-level `organization_id`** on `/api/vehicles/` retrieve responses is dropped from the default shape β€” it's redundant with `organization.organization_id` (the same UUID, nested inside the office payload). Still requestable explicitly via `?shape=organization_id`, but the default response no longer surfaces it. - **Funding-side organization signal removed from vehicles.** `agency_details.funding_office` is null at the vehicle grain. Vehicles are not the right grain for funding-org analysis: a single vehicle is funded by many agencies via task orders, and task-order data already carries funding-side detail. Consumers needing funding-org rollups should query `/api/vehicles//orders/` and aggregate from there. ## [4.2.0] - 2026-04-30 ### Added - G2X integration (#1881): new `/api/news/` and `/api/events/` endpoints (G2X User group required), a `/api/company/rag/` endpoint for unified company/people/news lookups, and `g2x_about` / `g2x_ai_summary` / `g2x_employee_count` fields available via `?shape=` on `/api/entities/` when a linked G2X profile exists - eBuy opportunities now available on `/api/opportunities/` via `?domain=ebuy` (eBuy only) or `?domain=sam,ebuy` (union with SAM). eBuy results are served live from the G2X GraphQL API β€” no stored snapshot; filter by `request_type`, `contract_type`, `set_aside_type`, `buyer_department`, `closes_after`, or `search`. On upstream outage, `?domain=sam,ebuy` degrades to SAM-only with an `upstream_warnings` field so SAM queries stay up - `vehicle` is now available as a shape expand on `/api/contracts/`. Use `?shape=vehicle(uuid,solicitation_title)` to attach the contract's parent vehicle to each result, or `?shape=vehicle(*)` for the curated field set (`uuid`, `solicitation_identifier`, `solicitation_title`, `solicitation_description`, `agency_id`, `vehicle_type`, `type_of_idc`, `contract_type`, `who_can_use`, `solicitation_date`, `award_date`, `last_date_to_order`, `fiscal_year`, `naics_code`, `psc_code`, `set_aside`, `description`). Contracts without a parent IDV β€” or whose parent IDV is not part of any vehicle β€” return `null`. For richer vehicle detail (awardees, opportunity, totals), follow the returned `uuid` to `/api/vehicles/{uuid}/`. Resolution adds one query per page, not per row. ## [4.1.1] - 2026-04-27 ### Added - `cage` is now an alias for `cage_code` across the API. Query entities with `?cage=` or `?cage_code=` (sending both is rejected β€” pick one). Award `recipient` shapes accept either key: `recipient(cage)` returns `cage`, `recipient(cage_code)` returns `cage_code`, and `recipient(*)` returns `cage_code` only. If you want the short `cage` key, ask for it explicitly (refs #1350). ### Fixed - Filtering subawards by `?awarding_agency=` or `?funding_agency=` now uses the same hierarchical resolution as the contracts and opportunities endpoints. Department queries (e.g. `?awarding_agency=DOE`, `?awarding_agency=089`) return all subawards under that department's subtree; agency codes (e.g. `?awarding_agency=8900` for DOE, `?awarding_agency=7530` for CMS) return that agency's subtree; abbreviations (e.g. `?awarding_agency=CMS`) resolve via the canonical alias table. Result counts will shift compared to the previous literal-code-match behavior β€” most notably, name-based queries that previously returned 0 (e.g. `?awarding_agency=CMS`) now return the full agency subtree, semantically aligned with `/api/contracts/?awarding_agency=...`. Closes #2076. ## [4.1.0] - 2026-04-26 ### Internal / Infra - Internal ETL pipeline rewrite for awards data freshness. No API surface or query-behavior changes (refs #2082). ## [4.0.14] - 2026-04-26 ### Changed - Latency spikes on `/metrics/` endpoints during scheduled refreshes should be noticeably smaller after an internal pipeline rewrite. API surface is unchanged β€” the same `/metrics/` endpoints with `?group_by=agency` / `?group_by=department` parameters continue to work. - Filtering opportunities or notices by `?agency=` now uses the same hierarchical resolution as the contracts agency filter. Department queries (e.g. `?agency=DOE`, `?agency=089`) return the whole department subtree; agency codes (e.g. `?agency=8900` for DOE, `?agency=8960` for FERC) return just that agency's subtree. Result counts will shift compared to the previous full-text-search behavior β€” the new counts are semantically correct subtree matches rather than token co-occurrence. Closes #2058. ### Fixed - Forecasts loader: reduced log noise and false Sentry alerts. `sanitize_year` data-quality events are now DEBUG-level; empty records is a no-op rather than an error; partial validation failures log as warnings (visible in admin, no Sentry alert). Closes #1974, closes #1935. - Filtering contracts by a department's full legal name (e.g. `?awarding_agency=ENERGY, DEPARTMENT OF`) now correctly returns the whole department's contracts instead of 0 results. The embedded comma in federal inverted names was being misinterpreted as a target/context separator. Queries for `?awarding_agency=DOE` and the numeric CGAC/FPDS codes are unchanged. Closes #2079. - Filtering contracts by `awarding_agency` or `funding_agency` using a real (but currently inactive) agency code such as `5706`, `8933`, or `8944` now returns an HTTP 200 response with the matching contracts, instead of an HTTP 400 "No agency found matching" error. Queries for agency codes that don't exist at all continue to return 400 as before. Closes #2057. - Filtering contracts by a numeric agency code (e.g. `awarding_agency=8900`, `funding_agency=8900`) now returns the correct subtree of contracts instead of narrowing to a single sub-office. A 4-digit FPDS code resolves to that agency and its descendants; a 3-digit CGAC code resolves to the whole department (matching what `awarding_agency=DOE` returns). Name queries are unchanged. Closes #2056. - Filtering opportunities or notices by a numeric agency code (e.g. `?agency=8900`) now resolves to the correct subtree instead of matching agencies whose search index happens to contain that token. Fixes over-broad matches for short numeric queries and makes sibling-agency queries (like DOE `8900` vs FERC `8960` under the same department) correctly distinct. Closes #2058. ## [4.0.12] - 2026-04-22 ### Added - The `/welcome/` page now displays your active API key(s) with copy-to-clipboard and visibility toggle β€” no longer need to navigate to your profile to find your key after signing up ### Changed - The welcome page's API keys card now matches the richer layout used on your profile: full-width card at the top of the page with your daily requests remaining, per-key name + "Active" badge, click-to-copy, show/hide, and created date + rate limits. "Your plan" and "Quick links" now sit side-by-side below it so nothing important is hidden below the fold ## [4.0.11] - 2026-04-21 - No user-facing changes ## [4.0.10] - 2026-04-21 - No user-facing changes ## [4.0.9] - 2026-04-20 - No user-facing changes ## [4.0.8] - 2026-04-20 - No user-facing changes ## [4.0.7] - 2026-04-18 - No user-facing changes ## [4.0.6] - 2026-04-17 - No user-facing changes --- --- description: "Filtering, ordering, and pagination for the deprecated /api/agencies/ endpoint; new integrations should use Organizations instead." updated: 2026-05-13 --- # Agencies !!! warning "Deprecated endpoint" This endpoint is deprecated. Use [Organizations](organizations.md) for the unified federal hierarchy. This endpoint will be removed in a future version. !!! warning "Deprecated scoped contract endpoints" The `/api/agencies/{code}/contracts/awarding/` and `/api/agencies/{code}/contracts/funding/` endpoints are deprecated. Use [`/api/contracts/?awarding_agency={code}`](contracts.md) or [`/api/contracts/?funding_agency={code}`](contracts.md) instead. Agencies are federal organizations exposed at `/api/agencies/` (with a small amount of structure via `department`). If you need the unified Federal Hierarchy model (departments/agencies/offices all as one tree), see [Organizations](organizations.md). For field definitions, see the [Organizations Data Dictionary](../data-dictionary/organizations.md). ## Endpoints - `GET /api/agencies/` (list) - `GET /api/agencies/{code}/` (detail) Agency-scoped contract lists (these behave like `/api/contracts/`, but scoped by agency code): - `GET /api/agencies/{code}/contracts/awarding/` - `GET /api/agencies/{code}/contracts/funding/` ## Filtering | Param | What it does | | --- | --- | | `search` | Full-text search over agencies (best-effort, vector-backed). | ## Ordering `/api/agencies/` does **not** support `ordering=...`. ## Pagination Agencies use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `code`, `name`, `abbreviation` - Expansions: - `department(code,name,abbreviation,description,cgac,website,congressional_justification)` Default shape (no `?shape=` param): `code,name,abbreviation,department(name,code)` ```bash # Just codes and names /api/agencies/?shape=code,name # Include department info /api/agencies/4700/?shape=code,name,department(name,code) # All department fields /api/agencies/4700/?shape=code,name,department(*) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). ### List agencies === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_agencies(limit=25) for a in resp.results: print(a.code, a.name) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listAgencies({ limit: 25 }); for (const a of resp.results) { console.log(a.code, a.name); } ``` ### Awarding/funding contracts for an agency The SDKs don’t yet expose a first-class method for these scoped endpoints. Use the contracts endpoint with awarding/funding agency filters, or call the scoped path directly. === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/agencies/4700/contracts/awarding/", params={"limit": 10, "shape": ShapeConfig.CONTRACTS_MINIMAL}, ) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts import { ShapeConfig, 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/agencies/4700/contracts/awarding/", { limit: 10, shape: ShapeConfig.CONTRACTS_MINIMAL, }); console.log("count:", data.count); ``` --- --- description: "Filtering, search, ordering, shaping and pagination for /api/assistance/direct_payments/, Tango's endpoint for direct payments for a specified use or with unrestricted use from USAspending." tags: [assistance, payments, awards, api, reference] updated: 2026-10-27 --- # Direct payments Federal financial-assistance awards of direct payments for a specified use or with unrestricted use are exposed at `/api/assistance/direct_payments/`. For field definitions, see the [Direct payments Data Dictionary](../data-dictionary/assistance-direct-payments.md). For how assistance awards, transactions, listings and recipients fit together, see the [Financial assistance overview](assistance.md). The other assistance endpoints, which take the same filters and shapes: [Grant awards](assistance-grants.md) Β· [Loans](assistance-loans.md) Β· [Other assistance](assistance-other.md). The endpoint holds every award whose GSDM assistance type is one of: | Code | Assistance type | | --- | --- | | `F006` | Direct Payment for Specified Use | | `F007` | Direct Payment with Unrestricted Use | Roughly seven in ten records on this endpoint have no recipient, because so many direct payments go to individual people. Agencies report small payments in bulk as **aggregate records** (record type `1`), one per county, state or country, which carry a `uri` instead of a `fain`. A payment to a named individual is a **PII-redacted record** (record type `3`). Both have `recipient: null`; their amounts, program, agency and place of performance are still there. Add `record_type=2` to keep only payments to an identified recipient, and filter aggregate records by `uri`. ## Endpoints - `GET /api/assistance/direct_payments/` (list, with filtering, search and ordering) - `GET /api/assistance/direct_payments/{key}/` (detail) - `GET /api/assistance/direct_payments/{key}/transactions/` (the award's transactions, latest first) - `GET /api/assistance/direct_payments/{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`: ```text cfda_number=93.778|93.767 ``` ### Award identifiers | Param | What it does | | --- | --- | | `key` | Award key (exact). OR via `|`. | | `fain` | Federal Award Identification Number (exact). OR via `|`. | | `uri` | Unique Record Identifier, carried by aggregate records (exact). OR via `|`. | | `funding_opportunity_number` | The funding opportunity number the award was made under, as on the Grants.gov opportunity (exact). OR via `|`. | ### Recipients | Param | What it does | | --- | --- | | `uei` | Recipient UEI (exact). OR via `|`. | | `recipient` | Recipient name or UEI. Each term matches the 100 recipients closest to it by name similarity, among recipients whose `legal_business_name` contains it (case-insensitive) and who have an award on this endpoint: 10 for a term under four characters or a bare business suffix such as `inc` or `llc`. A UEI-shaped term matches the recipient with that UEI. A term under three characters returns **400**. Works for every recipient, with or without a UEI. OR via `|` only; the word `OR` is not a separator here. | A broad `recipient` term covers only its closest names, not every recipient whose name contains it. To pin one recipient, filter on `uei`. ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Awarding agency (code, name or abbreviation; best-effort matching). OR via `|`. See [Agency search](../guides/patterns/agency-search.md). | | `funding_agency` | Funding agency or department, with the same matching as `awarding_agency`. OR via `|`. | ### Programs and types | Param | What it does | | --- | --- | | `cfda_number` | The award's **primary** assistance listing (CFDA) number, e.g. `93.778`. OR via `|`. An award funded under several programs matches only on its primary one; its other programs are in [`listings`](#endpoints). | | `assistance_type` | GSDM assistance type code (`F001`–`F010`), case-insensitive. OR via `|`. This endpoint holds only `F006`, `F007`, so another code matches nothing. | | `record_type` | `1` (aggregate), `2` (non-aggregate) or `3` (non-aggregate to an individual, PII-redacted). OR via `|`. An unknown code matches nothing. | | `business_funds_indicator` | `NON` (not Recovery Act) or `REC` (Recovery Act), case-insensitive. OR via `|`. | | `disaster_emergency_fund_code` | Disaster Emergency Fund Code (DEFC), e.g. `L`, case-insensitive. Matches the code as a whole within the award's list, so `L` doesn't match inside another code. OR via `|`. | ### Dates and fiscal years All date filters require `YYYY-MM-DD`. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Federal fiscal year of the award (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance **current end** date range. | ### Place of performance | Param | What it does | | --- | --- | | `pop_state` | State code, e.g. `VA` (case-insensitive). OR via `|`. | | `pop_country` | Country code, ISO 3166 alpha-3, e.g. `USA` (case-insensitive). OR via `|`. | | `pop_zip` | Five-digit ZIP code (exact). OR via `|`. | ### Dollars | Param | What it does | | --- | --- | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | 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](../data-dictionary/assistance-direct-payments.md#money). ## 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: | Input | Matches | | --- | --- | | `flood mitigation` | Awards matching every word. | | `broadband or fiber` | Awards matching either word. | | `housing -veterans` | Awards matching `housing` but not `veterans`. | | `"rural health"` | Awards matching **both** words, anywhere. A quoted phrase is not matched as adjacent words on these endpoints. | 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/direct_payments/?ordering=-award_date` - Largest first, comparable across endpoints: `GET /api/assistance/direct_payments/?ordering=-pragmatic_obligations` ## Pagination and counts The four list endpoints use **cursor-based (keyset) pagination**, like the other award endpoints (see [Contracts pagination](contracts.md#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](../guides/patterns/result-counts.md). The sub-routes use page-number pagination (`page`, `limit`): | Sub-route | Default `limit` | Max `limit` | | --- | --- | --- | | `/transactions/` | 100 | 500 | | `/listings/` | 10 | 100 | ## Response shaping These endpoints support [response shaping](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) via `?shape=`. Default shape (list and detail, no `?shape=` param): ```text 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:** | Expansion | Fields | | --- | --- | | `recipient(...)` | `uuid`, `uei`, `duns`, `legal_business_name`, `legal_business_name_raw`, `county`, `congressional_district`, `congressional_district_original`, `highest_owner`, `business_types` | | `recipient_address(...)` | `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `county_fips`, `state_fips`, `foreign_city_name`, `foreign_province_name`, `foreign_postal_code`, `congressional_district_original`, `congressional_district_current` | | `place_of_performance(...)` | `country`, `state_code`, `state_name`, `state_fips`, `county_fips`, `county_name`, `city_name`, `zip_code`, `zip_plus_four`, `code`, `scope`, `foreign_location` | | `awarding_office(...)`, `funding_office(...)` | `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `assistance_listing(...)` | `number`, `title` (from the [assistance listings](assistance-listings.md) catalog) | | `assistance_type(...)` | `code`, `description` | | `period_of_performance(...)` | `start_date`, `current_end_date` | | `officers(...)` | `highly_compensated_officer_1_name`, `highly_compensated_officer_1_amount`, … through `highly_compensated_officer_5_amount` | | `obligations_by_fiscal_year(...)` | `fiscal_year`, `obligated` | | `listings(...)` | `cfda_number`, `is_primary`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `transactions_count`, `first_action_date`, `last_action_date` | | `transactions(...)` | `key`, `modification_number`, `transaction_date`, `action_type`, `assistance_type_code`, `correction_delete_indicator`, `cfda_number`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `award_amount_basis`, `award_recipient_basis`, `action_date_fiscal_year`, `last_modified_date`, `initial_report_date` | A few behaviors worth knowing: - **`recipient` is a shared recipient record, shaped like an [entity](entities.md).** 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](../data-dictionary/assistance-direct-payments.md#business-types)). - **`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](#endpoints) pages through them instead. ## Access These endpoints are available on every plan, and no field on them is tier-gated (see [Plans & Data Access](../getting-started/pricing.md)). Call them with an API key or OAuth token (see [Authentication](../getting-started/authentication.md)), under the same [rate limits](../guides/patterns/rate-limits.md) as the other award endpoints. They aren't alertable: no [webhook alert](../webhooks/index.md) covers financial-assistance awards. ## Examples ```bash # Direct payments funded by a department, with the recipient's address curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/direct_payments/?funding_agency=USDA&shape=key,award_date,obligated,recipient(legal_business_name,uei),recipient_address(city,state_or_province_code)" # Only payments to an identified recipient, largest first curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/direct_payments/?record_type=2&ordering=-obligated&limit=10" # Aggregate records in one state, fiscal year 2024 curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/direct_payments/?record_type=1&pop_state=TX&fiscal_year=2024&shape=key,uri,obligated,cfda_number,place_of_performance(county_name)" # COVID-19 (DEFC L) payments curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/direct_payments/?disaster_emergency_fund_code=L&shape=key,obligated,covid19_obligated" ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose first-class methods for these endpoints. You can call them through the SDK's internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/assistance/direct_payments/", params={"record_type": "2", "ordering": "-obligated", "limit": 25}, ) for award in data["results"]: print(award["key"], award["award_date"], award["obligated"]) ``` === "Node (tango-node)" ```ts 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/direct_payments/", { record_type: "2", ordering: "-obligated", limit: 25, }); for (const award of data.results) { console.log(award.key, award.award_date, award.obligated); } ``` --- --- description: "Filtering, search, ordering, shaping and pagination for /api/assistance/grants/, Tango's endpoint for grant and cooperative-agreement awards from USAspending." tags: [assistance, grants, awards, api, reference] updated: 2026-10-27 --- # Grant awards Federal financial-assistance awards of grant and cooperative-agreement awards are exposed at `/api/assistance/grants/`. For field definitions, see the [Grant awards Data Dictionary](../data-dictionary/assistance-grants.md). For how assistance awards, transactions, listings and recipients fit together, see the [Financial assistance overview](assistance.md). The other assistance endpoints, which take the same filters and shapes: [Loans](assistance-loans.md) Β· [Direct payments](assistance-direct-payments.md) Β· [Other assistance](assistance-other.md). The endpoint holds every award whose GSDM assistance type is one of: | Code | Assistance type | | --- | --- | | `F001` | Grant | | `F002` | Cooperative Agreement | !!! note "Not the same as `/api/grants/`" [`/api/grants/`](grants.md) serves **grant opportunities** from Grants.gov: funding announcements you can apply for. `/api/assistance/grants/` serves **grant awards**: money an agency has already obligated to a recipient. An award's `funding_opportunity_number` names the opportunity it was made under, when the agency reported one, and the `funding_opportunity_number` filter finds the awards made under an opportunity. On a grant, `obligated` (and `pragmatic_obligations`, which equals it here) is the money out the door. `non_federal_funding_amount` is the recipient's cost share and `indirect_cost_federal_share_amount` the federal share of indirect costs. ## Endpoints - `GET /api/assistance/grants/` (list, with filtering, search and ordering) - `GET /api/assistance/grants/{key}/` (detail) - `GET /api/assistance/grants/{key}/transactions/` (the award's transactions, latest first) - `GET /api/assistance/grants/{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`: ```text cfda_number=93.778|93.767 ``` ### Award identifiers | Param | What it does | | --- | --- | | `key` | Award key (exact). OR via `|`. | | `fain` | Federal Award Identification Number (exact). OR via `|`. | | `uri` | Unique Record Identifier, carried by aggregate records (exact). OR via `|`. | | `funding_opportunity_number` | The funding opportunity number the award was made under, as on the Grants.gov opportunity (exact). OR via `|`. | ### Recipients | Param | What it does | | --- | --- | | `uei` | Recipient UEI (exact). OR via `|`. | | `recipient` | Recipient name or UEI. Each term matches the 100 recipients closest to it by name similarity, among recipients whose `legal_business_name` contains it (case-insensitive) and who have an award on this endpoint: 10 for a term under four characters or a bare business suffix such as `inc` or `llc`. A UEI-shaped term matches the recipient with that UEI. A term under three characters returns **400**. Works for every recipient, with or without a UEI. OR via `|` only; the word `OR` is not a separator here. | A broad `recipient` term covers only its closest names, not every recipient whose name contains it. To pin one recipient, filter on `uei`. ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Awarding agency (code, name or abbreviation; best-effort matching). OR via `|`. See [Agency search](../guides/patterns/agency-search.md). | | `funding_agency` | Funding agency or department, with the same matching as `awarding_agency`. OR via `|`. | ### Programs and types | Param | What it does | | --- | --- | | `cfda_number` | The award's **primary** assistance listing (CFDA) number, e.g. `93.778`. OR via `|`. An award funded under several programs matches only on its primary one; its other programs are in [`listings`](#endpoints). | | `assistance_type` | GSDM assistance type code (`F001`–`F010`), case-insensitive. OR via `|`. This endpoint holds only `F001`, `F002`, so another code matches nothing. | | `record_type` | `1` (aggregate), `2` (non-aggregate) or `3` (non-aggregate to an individual, PII-redacted). OR via `|`. An unknown code matches nothing. | | `business_funds_indicator` | `NON` (not Recovery Act) or `REC` (Recovery Act), case-insensitive. OR via `|`. | | `disaster_emergency_fund_code` | Disaster Emergency Fund Code (DEFC), e.g. `L`, case-insensitive. Matches the code as a whole within the award's list, so `L` doesn't match inside another code. OR via `|`. | ### Dates and fiscal years All date filters require `YYYY-MM-DD`. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Federal fiscal year of the award (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance **current end** date range. | ### Place of performance | Param | What it does | | --- | --- | | `pop_state` | State code, e.g. `VA` (case-insensitive). OR via `|`. | | `pop_country` | Country code, ISO 3166 alpha-3, e.g. `USA` (case-insensitive). OR via `|`. | | `pop_zip` | Five-digit ZIP code (exact). OR via `|`. | ### Dollars | Param | What it does | | --- | --- | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | 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](../data-dictionary/assistance-grants.md#money). ## 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: | Input | Matches | | --- | --- | | `flood mitigation` | Awards matching every word. | | `broadband or fiber` | Awards matching either word. | | `housing -veterans` | Awards matching `housing` but not `veterans`. | | `"rural health"` | Awards matching **both** words, anywhere. A quoted phrase is not matched as adjacent words on these endpoints. | 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/grants/?ordering=-award_date` - Largest first, comparable across endpoints: `GET /api/assistance/grants/?ordering=-pragmatic_obligations` ## Pagination and counts The four list endpoints use **cursor-based (keyset) pagination**, like the other award endpoints (see [Contracts pagination](contracts.md#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](../guides/patterns/result-counts.md). The sub-routes use page-number pagination (`page`, `limit`): | Sub-route | Default `limit` | Max `limit` | | --- | --- | --- | | `/transactions/` | 100 | 500 | | `/listings/` | 10 | 100 | ## Response shaping These endpoints support [response shaping](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) via `?shape=`. Default shape (list and detail, no `?shape=` param): ```text 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:** | Expansion | Fields | | --- | --- | | `recipient(...)` | `uuid`, `uei`, `duns`, `legal_business_name`, `legal_business_name_raw`, `county`, `congressional_district`, `congressional_district_original`, `highest_owner`, `business_types` | | `recipient_address(...)` | `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `county_fips`, `state_fips`, `foreign_city_name`, `foreign_province_name`, `foreign_postal_code`, `congressional_district_original`, `congressional_district_current` | | `place_of_performance(...)` | `country`, `state_code`, `state_name`, `state_fips`, `county_fips`, `county_name`, `city_name`, `zip_code`, `zip_plus_four`, `code`, `scope`, `foreign_location` | | `awarding_office(...)`, `funding_office(...)` | `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `assistance_listing(...)` | `number`, `title` (from the [assistance listings](assistance-listings.md) catalog) | | `assistance_type(...)` | `code`, `description` | | `period_of_performance(...)` | `start_date`, `current_end_date` | | `officers(...)` | `highly_compensated_officer_1_name`, `highly_compensated_officer_1_amount`, … through `highly_compensated_officer_5_amount` | | `obligations_by_fiscal_year(...)` | `fiscal_year`, `obligated` | | `listings(...)` | `cfda_number`, `is_primary`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `transactions_count`, `first_action_date`, `last_action_date` | | `transactions(...)` | `key`, `modification_number`, `transaction_date`, `action_type`, `assistance_type_code`, `correction_delete_indicator`, `cfda_number`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `award_amount_basis`, `award_recipient_basis`, `action_date_fiscal_year`, `last_modified_date`, `initial_report_date` | A few behaviors worth knowing: - **`recipient` is a shared recipient record, shaped like an [entity](entities.md).** 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](../data-dictionary/assistance-grants.md#business-types)). - **`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](#endpoints) pages through them instead. ## Access These endpoints are available on every plan, and no field on them is tier-gated (see [Plans & Data Access](../getting-started/pricing.md)). Call them with an API key or OAuth token (see [Authentication](../getting-started/authentication.md)), under the same [rate limits](../guides/patterns/rate-limits.md) as the other award endpoints. They aren't alertable: no [webhook alert](../webhooks/index.md) covers financial-assistance awards. ## Examples ```bash # The largest Medicaid grants curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/?cfda_number=93.778&ordering=-obligated&limit=10" # Awards made under one Grants.gov opportunity (Community Wildfire Defense Grants) curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/?funding_opportunity_number=USDA-FS-2024-CWDG-CWSF&shape=key,title,obligated,recipient(legal_business_name)" # Keyword search, newest first curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/?search=wildfire%20resilience&ordering=-award_date" # One award, with its per-program breakdown and per-year obligations curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/ASST_NON_2303OHAIPP_075/?shape=key,title,summary,obligated,listings(*),obligations_by_fiscal_year(*)" # Its transactions, 50 at a time curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/ASST_NON_2303OHAIPP_075/transactions/?limit=50" # Find an award by its FAIN curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/grants/?fain=2303OHAIPP&shape=key,fain,title" ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose first-class methods for these endpoints. You can call them through the SDK's internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/assistance/grants/", params={"cfda_number": "93.778", "ordering": "-award_date", "limit": 25}, ) for award in data["results"]: print(award["key"], award["award_date"], award["obligated"]) ``` === "Node (tango-node)" ```ts 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/grants/", { cfda_number: "93.778", ordering: "-award_date", limit: 25, }); for (const award of data.results) { console.log(award.key, award.award_date, award.obligated); } ``` --- --- description: "Filtering, ordering, and pagination for /api/assistance_listings/, the CFDA program reference endpoint." updated: 2026-05-13 --- # Assistance listings Assistance listings (CFDA) reference data is exposed at `/api/assistance_listings/`. This is the program catalog, not the awards: for financial-assistance awards and their per-program money, see [Financial assistance](assistance.md), whose `cfda_number` filter and `listings` expansion use these numbers. For field definitions, see the [Assistance Listings Data Dictionary](../data-dictionary/assistance-listings.md). ## Endpoints - `GET /api/assistance_listings/` (list) - `GET /api/assistance_listings/{number}/` (detail; `{number}` supports digits and `.`) ## Filtering None. ## Ordering `/api/assistance_listings/` does **not** support `ordering=...`. ## Pagination Assistance listings use standard page-number pagination: - `page` (default 1) - `limit` (default 1000, max 10000) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `number`, `title`, `published_date`, `archived_date`, `popular_name`, `objectives`, `applicant_eligibility`, `benefit_eligibility` - No expansions. Default shape (list, no `?shape=` param): `number,title` **Note:** Detail responses (`/api/assistance_listings/{number}/`) use the full serializer (includes all fields) when no `?shape=` param is provided. ```bash # Include extra fields /api/assistance_listings/?shape=number,title,objectives # Detail with specific fields /api/assistance_listings/10.001/?shape=number,title,objectives,popular_name ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don’t yet expose a first-class `list_assistance_listings()` / `listAssistanceListings()` method. You can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get("/api/assistance_listings/", params={"page": 1, "limit": 25}) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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_listings/", { page: 1, limit: 25 }); console.log("count:", data.count); ``` --- --- description: "Filtering, search, ordering, shaping and pagination for /api/assistance/loans/, Tango's endpoint for direct loans and loan guarantees from USAspending." tags: [assistance, loans, awards, api, reference] updated: 2026-10-27 --- # 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](../data-dictionary/assistance-loans.md). For how assistance awards, transactions, listings and recipients fit together, see the [Financial assistance overview](assistance.md). The other assistance endpoints, which take the same filters and shapes: [Grant awards](assistance-grants.md) Β· [Direct payments](assistance-direct-payments.md) Β· [Other assistance](assistance-other.md). The endpoint holds every award whose GSDM assistance type is one of: | Code | Assistance type | | --- | --- | | `F003` | Direct Loan | | `F004` | Loan Guarantee | 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`: ```text cfda_number=93.778|93.767 ``` ### Award identifiers | Param | What it does | | --- | --- | | `key` | Award key (exact). OR via `|`. | | `fain` | Federal Award Identification Number (exact). OR via `|`. | | `uri` | Unique Record Identifier, carried by aggregate records (exact). OR via `|`. | | `funding_opportunity_number` | The funding opportunity number the award was made under, as on the Grants.gov opportunity (exact). OR via `|`. | ### Recipients | Param | What it does | | --- | --- | | `uei` | Recipient UEI (exact). OR via `|`. | | `recipient` | Recipient name or UEI. Each term matches the 100 recipients closest to it by name similarity, among recipients whose `legal_business_name` contains it (case-insensitive) and who have an award on this endpoint: 10 for a term under four characters or a bare business suffix such as `inc` or `llc`. A UEI-shaped term matches the recipient with that UEI. A term under three characters returns **400**. Works for every recipient, with or without a UEI. OR via `|` only; the word `OR` is not a separator here. | A broad `recipient` term covers only its closest names, not every recipient whose name contains it. To pin one recipient, filter on `uei`. ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Awarding agency (code, name or abbreviation; best-effort matching). OR via `|`. See [Agency search](../guides/patterns/agency-search.md). | | `funding_agency` | Funding agency or department, with the same matching as `awarding_agency`. OR via `|`. | ### Programs and types | Param | What it does | | --- | --- | | `cfda_number` | The award's **primary** assistance listing (CFDA) number, e.g. `93.778`. OR via `|`. An award funded under several programs matches only on its primary one; its other programs are in [`listings`](#endpoints). | | `assistance_type` | GSDM assistance type code (`F001`–`F010`), case-insensitive. OR via `|`. This endpoint holds only `F003`, `F004`, so another code matches nothing. | | `record_type` | `1` (aggregate), `2` (non-aggregate) or `3` (non-aggregate to an individual, PII-redacted). OR via `|`. An unknown code matches nothing. | | `business_funds_indicator` | `NON` (not Recovery Act) or `REC` (Recovery Act), case-insensitive. OR via `|`. | | `disaster_emergency_fund_code` | Disaster Emergency Fund Code (DEFC), e.g. `L`, case-insensitive. Matches the code as a whole within the award's list, so `L` doesn't match inside another code. OR via `|`. | ### Dates and fiscal years All date filters require `YYYY-MM-DD`. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Federal fiscal year of the award (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance **current end** date range. | ### Place of performance | Param | What it does | | --- | --- | | `pop_state` | State code, e.g. `VA` (case-insensitive). OR via `|`. | | `pop_country` | Country code, ISO 3166 alpha-3, e.g. `USA` (case-insensitive). OR via `|`. | | `pop_zip` | Five-digit ZIP code (exact). OR via `|`. | ### Dollars | Param | What it does | | --- | --- | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | 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](../data-dictionary/assistance-loans.md#money). ## 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: | Input | Matches | | --- | --- | | `flood mitigation` | Awards matching every word. | | `broadband or fiber` | Awards matching either word. | | `housing -veterans` | Awards matching `housing` but not `veterans`. | | `"rural health"` | Awards matching **both** words, anywhere. A quoted phrase is not matched as adjacent words on these endpoints. | 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](contracts.md#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](../guides/patterns/result-counts.md). The sub-routes use page-number pagination (`page`, `limit`): | Sub-route | Default `limit` | Max `limit` | | --- | --- | --- | | `/transactions/` | 100 | 500 | | `/listings/` | 10 | 100 | ## Response shaping These endpoints support [response shaping](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) via `?shape=`. Default shape (list and detail, no `?shape=` param): ```text 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:** | Expansion | Fields | | --- | --- | | `recipient(...)` | `uuid`, `uei`, `duns`, `legal_business_name`, `legal_business_name_raw`, `county`, `congressional_district`, `congressional_district_original`, `highest_owner`, `business_types` | | `recipient_address(...)` | `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `county_fips`, `state_fips`, `foreign_city_name`, `foreign_province_name`, `foreign_postal_code`, `congressional_district_original`, `congressional_district_current` | | `place_of_performance(...)` | `country`, `state_code`, `state_name`, `state_fips`, `county_fips`, `county_name`, `city_name`, `zip_code`, `zip_plus_four`, `code`, `scope`, `foreign_location` | | `awarding_office(...)`, `funding_office(...)` | `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `assistance_listing(...)` | `number`, `title` (from the [assistance listings](assistance-listings.md) catalog) | | `assistance_type(...)` | `code`, `description` | | `period_of_performance(...)` | `start_date`, `current_end_date` | | `officers(...)` | `highly_compensated_officer_1_name`, `highly_compensated_officer_1_amount`, … through `highly_compensated_officer_5_amount` | | `obligations_by_fiscal_year(...)` | `fiscal_year`, `obligated` | | `listings(...)` | `cfda_number`, `is_primary`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `transactions_count`, `first_action_date`, `last_action_date` | | `transactions(...)` | `key`, `modification_number`, `transaction_date`, `action_type`, `assistance_type_code`, `correction_delete_indicator`, `cfda_number`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `award_amount_basis`, `award_recipient_basis`, `action_date_fiscal_year`, `last_modified_date`, `initial_report_date` | A few behaviors worth knowing: - **`recipient` is a shared recipient record, shaped like an [entity](entities.md).** 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](../data-dictionary/assistance-loans.md#business-types)). - **`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](#endpoints) pages through them instead. ## Access These endpoints are available on every plan, and no field on them is tier-gated (see [Plans & Data Access](../getting-started/pricing.md)). Call them with an API key or OAuth token (see [Authentication](../getting-started/authentication.md)), under the same [rate limits](../guides/patterns/rate-limits.md) as the other award endpoints. They aren't alertable: no [webhook alert](../webhooks/index.md) covers financial-assistance awards. ## Examples ```bash # 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](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose first-class methods for these endpoints. You can call them through the SDK's internal HTTP helper. === "Python (tango-python)" ```python 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"]) ``` === "Node (tango-node)" ```ts 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); } ``` --- --- description: "Filtering, search, ordering, shaping and pagination for /api/assistance/other/, Tango's endpoint for insurance, asset forfeiture, sales or donations of property, and other assistance from USAspending." tags: [assistance, insurance, awards, api, reference] updated: 2026-10-27 --- # Other assistance Federal financial-assistance awards of insurance, asset forfeiture, sales or donations of property, and other assistance are exposed at `/api/assistance/other/`. For field definitions, see the [Other assistance Data Dictionary](../data-dictionary/assistance-other.md). For how assistance awards, transactions, listings and recipients fit together, see the [Financial assistance overview](assistance.md). The other assistance endpoints, which take the same filters and shapes: [Grant awards](assistance-grants.md) Β· [Loans](assistance-loans.md) Β· [Direct payments](assistance-direct-payments.md). The endpoint holds every award whose GSDM assistance type is one of: | Code | Assistance type | | --- | --- | | `F005` | Indemnity/Insurance | | `F008` | Asset Forfeiture/Equitable Sharing | | `F009` | Sale, Exchange, or Donation of Property and Goods | | `F010` | Other Financial Assistance | | `-1` | Not specified | This endpoint also holds awards whose assistance type is not specified (`-1`). `insurance_coverage_amount` is reported only for FEMA's National Flood Insurance Program (`cfda_number=97.022`), whose aggregate records report coverage as obligations; it's `null` for every other program. ## Endpoints - `GET /api/assistance/other/` (list, with filtering, search and ordering) - `GET /api/assistance/other/{key}/` (detail) - `GET /api/assistance/other/{key}/transactions/` (the award's transactions, latest first) - `GET /api/assistance/other/{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`: ```text cfda_number=93.778|93.767 ``` ### Award identifiers | Param | What it does | | --- | --- | | `key` | Award key (exact). OR via `|`. | | `fain` | Federal Award Identification Number (exact). OR via `|`. | | `uri` | Unique Record Identifier, carried by aggregate records (exact). OR via `|`. | | `funding_opportunity_number` | The funding opportunity number the award was made under, as on the Grants.gov opportunity (exact). OR via `|`. | ### Recipients | Param | What it does | | --- | --- | | `uei` | Recipient UEI (exact). OR via `|`. | | `recipient` | Recipient name or UEI. Each term matches the 100 recipients closest to it by name similarity, among recipients whose `legal_business_name` contains it (case-insensitive) and who have an award on this endpoint: 10 for a term under four characters or a bare business suffix such as `inc` or `llc`. A UEI-shaped term matches the recipient with that UEI. A term under three characters returns **400**. Works for every recipient, with or without a UEI. OR via `|` only; the word `OR` is not a separator here. | A broad `recipient` term covers only its closest names, not every recipient whose name contains it. To pin one recipient, filter on `uei`. ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Awarding agency (code, name or abbreviation; best-effort matching). OR via `|`. See [Agency search](../guides/patterns/agency-search.md). | | `funding_agency` | Funding agency or department, with the same matching as `awarding_agency`. OR via `|`. | ### Programs and types | Param | What it does | | --- | --- | | `cfda_number` | The award's **primary** assistance listing (CFDA) number, e.g. `93.778`. OR via `|`. An award funded under several programs matches only on its primary one; its other programs are in [`listings`](#endpoints). | | `assistance_type` | GSDM assistance type code (`F001`–`F010`), case-insensitive. OR via `|`. This endpoint holds only `F005`, `F008`, `F009`, `F010`, `-1`, so another code matches nothing. | | `record_type` | `1` (aggregate), `2` (non-aggregate) or `3` (non-aggregate to an individual, PII-redacted). OR via `|`. An unknown code matches nothing. | | `business_funds_indicator` | `NON` (not Recovery Act) or `REC` (Recovery Act), case-insensitive. OR via `|`. | | `disaster_emergency_fund_code` | Disaster Emergency Fund Code (DEFC), e.g. `L`, case-insensitive. Matches the code as a whole within the award's list, so `L` doesn't match inside another code. OR via `|`. | ### Dates and fiscal years All date filters require `YYYY-MM-DD`. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Federal fiscal year of the award (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance **current end** date range. | ### Place of performance | Param | What it does | | --- | --- | | `pop_state` | State code, e.g. `VA` (case-insensitive). OR via `|`. | | `pop_country` | Country code, ISO 3166 alpha-3, e.g. `USA` (case-insensitive). OR via `|`. | | `pop_zip` | Five-digit ZIP code (exact). OR via `|`. | ### Dollars | Param | What it does | | --- | --- | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | 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](../data-dictionary/assistance-other.md#money). ## 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: | Input | Matches | | --- | --- | | `flood mitigation` | Awards matching every word. | | `broadband or fiber` | Awards matching either word. | | `housing -veterans` | Awards matching `housing` but not `veterans`. | | `"rural health"` | Awards matching **both** words, anywhere. A quoted phrase is not matched as adjacent words on these endpoints. | 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/other/?ordering=-award_date` - Largest first, comparable across endpoints: `GET /api/assistance/other/?ordering=-pragmatic_obligations` ## Pagination and counts The four list endpoints use **cursor-based (keyset) pagination**, like the other award endpoints (see [Contracts pagination](contracts.md#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](../guides/patterns/result-counts.md). The sub-routes use page-number pagination (`page`, `limit`): | Sub-route | Default `limit` | Max `limit` | | --- | --- | --- | | `/transactions/` | 100 | 500 | | `/listings/` | 10 | 100 | ## Response shaping These endpoints support [response shaping](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) via `?shape=`. Default shape (list and detail, no `?shape=` param): ```text 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:** | Expansion | Fields | | --- | --- | | `recipient(...)` | `uuid`, `uei`, `duns`, `legal_business_name`, `legal_business_name_raw`, `county`, `congressional_district`, `congressional_district_original`, `highest_owner`, `business_types` | | `recipient_address(...)` | `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `county_fips`, `state_fips`, `foreign_city_name`, `foreign_province_name`, `foreign_postal_code`, `congressional_district_original`, `congressional_district_current` | | `place_of_performance(...)` | `country`, `state_code`, `state_name`, `state_fips`, `county_fips`, `county_name`, `city_name`, `zip_code`, `zip_plus_four`, `code`, `scope`, `foreign_location` | | `awarding_office(...)`, `funding_office(...)` | `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `assistance_listing(...)` | `number`, `title` (from the [assistance listings](assistance-listings.md) catalog) | | `assistance_type(...)` | `code`, `description` | | `period_of_performance(...)` | `start_date`, `current_end_date` | | `officers(...)` | `highly_compensated_officer_1_name`, `highly_compensated_officer_1_amount`, … through `highly_compensated_officer_5_amount` | | `obligations_by_fiscal_year(...)` | `fiscal_year`, `obligated` | | `listings(...)` | `cfda_number`, `is_primary`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `transactions_count`, `first_action_date`, `last_action_date` | | `transactions(...)` | `key`, `modification_number`, `transaction_date`, `action_type`, `assistance_type_code`, `correction_delete_indicator`, `cfda_number`, `obligated`, `pragmatic_obligations`, `non_federal_funding_amount`, `indirect_cost_federal_share_amount`, `face_value_of_loan`, `loan_subsidy_cost`, `award_amount_basis`, `award_recipient_basis`, `action_date_fiscal_year`, `last_modified_date`, `initial_report_date` | A few behaviors worth knowing: - **`recipient` is a shared recipient record, shaped like an [entity](entities.md).** 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](../data-dictionary/assistance-other.md#business-types)). - **`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](#endpoints) pages through them instead. ## Access These endpoints are available on every plan, and no field on them is tier-gated (see [Plans & Data Access](../getting-started/pricing.md)). Call them with an API key or OAuth token (see [Authentication](../getting-started/authentication.md)), under the same [rate limits](../guides/patterns/rate-limits.md) as the other award endpoints. They aren't alertable: no [webhook alert](../webhooks/index.md) covers financial-assistance awards. ## Examples ```bash # Insurance awards, newest first curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/other/?assistance_type=F005&ordering=-award_date" # National Flood Insurance Program coverage curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/other/?cfda_number=97.022&shape=key,award_date,insurance_coverage_amount,place_of_performance(state_code,county_name)" # Sales, exchanges or donations of property in fiscal year 2024 curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/assistance/other/?assistance_type=F009&fiscal_year=2024" ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose first-class methods for these endpoints. You can call them through the SDK's internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/assistance/other/", params={"assistance_type": "F005", "ordering": "-award_date", "limit": 25}, ) for award in data["results"]: print(award["key"], award["award_date"], award["obligated"]) ``` === "Node (tango-node)" ```ts 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/other/", { assistance_type: "F005", ordering: "-award_date", limit: 25, }); for (const award of data.results) { console.log(award.key, award.award_date, award.obligated); } ``` --- --- description: "Tango's financial-assistance award endpoints, grants, loans, direct payments and other assistance, and how the data is shaped: awards versus transactions, assistance listings, retired award IDs, recipients without a UEI, and how awards differ from Grants.gov opportunities." tags: [assistance, grants, loans, concepts, api] updated: 2026-10-27 --- # 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: | Endpoint | API reference | Data dictionary | | --- | --- | --- | | `/api/assistance/grants/` | [Grant awards](assistance-grants.md) | [Grant awards fields](../data-dictionary/assistance-grants.md) | | `/api/assistance/loans/` | [Loans](assistance-loans.md) | [Loans fields](../data-dictionary/assistance-loans.md) | | `/api/assistance/direct_payments/` | [Direct payments](assistance-direct-payments.md) | [Direct payments fields](../data-dictionary/assistance-direct-payments.md) | | `/api/assistance/other/` | [Other assistance](assistance-other.md) | [Other assistance fields](../data-dictionary/assistance-other.md) | | `/api/assistance_listings/` | [Assistance listings (CFDA)](assistance-listings.md) | [Assistance listing fields](../data-dictionary/assistance-listings.md) | All four award endpoints take the same filters, shapes and ordering, and share [pagination and result counts](../guides/patterns/result-counts.md), [response shaping](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) and [agency search](../guides/patterns/agency-search.md). They're available on every plan, with no tier-gated fields ([Plans & Data Access](../getting-started/pricing.md)), and they aren't alertable through [webhooks](../webhooks/index.md). ## Opportunities versus awards These two are easy to confuse: | | Grant **opportunities** | Assistance **awards** | | --- | --- | --- | | Endpoint | [`/api/grants/`](grants.md) | `/api/assistance/grants/` (and loans, direct payments, other) | | What it is | A funding announcement, open for applications | Money an agency has obligated to a recipient | | Source | Grants.gov | USAspending | | When it exists | Before anyone applies | After the agency makes the award | 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: | Endpoint | Assistance types | | --- | --- | | [`/api/assistance/grants/`](assistance-grants.md) | `F001` Grant, `F002` Cooperative Agreement | | [`/api/assistance/loans/`](assistance-loans.md) | `F003` Direct Loan, `F004` Loan Guarantee | | [`/api/assistance/direct_payments/`](assistance-direct-payments.md) | `F006` Direct Payment for Specified Use, `F007` Direct Payment with Unrestricted Use | | [`/api/assistance/other/`](assistance-other.md) | `F005` Indemnity/Insurance, `F008` Asset Forfeiture/Equitable Sharing, `F009` Sale, Exchange, or Donation of Property and Goods, `F010` Other Financial Assistance, and awards with no type specified | 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](../data-dictionary/assistance-grants.md#assistance-types)). 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](assistance-listings.md) 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](entities.md), 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](assistance-grants.md#recipients), 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](concepts/federal-agency-hierarchy.md); - `summary`, `title` and `purposes_differ`. --- --- description: "Endpoints, sources, filtering and alerts for /api/news/award_announcements/, one feed of the Department of War's daily contracts release and MakeGov-generated announcements of new civilian IDVs and OTAs." tags: [news, awards, api, reference] updated: 2026-10-30 --- # Award announcements Award announcements are short paragraphs saying that an award was made, served from two sources at `/api/news/award_announcements/`. For field definitions, see the [Award announcements Data Dictionary](../data-dictionary/award-announcements.md). Every row names its `source`, so you can always tell government text from text MakeGov wrote. The dataset is updated daily. **Authentication**: this endpoint requires authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. **Plans**: every filter and every field is available on **every plan, including Free**. ## Endpoints - `GET /api/news/award_announcements/` β€” list, with filtering, search, ordering and pagination - `GET /api/news/award_announcements/{uuid}/` β€” one announcement The detail path segment must be a valid UUID; anything else is a 404. ## Two sources | `source` | What it covers | Who wrote the text | | --- | --- | --- | | `official_release` | Awards of $7.5 million or more in the Department of War's daily contracts release, from March 2026. | The Department of War. `text` is served as published. | | `makegov_generated` | New civilian IDVs of $25 million or more, and every new OTA and OT IDV, from June 2026. | MakeGov, from FPDS award data. A language model summarizes the purpose and writes the title. **It is not government text.** | Each generated paragraph is written in the style of the official release, so read `source` rather than the wording. The figures, dates and names in a generated paragraph come from FPDS through a fixed template, and FPDS can be wrong or incomplete. Treat a generated announcement as a lead, and check the award itself before you rely on it: `piids` on the row works as the `piid` filter on [IDVs](idvs.md), [OTAs](otas.md) and [OTIDVs](otidvs.md). One generated row can announce several awards when IDVs join a vehicle together, so the row carries lists of `piids`, `award_uuids` and awardees. For those rows, the $25 million test applies to the vehicle's ceiling rather than to each IDV. Orders and other child awards are not announced. ### Source fields `source`, `source_name` and `source_url` are in the default shape of every row, on both the list and the detail endpoint. | Field | `official_release` | `makegov_generated` | | --- | --- | --- | | `source` | `official_release` | `makegov_generated` | | `source_name` | `Department of War daily contracts release` | `MakeGov, generated from FPDS award data` | | `source_url` | The release on war.gov | Always `null`: no page exists to link to | ### A generated announcement is dropped when an official release covers the award When an official release covers the same award as a generated announcement, by award link or by contract number, the generated row is removed and only the official one remains. This can happen after the generated row was published, so a stored `makegov_generated` uuid can later return **404**. A withdrawn release covers nothing, so a generated announcement of the same award stays. ### Withdrawn announcements The Department of War sometimes publishes a correction saying that an award was not released, not awarded or rescinded. That announcement is marked `is_withdrawn: true`. - Lists and alerts hide it by default. Add `include_withdrawn=true` to include it. - It stays retrievable by uuid at `/api/news/award_announcements/{uuid}/`, with or without that parameter. Exclude withdrawn rows from anything you count or sum, which the default does for you. ### Corrections A correction is not its own row. The corrected values are applied to the announcement it corrects: `amount`, `piids` and `is_withdrawn` show the corrected values, `text` stays as published, and `corrections` records what changed. A correction that can't be matched to one original announcement is not served. ## `published_date` versus `award_date` The two dates answer different questions, and each source fills them differently. | Field | `official_release` | `makegov_generated` | | --- | --- | --- | | `published_date` | The date of the release. | The date MakeGov first announced the award. It does not move when the row is later updated. Rows from the initial backfill carry their award date. | | `award_date` | `null`. The release states dates only in its text. | The award's date; the earliest of them when a row covers several awards. | FPDS reports awards after they are made, so a generated row's `published_date` is usually later than its `award_date`. `published_date_*` filters work across both sources; `award_date_*` filters return only generated rows. ## Fields that differ by source These fields come from the official release and are always `null` on a generated row: - `component` - `contracting_activity` - `corrections` - `is_modification` - `small_business` on each awardee `is_withdrawn` is also `null` on a generated row. `obligated_at_award` is not official-only: a generated row carries the FPDS figure when every award in the row has had a single action, and `null` otherwise. In the other direction, `announcement_type` is set only on generated rows, and `civilian` is `false` on every official row. A generated row can be `civilian: false` too, because every new DoD OTA and OT IDV is announced. Because they are null, a filter on these fields narrows the result to one source: `component`, `small_business` and `is_modification` return only official rows, and `announcement_type` returns only generated rows. For new awards across both sources, use `action_type=new_award`. ## Filtering Multi-value filters accept `|` (or the word `OR`) for OR. Date filters require `YYYY-MM-DD`; invalid dates or inverted ranges return **400** (see [Date filters](shared.md#date-filters)). | Param | What it does | | --- | --- | | `search` | Full-text search over the title and text. A match in the title ranks above a match in the text. Wrap a value in double quotes for a phrase. Min 2 characters. | | `source` | `official_release` or `makegov_generated`. Any other value returns **400**. | | `agency` | The awarding organization, by name, abbreviation, code or organization key, e.g. `Navy`. A department includes its sub-agencies. Multi-value: use `\|` for OR. See [Agency search](../guides/patterns/agency-search.md). | | `component` | The DoD component heading the official release, e.g. `NAVY`. Case-insensitive exact match. Multi-value: use `\|` for OR, up to 500 values. Official rows only. | | `published_date_after`, `published_date_before` | Published-date range (`YYYY-MM-DD`). | | `award_date_after`, `award_date_before` | Award-date range (`YYYY-MM-DD`). Generated rows only. | | `amount_min`, `amount_max` | Range on `amount`, in US dollars. Read `value_kind` alongside it: see [Amounts](#amounts). | | `piid` | A contract number named in the announcement, e.g. `N00019-25-C-0070` or `N0001925C0070`. Dashes and case are ignored. Multi-value: use `\|` for OR. A value with no letter or digit returns **400**. | | `awardee` | Case-insensitive substring match on awardee names, not locations. At least 3 characters; shorter returns **400**. | | `uei` | An exact awardee UEI. Official releases print no UEI, so this matches an official row only where one was resolved. | | `action_type` | `new_award`, `modification`, `option_exercise`, `order` or `unknown`. Exact match. Multi-value: use `\|` for OR, up to 500 values. | | `announcement_type` | `new_vehicle`, `on_ramp`, `single_award`, `vehicle_pending`, `ota` or `ot_idv`. Exact match. Multi-value: use `\|` for OR, up to 500 values. Generated rows only. | | `civilian` | Boolean. Announces a civilian award. | | `small_business` | Boolean. `true` keeps announcements with at least one small-business awardee. `false` keeps those whose awardees are stated not to be small. Generated rows state neither, so they match neither value. | | `is_modification` | Boolean. Announces a modification to an existing contract. Official rows only. | | `is_multiple_award` | Boolean. On an official row, the announcement names more than one awardee. On a generated row, `true` means a multiple-award vehicle, which can name a single awardee. | | `include_withdrawn` | Boolean. `true` includes withdrawn announcements. See [Withdrawn announcements](#withdrawn-announcements). | An unrecognized query parameter on the list endpoint returns **400** rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page. ### Amounts `amount` is the announcement's headline dollar figure, and `value_kind` says what it measures. It is `null` when the announcement states none. Amounts are not comparable across kinds: a `ceiling` is an upper bound, a `combined_ceiling` is shared by every awardee in a pool, and a `modification_value` is a change rather than a total. Sum or rank `amount` only within one `value_kind`. The kinds are listed in the [data dictionary](../data-dictionary/award-announcements.md#value_kind). ## Ordering `ordering=` allowlist: - `published_date` β€” the default is `-published_date` (newest first) - `amount` - `rank` β€” relevance; requires a non-empty `search`, and is the implicit default under one `-amount` and `-published_date` put rows without a value last. Results are tie-broken deterministically, so paging through a large result set never repeats or skips an announcement. ## Pagination Standard page-number pagination: - `page` (default 1) - `limit` (default 10, max 100) Responses carry `count / next / previous / results`. ## Shaping See [Response shaping](../guides/patterns/response-shaping.md) for the syntax. - **List default:** `uuid`, `source`, `source_name`, `source_url`, `published_date`, `award_date`, `title`, `amount`, `value_kind`, `action_type`, `announcement_type`, `awardee_count`, `piids`, `is_modification`, `is_multiple_award`, `is_withdrawn`, `awardees(*)` - **Detail default:** the list fields plus `source_record_id`, `text`, `obligated_at_award`, `award_kind`, `award_uuids`, `civilian`, `component`, `contracting_activity`, `corrections`, `organization(*)` Lists leave out `text` because a single paragraph can run past 16,000 characters. Name it in `?shape=` to get it; every field is available on both the list and the detail endpoint. ### Expansions - `awardees(...)` β€” `name`, `uei`, `location`, `small_business` - `organization(...)` β€” `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` ## Alerts `award_announcement` is an alertable query type, delivered as `alerts.award_announcement.match` and using the same filters documented above. See the [webhooks guide](../webhooks/index.md). An alert fires when a matching announcement first appears and when one changes, so expect a second alert when a correction is applied or when an official announcement's award links fill in. Withdrawn announcements do not match unless the alert sets `include_withdrawn` to `true`. A generated row being dropped in favor of an official release does not fire on the generated row, though the official row can match on its own. To receive only government text, include `"source": "official_release"` in the alert's filters. ## Examples ```bash # Official announcements of $100 million or more GET /api/news/award_announcements/?source=official_release&amount_min=100000000 # Everything the Navy has announced since September GET /api/news/award_announcements/?agency=Navy&published_date_after=2026-09-01 # New OTAs and OT IDVs written by MakeGov GET /api/news/award_announcements/?source=makegov_generated&announcement_type=ota|ot_idv # New awards from both sources GET /api/news/award_announcements/?action_type=new_award # Announcements naming one contract number GET /api/news/award_announcements/?piid=N00019-25-C-0070 # Announcements naming an awardee GET /api/news/award_announcements/?awardee=example%20systems # A phrase, ranked by relevance GET /api/news/award_announcements/?search=%22hypersonic%22 # Include withdrawn announcements GET /api/news/award_announcements/?source=official_release&include_withdrawn=true # A lean list payload with the text and awardee names GET /api/news/award_announcements/?shape=uuid,source,published_date,title,text,awardees(name) # Detail, with every default field GET /api/news/award_announcements/{uuid}/ ``` Notes: - `*` is only valid inside expansions, such as `awardees(*)`. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Endpoints, filtering, and ordering for the beta /api/budget/accounts/ federal-account budget resource and its recipient and quarterly drill-downs." tags: [budget, api, reference] updated: 2026-10-09 --- # Budget !!! warning "Beta β€” surface may change" The `/api/budget/...` endpoints and the `/api/entities/{uei}/budget-flows/` action are **beta**. Data is real and refreshed on the normal cadence, but field names, shape leaves, default fields, filter names, and URL paths may still change based on early-consumer feedback. Pin a specific request shape (`?shape=...`) in production code, and watch the [changelog](../CHANGELOG.md) for the move-to-stable announcement. Federal-account budget data β€” what Congress requested, what it enacted, what got apportioned, what's been obligated, and what's been outlayed β€” joined to FPDS contract activity. Each row is one (federal account Γ— fiscal year). For task-oriented walkthroughs, see [Explore federal budget data](../guides/how-to/explore-federal-budget.md). For field definitions, see the [Budget Data Dictionary](../data-dictionary/budget.md). ## Endpoints - `GET /api/budget/accounts/` β€” list + filter + search. - `GET /api/budget/accounts/{pk}/` β€” detail. - `GET /api/budget/accounts/{pk}/recipients/` β€” funding-office Γ— recipient drill-down with hydrated contracts. - `GET /api/budget/accounts/{pk}/quarters/` β€” TAS-grain SF-133 quarterly flow (FY21+). Related budget surfaces on other resources: - `GET /api/entities/{uei}/budget-flows/` β€” federal accounts that paid a given vendor (the inverse of `/recipients/`). Documented below. - `GET /api/organizations/{key}/?shape=...,budget_appropriation(*),budget_spending(*)` β€” org-level rollups. See [Organizations](organizations.md). ## Filtering | Param | What it does | | --- | --- | | `search` | Free-text search across `account_title`, `agency_name`, `bureau_name`. | | `federal_account_symbol` | Exact match (also `__in` for multi). E.g. `075-0512`. | | `fiscal_year` | Exact match, also `__in`, `__gte`, `__lte`. | | `data_through_period` | Fiscal period (1–12) the account-year's figures run through. Exact match, also `__gte`, `__lte`, `__isnull`. `data_through_period=12` keeps only complete years β€” see [Partial fiscal years](#partial-fiscal-years). | | `agency_code` | CGAC 3-character code. `__in` for multi-agency queries. | | `bureau_name` | Exact, `__in`, or `__icontains` for fuzzy matching. | | `account_title` | `__icontains` for fuzzy matching on account title. | | `bea_category` | Budget enforcement category: `Discretionary`, `Mandatory`, or `Net interest`. Exact, case-sensitive match; `__in` for multi. | | `on_off_budget` | `On-budget` or `Off-budget`. Exact, case-sensitive match. | | `subfunction_code` | OMB budget subfunction code (e.g. `051`, `551`). | | `account_category` | `budgetary`, `credit_financing`, `request_only` or `proposed` (also `__in`). Which values to include depends on what you are summing β€” see [Account category](#account-category). | Every dollar and ratio field also supports `__gte` / `__lte` range filters. The full list of range-filterable fields: - **Dollars:** `requested_ba`, `enacted_ba`, `apportioned`, `obligated_total`, `outlayed_total`, `unobligated_balance`, `contract_obligated`, `contract_outlayed`, `assistance_obligated`, `assistance_outlayed` - **Ratios (capped + raw):** `contract_share_of_obligated_capped`, `obligated_to_apportioned_pct(_capped)`, `apportioned_to_enacted_pct(_capped)`, `obligated_to_enacted_pct(_capped)`, `outlayed_to_obligated_pct(_capped)`, `unobligated_pct` - **Trends:** `enacted_ba_yoy_pct`, `obligated_yoy_pct`, `enacted_ba_5yr_cagr`, `ba_growth_next_year_pct` - **Request-vs-actual:** `actual_vs_requested_contract(_capped)` See [Budget Data Dictionary](../data-dictionary/budget.md) for what each field means and the [exploration guide](../guides/how-to/explore-federal-budget.md) for filter recipes. ## Ordering Pass `?ordering=` (prefix with `-` for descending). Allowed sort fields: `fiscal_year`, `agency_code`, `federal_account_symbol`, `enacted_ba`, `obligated_total`, `outlayed_total`, `contract_obligated`, `contract_share_of_obligated_capped`, `obligated_to_apportioned_pct_capped`, `obligated_to_enacted_pct_capped`, `ba_growth_next_year_pct`, `actual_vs_requested_contract_capped`, `enacted_ba_yoy_pct`, `enacted_ba_5yr_cagr`, `modified`. Default sort is `-fiscal_year, -enacted_ba` β€” the un-filtered list lands on the largest accounts of the most recent fiscal year. Within a fiscal year, accounts with no `enacted_ba` (null) sort after every other account, and ties break on the account's id, so pages are stable. An explicit `?ordering=` also sorts nulls last in both directions, and a field that is not in the list above returns `400` with the allowed fields rather than being ignored. ## Pagination Standard page-number pagination: `count / next / previous / results`. - `page` (default 1) - `limit` (default 10, max 100) The `/recipients/`, `/quarters/`, and `/budget-flows/` drill-downs default to 25 per page (max 100). ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via `?shape=`. **Default shape** (no `?shape=` param): identity fields (including `data_through_period`, right after `fiscal_year`, and `account_category`) + lifecycle dollars + the capped ratios that show up in the most common workflows + `contract_obligated`, `contract_share_of_obligated_capped`, `assistance_obligated`, `ba_growth_next_year_pct` + `source_anomalies`. **On-demand expansions:** | Expand | Returns | Notes | | --- | --- | --- | | `appendix(*)` | President's Budget Appendix object-class breakdown (16 OMB request buckets β€” personnel comp, travel, contractual services, grants, etc. β€” plus granule ID and PDF URL). | `null` for accounts with no Appendix data (typically large mandatory programs). Coverage: FY08–FY27. | | `narratives(*)` | List of Appendix narrative + appropriations text entries for this (FA, FY). | `null` when no narratives exist. ~5% of accounts have multiple narratives per year (split by subaccount). Text fields can be several KB each β€” only loaded when explicitly requested. | ```bash # Default shape /api/budget/accounts/ # Pull everything /api/budget/accounts/{pk}/?shape=* # Detail + Appendix breakdown /api/budget/accounts/{pk}/?shape=*,appendix(*) # Detail + Appendix breakdown + narrative text /api/budget/accounts/{pk}/?shape=*,appendix(*),narratives(*) # Trends cluster /api/budget/accounts/?shape=federal_account_symbol,account_title,enacted_ba,enacted_ba_yoy_pct,enacted_ba_5yr_cagr,contract_obligated_5yr_cagr ``` ## Recipients drill-down ```text GET /api/budget/accounts/{pk}/recipients/ GET /api/budget/accounts/{pk}/recipients/?funding_organization_id={org_uuid} ``` One row per (funding office Γ— recipient Γ— this account-year) on the contract side, sorted by `contract_obligated` desc. Each row carries: | Field | Meaning | | --- | --- | | `funding_organization_id` | Organization UUID β€” resolvable via `/api/organizations/{key}/`. | | `funding_office` | Hydrated payload with full Department / Agency / Office hierarchy for the funding org. | | `recipient_id` | UEI β€” resolvable via `/api/entities/{uei}/`. | | `recipient` | Hydrated payload with `uei`, `legal_business_name`, `dba_name`. | | `contract_obligated`, `contract_outlayed` | Dollar flows. | | `n_contracts` | Distinct PIID count under this (FA, funding office, recipient). | | `contracts[]` | Minimal `Contract` shape per PIID β€” `key`, `piid`, `naics`, `psc`, `obligated`, `award_date`. Use `key` to follow back to the full Contract record. | The raw PIID array isn't surfaced β€” each `contracts[]` row carries its own `piid`, so the analytics-only consumer can reconstruct the list without bandwidth duplication. **Query params:** - `funding_organization_id` β€” Narrow to a single funding office (Organization UUID). - `limit` β€” Page size (default 25, max 100). **Top-level response envelope** includes `federal_account_symbol` and `fiscal_year` for context. ## Quarterly cash flow ```text GET /api/budget/accounts/{pk}/quarters/ GET /api/budget/accounts/{pk}/quarters/?tas=075-2024-2024-0512 ``` One row per (Treasury Account Symbol Γ— quarter Γ— period type) for this account-year. A federal account typically rolls up several TAS (different appropriation-year vintages), so the response is a list rather than a single record. | Field | Meaning | | --- | --- | | `tas` | Full Treasury Account Symbol including appropriation year. | | `quarter` | `1` through `4`. | | `period` | `quarterly` or `cumulative` β€” both shapes are returned per quarter. | | `obligated_quarterly`, `outlayed_quarterly` | Flow during the quarter. | | `obligated_cumulative`, `outlayed_cumulative` | Running total through end of the quarter. | | `quarterly_source` | Provenance flag β€” which SF-133 snapshot the row came from. | **Coverage:** FY21+. Earlier years return an empty page; use the account detail's lifecycle fields (`obligated_total`, `outlayed_total`) for FY17–FY20. **Query params:** - `tas` β€” Narrow to a single TAS. - `limit` β€” Page size (default 25, max 100). ## Entity budget-flows ```text GET /api/entities/{uei}/budget-flows/ GET /api/entities/{uei}/budget-flows/?fiscal_year=2024 ``` The inverse of `/recipients/` β€” given a UEI, list the federal accounts that paid this vendor. One row per (account Γ— funding office Γ— this UEI) flow, sorted by `contract_obligated` desc. Each row carries surrounding account context (account title, agency, bureau, BEA category, total enacted BA, contract share of obligated) plus the hydrated `funding_office` and `contracts[]` payloads (same shape as the recipients drill-down). **Contract-side only** β€” grants and other assistance flows are not in this index. **Query params:** - `fiscal_year` β€” Restrict to one FY (omit for all years). - `limit` β€” Page size (default 25, max 100). This endpoint requires authentication. ## Coverage windows | Surface | Years covered | | --- | --- | | `/api/budget/accounts/` lifecycle | FY17–FY26 | | `appendix(*)` shape leaf | FY08–FY27 | | `narratives(*)` shape leaf | FY08–FY27 | | `/quarters/` | FY21+ | | `/recipients/`, `/budget-flows/` | FY17–FY26 | Out-of-range requests return empty lists or `null`-valued leaves β€” no error. ## Capped vs raw ratios Most ratio fields ship in three variants: `*_pct`, `*_pct_capped`, and `*_pct_capped_flag`. The capped variant bounds extreme values (typically at 5.0) so the field sorts and charts cleanly; the flag tells you whether the cap was applied for that row. Use raw when you need exact math, capped when filtering/sorting/visualizing. ## Partial fiscal years `data_through_period` is the fiscal period (1–12) of USAspending File A that an account-year's figures run through, and `null` when the row has no File A data (for example, an account known only from apportionments or the Budget Appendix). Closed fiscal years read `12`. The latest fiscal year is year-to-date and stays below `12` until it closes. The `X-Tango-Data-As-Of` header (below) names the latest period in the current publication. Until the data pipeline derives the period from the source, rows may carry `12` or `null` instead of the real period, so treat a value as a hint, not a guarantee. A partial year is not comparable to a closed one. Beyond the missing months, mid-year figures for indefinite and trust-fund appropriations can run high and settle lower by year-end, so a partial-year `enacted_ba` can exceed the prior year's final figure without any real increase. Check `data_through_period` before comparing the latest year with earlier ones, or filter to complete years: ```text /api/budget/accounts/?fiscal_year__gte=2022&data_through_period=12 ``` Responses also carry an `X-Tango-Data-As-Of` header with the latest fiscal year and period in the publication (e.g. `2026-P10`), and `X-Tango-Data-Published-At`; both are omitted until a validated publication is live. The header describes the whole response, while `data_through_period` says it on every row. ## Account category `account_category` is one of four values: | Value | What it is | | --- | --- | | `budgetary` | The default: current-law accounts with Treasury File A data. | | `credit_financing` | Non-budgetary accounts that record the cash flows of federal direct loans and loan guarantees. They carry apportionments but no obligations, and have no `enacted_ba`. Their apportionments are not budget authority. | | `request_only` | Current-law accounts with a President's Budget / Appendix request (`requested_ba`) and no File A data, such as NIH's `075-9915`. Every execution column (obligations, outlays, apportionments, contract figures) and `enacted_ba` is `null`. | | `proposed` | Recurring President's Budget requests for programs Congress never created, such as the EV Fund `047-0623`. Same shape as `request_only`, but not current law. | All four are served and filterable. Which to include when you add rows up depends on the figure: - **Apportionment, obligation and enacted sums:** use `account_category=budgetary`. Credit financing apportionments are not budget authority, so including them double-counts; `request_only` and `proposed` rows have null execution figures and add nothing. - **A current-law `requested_ba` total:** use `account_category__in=budgetary,request_only`. Filtering to `budgetary` alone drops the request-only accounts, so the request comes out low. Leave `credit_financing` and `proposed` out. ```text /api/budget/accounts/?fiscal_year=2025&agency_code=075&account_category=budgetary /api/budget/accounts/?fiscal_year=2027&agency_code=075&account_category__in=budgetary,request_only ``` The organization `budget_appropriation(*)` rollup follows the same rule: it leaves out credit financing and proposed accounts entirely, and adds `request_only` `requested_ba` to the department's request (request-only accounts are not counted in its other figures). ## Source anomalies `source_anomalies` is a list in the default shape, `[]` when the account-year is clean. Each element names one problem found in the source data for that row, and says whether Tango changed the served value (`capped`) or only reported the problem (`flagged`). | `code` | Condition | `action` | | --- | --- | --- | | `contract_exceeds_obligations` | USAspending File C contract obligations exceed the account's positive File A total obligations. `contract_obligated` is capped at `obligated_total`. | `capped` | | `assistance_exceeds_obligations` | File C assistance obligations exceed the account's positive File A total obligations. Values are unchanged. | `flagged` | | `contract_without_obligations` | File C reports contract obligations for an account whose File A total obligations are zero or negative. Values are unchanged. | `flagged` | The list of codes may grow; treat an unknown `code` as a reason to look closer rather than an error. There is no filter on anomalies β€” read the field. Field-by-field definitions of each element are in the [data dictionary](../data-dictionary/budget.md#source-anomalies). ```json "source_anomalies": [ { "code": "contract_exceeds_obligations", "field": "contract_obligated", "bound_field": "obligated_total", "action": "capped", "reported_value": 1250000000.0, "served_value": 980000000.0, "likely_cause": "single_row_outlier", "affected_fields": [ "contract_obligated", "contract_share_of_obligated_capped", "contract_obligated_yoy_pct", "contract_obligated_5yr_cagr", "actual_vs_requested_contract", "actual_vs_requested_contract_capped" ], "message": "USAspending File C contract obligations exceed this account's total obligations (File A). contract_obligated is capped at obligated_total; the excess most likely comes from a misreported File C row.", "source": { "dataset": "usaspending_file_c", "fiscal_year": 2025, "rows": [ { "fiscal_period": 9, "piid": "EXAMPLE0001", "parent_piid": null, "tas": "000-X-0000-000", "reporting_agency_id": "000", "transaction_obligated_amount": 300000000.0, "file_c_source": "db_dump" } ] } } ] ``` Dollar amounts, PIID and TAS in the example are illustrative. Both contract codes carry `source.rows`: up to three of the largest PIID-linked File C rows on the account and fiscal year, largest first (`[]` when none were found). `assistance_exceeds_obligations` carries no `rows`. !!! note "May be empty until the next data refresh" `source_anomalies`, `account_category` and `data_through_period` populate from the budget data publication. Until a publication carrying them is live, `source_anomalies` is `[]`, `account_category` is `budgetary` and `data_through_period` may be `null` or `12` on every row. ## SDK examples The Python and Node SDKs expose budget methods: `list_budget_accounts`, `get_budget_account`, `get_budget_account_quarters`, `get_budget_account_recipients`, and `get_entity_budget_flows` in Python, and `listBudgetAccounts`, `getBudgetAccount`, `getBudgetAccountQuarters`, `getBudgetAccountRecipients`, and `getEntityBudgetFlows` in Node. The [exploration guide](../guides/how-to/explore-federal-budget.md) has curl and Python `requests` recipes for raw HTTP. --- --- description: "Filtering, ordering, and pagination for /api/business_types/, the SAM.gov business-type code reference endpoint." updated: 2026-05-13 --- # Business types Business type reference data is exposed at `/api/business_types/`. For field definitions, see the [Business Types Data Dictionary](../data-dictionary/business-types.md). ## Endpoints - `GET /api/business_types/` (list) - `GET /api/business_types/{code}/` (detail) ## Value formats - **`code`**: 2-character alphanumeric, typically uppercase (examples: `A6`, `JT`, `XX`, `2R`). - **`certifier`**: In practice you’ll see a small set of values: `SBA`, `AbilityOne`, `Government`, `Self`. ## Filtering None. ## Ordering `/api/business_types/` does **not** support `ordering=...`. ## Pagination Business types use page-number pagination (static reference pagination defaults to larger pages): - `page` (default 1) - `limit` (default 1000, max 10000) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `name`, `code` - No expansions. Default shape (no `?shape=` param): `name,code` ```bash # Select a single field /api/business_types/?shape=name ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_business_types(limit=25) print("count:", resp.count) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listBusinessTypes({ limit: 25 }); console.log("count:", resp.count); ``` --- --- description: "Why federal organization data is split across SAM's Federal Hierarchy, USAspending, and legacy FPDS sources, and how Tango's Organizations model unifies them." tags: [federal-hierarchy, organizations, reference] updated: 2026-05-11 --- # Finding Federal Organizations: The Challenge of Incomplete Data Sources When building applications that work with federal procurement and assistance data, one of the first challenges you'll encounter is finding the right organization identifiers. The federal government maintains multiple overlapping but incomplete data sources, each with their own strengths and gaps. In this post, we'll explore why SAM's Federal Hierarchy is authoritative but incomplete, how USAspending fills some gaps but misses others, and how Tango's unified approach helps you find organizations reliably. ## The Authoritative Source: SAM Federal Hierarchy The [Federal Hierarchy from SAM.gov](https://sam.gov/content/entity-registration) is the official, authoritative source for federal organization structure. It provides a comprehensive tree of departments, agencies, and offices with unique `orgKey` identifiers and maintains the canonical parent-child relationships. However, the Federal Hierarchy has a critical limitation: **it's missing entire organizations that appear in transaction data**. For example, USAspending's office file contains thousands of organizations that don't exist in Federal Hierarchy. These include: - **Office `AC6091`** - "W462 USA AERONAUTICAL SVCS AGG" (Department of Defense office that appears in USAspending financial assistance data but is missing from Federal Hierarchy) - **Many DOD offices** - Hundreds of Department of Defense offices with codes like `W81YDE`, `W914J4`, `W90LDH` that appear in USAspending transaction data but aren't in Federal Hierarchy's structure - **Subtier agencies** - Organizations like "Center for Nutrition Policy and Promotion" (subtier code `12F3`) and "Federal Library and Information Center Committee" (subtier code `0363`) that exist in USAspending's subtier file but may be missing from Federal Hierarchy When you're working with contract data from FPDS or financial assistance from USAspending, you'll encounter codes like: - **CGAC codes** (like `069` for Department of Transportation) - **FPDS codes** (4-digit agency identifiers used in contract transactions) - **Subtier codes** (like `12F3` for Center for Nutrition Policy and Promotion) - **Office codes** (like `15JCRM` for the Criminal Division) The Federal Hierarchy may have the organization's name and structure, but it often lacks these operational codes that appear in actual transaction data. ## USAspending: Filling Some Gaps USAspending's database has data that complement the Federal Hierarchy, divided into top tier, subtier, and offices. USASpending contains data that are missing from Federal Hierarchy. For example, this includes abbreviations like `DOT`, `DHS`, `USDA`, as well as full names and mission statements. However, **USAspending has a critical gap: it doesn't include all FPDS contract data**. FPDS uses its own set of organization identifiers that don't always map cleanly to USAspending's structure. When you're working with contract transactions, you'll encounter organizations that exist in neither Federal Hierarchy nor USAspending: - **Legacy FPDS offices** - Historical contract offices that were used in FPDS transactions but have since been reorganized or decommissioned. These appear in FPDS contract data with office codes that don't match any organization in Federal Hierarchy or USAspending's reference files. - **Contract-specific organization IDs** - FPDS transaction data includes `fpds_org_id` values that are specific to contract processing workflows. These identifiers may reference organizations that were valid at the time of the contract but no longer exist in current organization reference data. - **Historical agency structures** - FPDS contains contract transactions from years past that reference agency codes and department IDs that have changed over time. The organization that awarded a contract in 2010 might have a different code structure today, and the old codes may not appear in either Federal Hierarchy or USAspending's current reference files. These FPDS identifiers appear in millions of contract transactions but aren't present in USAspending's organization files. Tango addresses this by maintaining legacy organization data from historical FPDS sources, ensuring that even old contract transactions can be properly linked to their awarding organizations. ## Tango's Unified Approach Tango consolidates all these sources into a single `Organization` model with a priority-based field provenance system. Here's how it works: ### Data Source Priority Tango loads organizations from multiple sources in priority order: 1. **Federal Hierarchy (Top Priority)** - The authoritative structure 2. **USAspending (Next Priority)** - Fills in missing codes and details 3. **Legacy models (Historical FPDS)** - Backfills from historical data Higher-priority sources won't be overwritten by lower-priority ones, ensuring that Federal Hierarchy's authoritative structure is preserved while USAspending fills in the operational codes. ### Deduplication When multiple Federal Hierarchy records map to the same organizational unit (same canonical code), Tango elects the best representative based on data completeness (name, codes, source priority, freshness) and demotes the others. Demoted records are preserved in the database for historical reference but excluded from API search and list results. Their `fh_key` values are recorded in the canonical record's history so lookups by any historical identifier still resolve correctly. ### Finding Organizations in Tango Tango provides several ways to find organizations, each optimized for different use cases: #### 1. Search by Name or Alias The `/api/organizations/` endpoint supports a `search` query parameter that uses a multi-stage search strategy: ```bash # Search by abbreviation, acronym, or name GET /api/organizations/?search=FEMA GET /api/organizations/?search=Department of Transportation GET /api/organizations/?search=Treasury OIG # Context-aware search ``` Or programmatically using the search library: ```python from agencies.lib.search import search_organizations # Finds organizations by abbreviation, acronym, or name results = search_organizations("FEMA") results = search_organizations("Department of Transportation") results = search_organizations("Treasury OIG") # Context-aware search ``` The search handles: - **Exact alias matches** - Catches abbreviations like "CIO", "OIG", "FEMA" - **Trigram similarity** - Handles typos like "FMEA" β†’ "FEMA" - **Full-text search** - Finds organizations by keywords in names - **Context-aware queries** - "Treasury OIG" finds the OIG within Treasury #### 2. Filter or look up by code The list endpoint supports a single code-based filter β€” **`cgac`** (department-level CGAC code). Other codes (FPDS, office, sub-tier) are not exposed as filters; use `?search=` or a path lookup instead: ```bash # Filter by CGAC (department-level) GET /api/organizations/?cgac=069 # Search across aliases / full-text β€” works for FPDS codes, office codes, # names, and abbreviations (multi-stage: aliases β†’ trigram β†’ FTS β†’ fuzzy) GET /api/organizations/?search=2100 GET /api/organizations/?search=15JCRM GET /api/organizations/?search=FEMA # Direct lookup by Federal Hierarchy key (zero-padded 9-char string) or UUID GET /api/organizations/{fh_key}/ GET /api/organizations/{key}/ ``` > **Note:** `?fpds_code=` and `?code=` query parameters are silently ignored (the response includes a `meta.warnings` entry). `fpds_code`, `fpds_org_id`, and the office-level `code` are available as response **leaves**, not filters β€” request them via `?shape=...,fpds_code,fpds_org_id,code`. #### 3. Lookup by fh_key The Federal Hierarchy's `orgKey` (mapped to `fh_key` in Tango) is used for direct lookups: ```bash GET /api/organizations/{fh_key}/ ``` **Note**: Tango uses two identifiers: - `key` (UUID) - The primary key for the Organization model, stable across reloads - `fh_key` (BigInteger) - The Federal Hierarchy's `orgKey` identifier, used for API lookups and cross-referencing with SAM.gov #### 4. Hierarchy Navigation Each organization includes parent relationships and flattened hierarchy paths: ```json { "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "fh_key": 123456, "name": "Federal Emergency Management Agency", "short_name": "FEMA", "parent_fh_key": 789012, "l1_name": "Department of Homeland Security", "l1_short_name": "DHS", "full_parent_path_name": "Department of Homeland Security > Federal Emergency Management Agency" } ``` ### Field Provenance Every organization tracks which source provided each field and when it was last updated: ```json { "field_provenance": { "name": { "source": "federal_hierarchy", "modified_at": "2024-12-01T10:00:00Z" }, "cgac": { "source": "usaspending", "modified_at": "2024-12-01T10:00:00Z" }, "fpds_code": { "source": "usaspending", "modified_at": "2024-12-01T10:00:00Z" }, "code": { "source": "legacy", "modified_at": "2024-12-01T10:00:00Z" } } } ``` This transparency helps us ensure the reliability of each field and make informed decisions about which identifiers to use. ## Practical Examples ### Example 1: Finding an Organization from a Contract Transaction When processing an FPDS contract transaction, you might see: - `agencyID`: `2100` - `departmentID`: `097` In Tango, you can find the organization by department CGAC, by searching for the FPDS code (search picks it up), or by name: ```bash # By CGAC (department-level filter) GET /api/organizations/?cgac=097 # By FPDS code via search (the multi-stage search picks it up via aliases / FTS) GET /api/organizations/?search=2100 # Or search by name if you know it GET /api/organizations/?search=Department of the Army ``` ### Example 2: Finding an Office from USAspending Data USAspending financial assistance data might reference: - `awarding_sub_agency_code`: `1501` - `awarding_office_code`: `15JCRM` You can find the office via search: ```bash GET /api/organizations/?search=15JCRM ``` The response will include the full hierarchy, so you can see it's part of the Department of Justice (CGAC `015`). ### Example 3: Context-Aware Search If you know you're looking for "Treasury OIG" but aren't sure of the exact code: ```bash GET /api/organizations/?search=Treasury OIG ``` Tango's contextual search will find the OIG (Office of Inspector General) within the Treasury Department, even if there are multiple OIGs across different departments. ## Best Practices 1. **Use `key` (UUID) for API references** - The UUID `key` is the primary identifier for storing references to organizations in your application 2. **Use `fh_key` for Federal Hierarchy lookups** - When cross-referencing with SAM.gov or other federal data sources that use the Federal Hierarchy, use `fh_key` 3. **Use code lookups for transaction matching** - When matching transactions, use the specific code type (CGAC, FPDS code, office code) that appears in your data 4. **Leverage search for user-facing features** - The `search` query parameter handles abbreviations, typos, and context better than exact code matching 5. **Check field_provenance for data quality** - Understand which source provided each field to assess reliability ## Conclusion Federal organization data is fragmented across multiple sources, each with its own strengths and gaps. SAM's Federal Hierarchy provides the authoritative structure but lacks operational codes. USAspending fills in many codes but doesn't include FPDS contract identifiers. Tango unifies these sources with a priority-based system that preserves authoritative data while filling in the gaps, giving you a single, reliable way to find and reference federal organizations. Whether you're matching contract transactions, processing financial assistance awards, or building user-facing search features, Tango's unified `Organization` model and flexible search capabilities help you find the right organization identifiers, regardless of which source your data comes from. --- --- description: "How Tango tracks which upstream source last updated each field and row, and why that matters even though provenance isn't exposed directly in the API yet." tags: [provenance, data-quality, reference] updated: 2026-01-25 --- # Provenance & auditing Tango ingests data from multiple upstream systems (SAM.gov, USAspending, FPDS, agency feeds, etc.). Those sources overlap, disagree, and update on different cadences. To keep the dataset consistent (and debuggable), Tango tracks two related concepts: - **Field provenance**: β€œWhich source last updated this specific field, and when?” - **Change logs (CDC)**: β€œWhich fields changed on this row, by what operation (INSERT/UPDATE), and from what source?” Even though we **do not currently expose** provenance or changelog tables in the public API, this tracking matters to API consumers because it helps us: - **Explain behavior**: why a value changed (or why it didn’t). - **Prevent regressions**: avoid overwriting authoritative sources with lower-quality sources. - **Improve reliability**: tighten guarantees around β€œdata is ready / stable” moments for downstream consumers. ## Terminology - **CDC (Change Data Capture)**: a pattern for recording row-level changes (insert/update/delete) as data is ingested. - **`change_source`**: a normalized identifier of the ingest source (e.g. `"sam"`, `"dsbs"`, `"usaspending"`). - **`changed_fields`**: the list of field names that were changed by an operation. - For **UPDATE**, this is a true diff. - For **INSERT**, this is a best-effort list of fields set by the ingest path. - **`batch_id` / `etl_job_id`**: identifiers used to correlate changes to a specific loader run. ## What models have this (so far) Today, Tango tracks provenance/auditing for: - **Organizations** - **Entities** - **Opportunities** ## How it works (high level) At ingest time, Tango typically writes incoming data into a staging representation, computes a diff against the current table, records the audit log, and then applies the update. ```mermaid flowchart LR A[Upstream source file/API] --> B[Loader parses + normalizes] B --> C[(Staging / temp representation)] C --> D[Compute diff vs target] D --> E[(ChangeLog rows)] D --> F[(Field provenance updates)] C --> G[Apply upsert/update to target] ``` ## Why this is useful - **Multiple sources, different trust levels**: provenance lets us define β€œwho wins” per field (and why). - **Better debugging**: we can query β€œwhat changed the name for UEI X?” or β€œwhy did this org’s code change?” - **Future-facing**: this lays groundwork for exposing provenance in a controlled way (e.g. support tooling, exports, or opt-in API surfaces). ## Example questions we can answer - β€œWhat last updated an Organization’s `name` (and from which source)?” - β€œWhat last updated `legal_business_name` for an entity UEI?” - β€œWhich fields changed on organization FH key 12345 in the last sync?” - β€œDid loader X actually change data, or was it a no-op?” --- --- description: "Endpoints, filtering and docket matching for /api/contract_appeals/, Tango's CBCA and ASBCA contract appeal decisions." tags: [contracts, arbitration, api, reference] updated: 2026-09-21 --- # Contract appeals Contract appeals are the decisions of the two boards of contract appeals, exposed at `/api/contract_appeals/`. For field definitions, see the [Contract Appeals Data Dictionary](../data-dictionary/contract-appeals.md). A contract appeal is a dispute **under a contract that already exists**. A contractor and the government disagree over a claim, a termination, delay, or how much is owed; the contracting officer issues a final decision; the contractor appeals it to a board under the Contract Disputes Act. Two boards hear them: - **CBCA** β€” the Civilian Board of Contract Appeals, which hears appeals from most civilian agencies. Coverage runs from **2007** to the present. - **ASBCA** β€” the Armed Services Board of Contract Appeals, which hears appeals from the Department of Defense, NASA and the CIA. Coverage runs from **2010** to the present. About 8,200 decisions are available across the two boards, and the dataset is updated daily. !!! note "Contract appeals are not bid protests" A **bid protest** challenges an award or a solicitation before or just after award β€” who should have won. A **contract appeal** challenges a contracting officer's final decision under a contract already in hand β€” what is owed under it. They are different proceedings, in different forums, usually with different parties, and Tango keeps them in separate resources. Bid protests (GAO, the U.S. Court of Federal Claims, and SBA OHA) live at [`/api/protests/`](protests.md). Nothing appears in both resources. **Authentication**: Contract appeal endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. **Plans**: every endpoint, every filter and the full-text search are available on **every plan, including Free**. One field β€” `decision_text`, the extracted body of the decision β€” requires an **Enterprise** plan. Searching that text is free; reading it is not. See [`decision_text`](#decision_text-the-decision-body). ## Endpoints - `GET /api/contract_appeals/` β€” list, with filtering, search, ordering and pagination - `GET /api/contract_appeals/{uuid}/` β€” one decision The detail path segment is the decision's `uuid`, and it must be a valid RFC 4122 UUID β€” anything else is a 404. The `uuid` is stable: it survives a rebuild of the dataset, so it is safe to store alongside your own records. ## One row is one decision as the board lists it Each board publishes its decisions as a listing, and one row here is one document on that listing. Three consequences are worth knowing before your first query: - **A consolidated appeal carries several dockets.** `docket_numbers` is an array, not a string. One decision resolving four consolidated appeals lists all four. - **A decision the board stops listing is kept, not deleted.** `listed` goes to `false` and the row stays, so a decision you retrieved last month still resolves on its `uuid`. Filter `?listed=true` if you want only what the boards currently publish. - **Not every field is populated on every row, and the gaps follow the boards' own history.** ASBCA's listing gained a docket-number column in 2014, so `docket_numbers` is empty on most ASBCA decisions before then. CBCA's listing gained a decision-type column in 2015, so `decision_type` is null on CBCA decisions before then β€” and it is null on every ASBCA decision, because that board publishes no type at all. ## Filtering Identifier and classification filters accept `|` (or the word `OR`) for OR. Date filters require `YYYY-MM-DD`; invalid dates or inverted ranges return **400** (see [Date filters](shared.md#date-filters)). `search` and `appellant` must be at least 2 characters. | Param | What it does | | --- | --- | | `board` | `cbca` or `asbca`. Case-insensitive. Multi-value: use `\|` for OR. | | `docket` | Exact match on one of the decision's docket numbers β€” see [Matching a docket](#matching-a-docket). Multi-value: use `\|` for OR. | | `appellant` | Case-insensitive substring match on the appellant's name. Min 2 characters. Multi-value: use `\|` for OR. | | `judge` | Case-insensitive exact match on the judge as the board's listing names them. Multi-value: use `\|` for OR. | | `decision_type` | CBCA only: `Decision`, `Dismissal`, `Order`, `Full Board Order`, or the listing's own wording where it matches none of those. Multi-value: use `\|` for OR. | | `decision_date_after`, `decision_date_before` | Decision-date range (`YYYY-MM-DD`). | | `listed` | Boolean. `false` returns decisions the board's newest listing no longer carries. | | `document_id` | Exact match on the board's document identifier. Useful for pinning one document when several listing rows link it. | | `search` | Ranked full-text search over the appellant and the decision text β€” see [Search](#search). Min 2 characters. | An unrecognized query parameter on the list endpoint returns **400** with a did-you-mean suggestion rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page. ### Matching a docket `?docket=` matches **one docket exactly**, against any element of the decision's `docket_numbers` array. Dockets are stored without the board prefix, as the board writes them minus its own name: `59116`, `3288-R`, `7092-C(6682, 6765, 6767)`. You do not have to strip anything yourself β€” a leading `CBCA` or `ASBCA`, and `No.` or `Nos.`, are ignored, so a docket can be pasted straight out of a citation: ```bash GET /api/contract_appeals/?docket=59116 GET /api/contract_appeals/?docket=ASBCA%20No.%2059116 GET /api/contract_appeals/?docket=CBCA%203288-R ``` All three of those are the same query, and suffix letters are matched case-insensitively (`3288-r` finds `3288-R`). Two things this filter is not: - **It is not a prefix or substring search.** `?docket=5911` does not find `59116`. A quantum or remand docket can name its source dockets in parentheses β€” `7092-C(6682, 6765, 6767)` β€” and that whole string is one docket, so quoting `6682` alone does not reach it. - **The comma is not a separator.** Because a docket can contain commas, `|` (or `OR`) is the only way to ask for several: `?docket=59116|59117`. ### Search `?search=` is a ranked full-text query over the **appellant name and the full text of the decision**, and it is available on every plan including Free. Wrap a value in double quotes for a phrase: `?search="differing site conditions"`. Without quotes, the terms are matched individually. Under `search=` with no explicit `ordering`, results come back by relevance. `ordering=rank` asks for that explicitly and requires a non-empty `search` β€” passing it alone returns **400**. **Searching the decision text is free; reading it is not.** A search response tells you *which* decisions matched and carries no fragment of the body, so there is nothing to gate. Reading the body is a separate, Enterprise-only field β€” see [`decision_text`](#decision_text-the-decision-body). Search reaches the decisions whose text we hold. `text_status` and `text_char_count` report, on every plan, whether a given decision has extracted text behind it, so you can tell a decision with no text from one whose text simply did not match. ## Ordering `ordering=` allowlist: - `decision_date` β€” the default is `-decision_date` (newest first) - `appellant` - `first_listed_at` β€” when Tango first observed the decision on a board's listing, which is the field to poll on - `rank` β€” relevance; requires a non-empty `search`, and is the implicit default under one `decision_date` and `appellant` sort empties last in both directions, so a page is never headed by undated rows. Results are tie-broken deterministically, so paging through a large result set never repeats or skips a decision. ## Pagination Standard page-number pagination: - `page` (default 1) - `limit` (default 25, max 100) Responses carry `count / next / previous / results`. ## Shaping Contract appeals are a **flat** resource: every field is a leaf, and there are no expandable relations (so no `*` expansions). See [Response shaping](../guides/patterns/response-shaping.md) for the syntax. - **List default:** `uuid`, `board`, `docket_numbers`, `decision_date`, `appellant`, `judge`, `decision_type`, `url` - **Detail default:** the list fields plus `docket_raw`, `docket_source`, `decision_date_repaired`, `decision_type_raw`, `listing_year`, `first_listed_at`, `listed`, `text_status`, `text_char_count` Every other field β€” `decision_date_raw`, `document_id`, `listing_url` and `decision_text` β€” is available by naming it in `?shape=`. The full list is in the [data dictionary](../data-dictionary/contract-appeals.md#fields). ### `decision_text` β€” the decision body ```bash GET /api/contract_appeals/{uuid}/?shape=uuid,board,docket_numbers,decision_text ``` `decision_text` is the extracted text of the board's own decision document. It requires an **Enterprise** plan, and three rules govern it: - **You have to name it.** It is in neither default shape, because a single decision runs to roughly 100,000 characters β€” twenty-five of them is not a list page. - **Below Enterprise, the request still succeeds.** You get **200** with the rest of your shape intact, the field omitted, and an entry in `meta.upgrade_hints` naming it and the plan that unlocks it. It is not a 403, and the rest of the response is unaffected. - **The field can be null at any plan.** `decision_text` is null until the decision's document has been through text extraction, and on a decision whose document yielded no text at all. `text_status` (`completed`, `empty`, `failed`, or null when not yet attempted) and `text_char_count` tell you which case you are in, on every plan β€” so you can decide whether a body is worth buying before you buy it. A below-Enterprise response to a shape naming `decision_text`: ```json { "count": 1, "meta": { "upgrade_hints": { "message": "Some requested fields were omitted because they require a higher tier subscription.", "fields": [ {"field": "decision_text", "required_tier": "Enterprise A"} ], "upgrade_url": "https://docs.makegov.com/getting-started/pricing/" } }, "results": [ { "uuid": "7a2e4c1b-3d5f-5e8a-9b0c-1d2e3f4a5b6c", "board": "asbca", "docket_numbers": ["63456", "63457"] } ] } ``` Every other field on the resource, including the board's own link to the decision document in `url`, is available on every plan. ## Alerts `contract_appeal` is an alertable query type β€” `alerts.contract_appeal.match`, using the same filters documented above. See the [webhooks guide](../webhooks/index.md). An alert fires when a matching decision first appears and when a matching decision changes. Two changes are worth calling out, because both are real writes rather than query-time derivations: - **A delisting fires.** When a board's newest listing stops carrying a decision, `listed` flips to `false` and subscribers hear about it. - **Newly extracted text fires.** A decision gaining its `decision_text` is a change to the record, so a subscription can be used to follow extraction β€” including on plans that cannot read the text itself. ## Examples ```bash # One ASBCA docket GET /api/contract_appeals/?board=asbca&docket=57530 # Differing-site-conditions decisions since 2024 GET /api/contract_appeals/?search=differing+site+conditions&decision_date_after=2024-01-01 # Construction appellants, newest first GET /api/contract_appeals/?appellant=construction&ordering=-decision_date # CBCA dismissals in a window, timeline payload GET /api/contract_appeals/?board=cbca&decision_type=Dismissal&decision_date_after=2025-01-01&shape=uuid,docket_numbers,appellant,decision_date,url # Everything new since your last poll GET /api/contract_appeals/?ordering=-first_listed_at&shape=uuid,board,docket_numbers,appellant,decision_date,first_listed_at # Decisions the boards no longer list GET /api/contract_appeals/?listed=false&shape=uuid,board,docket_numbers,decision_date # Detail, with the decision body (Enterprise) GET /api/contract_appeals/{uuid}/?shape=uuid,board,docket_numbers,appellant,decision_date,decision_text ``` Notes: - `*` is only valid inside expansions; contract appeals have none, so use explicit field lists. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Filtering, ordering, and pagination for /api/contracts/, Tango's definitive contract award endpoint." tags: [contracts, api, reference] updated: 2026-10-16 --- # Contracts Contracts are awards (FPDS β€œdefinitive contracts”) exposed at `/api/contracts/`. For field definitions, see the [Contracts Data Dictionary](../data-dictionary/contracts.md). ## Endpoints - `GET /api/contracts/` (list + filtering + search + ordering) - `GET /api/contracts/{key}/` (detail) - `GET /api/contracts/{key}/transactions/` (detail transactions) - `GET /api/contracts/{key}/subawards/` (subawards scoped to a contract) Related β€œscoped” list endpoints that behave like `/api/contracts/`: - `GET /api/entities/{uei}/contracts/` - `GET /api/idvs/{key}/awards/` (child awards under an IDV) - `GET /api/vehicles/{uuid}/orders/` (task orders under a vehicle) ## Filtering Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day. ### Text / parties | Param | What it does | | --- | --- | | `search` | Full-text-ish search across contract search vectors (good for keywords). | | `recipient` | Search by recipient/vendor name. | | `uei` | Filter by recipient UEI (exact). | | `piid` | Filter by PIID (case-insensitive). | | `solicitation_identifier` | Filter by solicitation identifier. Matches every spelling of the number (`N6600120R0002` or `N66001-20-R-0002`, any case). Multi-value: use `|` for OR. | ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Filter by awarding agency (code/name/abbrev; best-effort matching). Implemented via organization UUID for performance; response `awarding_office` shape unchanged. | | `funding_agency` | Filter by funding agency (code/name/abbrev; best-effort matching). Implemented via organization UUID for performance; response `funding_office` shape unchanged. | ### Codes / set-asides | Param | What it does | | --- | --- | | `naics` | Filter by NAICS. | | `psc` | Filter by PSC. | | `set_aside` | Filter by set-aside. | | `commercial_item_acquisition_procedures` | Filter by FPDS commercial item acquisition procedures code (`A`–`E`, case-insensitive). Multi-value: use `|` for OR. See [Commercial item acquisition procedures](#commercial-item-acquisition-procedures). | ### Commercial item acquisition procedures `commercial_item_acquisition_procedures` matches the FPDS code recorded on the contract. | Code | Meaning | | --- | --- | | `A` | Commercial Products/Services | | `B` | Products or services pursuant to FAR 12.102(f) | | `C` | Services pursuant to FAR 12.102(g) | | `D` | Commercial Products/Services Procedures not used | | `E` | DoD - Section 803 CSO Procedures | `E` marks awards made through a DoD Section 803 Commercial Solutions Opening (CSO). To list them: ``` GET /api/contracts/?commercial_item_acquisition_procedures=E ``` Codes are case-insensitive, and `A|E` matches either code. An unknown or multi-character value matches nothing rather than returning an error. This filter is not available on [OTAs](otas.md) or [OT IDVs](otidvs.md). ### Dates / fiscal years All date filters require `YYYY-MM-DD` format. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters) for details. | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Fiscal year (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | ### Period of performance | Param | What it does | | --- | --- | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance **current end** date range. | | `expiring_gte`, `expiring_lte` | Ultimate completion date range (useful for β€œexpiring soon”). | ### Dollars / types | Param | What it does | | --- | --- | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | | `award_type` | Award type code. | | `ordering` | Sort results (allowlist: `award_date`, `obligated`, `total_contract_value`; prefix with `-` for descending). | ### Multi-value filter syntax Use `|` (or the literal word `OR`) to match any of several values: ``` naics=541511|541512 ``` The same syntax works on every filter that accepts multiple values. ## Ordering Contracts support `ordering=` with a strict allowlist: - `award_date` - `obligated` - `total_contract_value` Examples: - Newest first: `GET /api/contracts/?ordering=-award_date` - Largest obligations first: `GET /api/contracts/?ordering=-obligated` ## Vehicle linkage Contracts that are part of an IDIQ / GWAC vehicle can opt-in to a curated subset of vehicle fields via `?shape=...,vehicle(*)` (allowed leaves include `vehicle_type`, plus a curated subset of solicitation / vehicle metadata). The full vehicle detail (awardees, opportunity, totals) stays on `/api/vehicles/{uuid}/`. The expansion is not in the default response shape; opt in when needed. ## Pagination High-volume award endpoints use **cursor-based (keyset) pagination**. - Use `limit` to control page size. - Follow the `next` / `previous` URLs in responses. - If you’re constructing requests manually, you’ll typically pass a `cursor` parameter from the `next` URL. ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). ### Search + ordering + shaping === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_contracts( keyword="cloud services", # SDK maps to API param: search awarding_agency="4700", # GSA fiscal_year=2024, sort="award_date", # SDK maps (sort+order) -> API ordering order="desc", limit=10, shape=ShapeConfig.CONTRACTS_MINIMAL, ) for c in resp.results: print(c.piid, c.award_date, c.recipient.display_name) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listContracts({ keyword: "cloud services", // SDK maps to API param: search awarding_agency: "4700", // GSA fiscal_year: 2024, sort: "award_date", // SDK maps (sort+order) -> API ordering order: "desc", limit: 10, shape: ShapeConfig.CONTRACTS_MINIMAL, }); for (const c of resp.results) { console.log(c.piid, c.award_date, c.recipient.display_name); } ``` ### Cursor pagination (using the `next` URL) === "Python (tango-python)" ```python import os from urllib.parse import parse_qs, urlparse from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_contracts(limit=25, sort="award_date", order="desc") print("next:", resp.next) if resp.next: qs = parse_qs(urlparse(resp.next).query) cursor = (qs.get("cursor") or [None])[0] if cursor: resp2 = client.list_contracts(limit=25, cursor=cursor, sort="award_date", order="desc") print("page 2 results:", len(resp2.results)) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listContracts({ limit: 25, sort: "award_date", order: "desc" }); console.log("next:", resp.next); if (resp.next) { const url = new URL(resp.next); const cursor = url.searchParams.get("cursor"); if (cursor) { const resp2 = await client.listContracts({ limit: 25, cursor, sort: "award_date", order: "desc" }); console.log("page 2 results:", resp2.results.length); } } ``` --- --- description: "Filtering, ordering, and pagination for the deprecated /api/departments/ endpoint; new integrations should use Organizations instead." updated: 2026-05-13 --- # Departments !!! warning "Deprecated endpoint" This endpoint is deprecated. Use [Organizations](organizations.md) for the unified federal hierarchy. This endpoint will be removed in a future version. Departments are top-level organizations exposed at `/api/departments/`. If you need the full organization tree + richer search, see [Organizations](organizations.md). For field definitions, see the [Organizations Data Dictionary](../data-dictionary/organizations.md). ## Endpoints - `GET /api/departments/` (list) - `GET /api/departments/{code}/` (detail) ## Filtering None. ## Ordering `/api/departments/` does **not** support `ordering=...`. ## Pagination Departments use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `code`, `name`, `abbreviation`, `description`, `cgac`, `website`, `congressional_justification` - No expansions. Default shape (no `?shape=` param): `code,name,abbreviation` ```bash # Select specific fields /api/departments/?shape=code,name # Extended department info /api/departments/1400/?shape=code,name,description,website,congressional_justification ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The SDKs don’t yet expose a first-class `list_departments()` / `listDepartments()` method. You can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get("/api/departments/", params={"page": 1, "limit": 25}) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/departments/", { page: 1, limit: 25 }); console.log("count:", data.count); ``` --- --- description: "Endpoints, shared filters, and pagination for the DLA DIBBS resources β€” requests for quote, solicitations, and awards." updated: 2026-10-29 --- # DIBBS The DLA Internet Bid Board System (DIBBS) endpoints expose small-purchase requests for quote, larger solicitations (RFP/IFB), and awards from the Defense Logistics Agency. For field definitions, see the [DIBBS Data Dictionary](../data-dictionary/dibbs.md). **Authentication**: DIBBS endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. Available on every plan, including Free β€” no tier gating on any field. ## Endpoints - `GET /api/dibbs/rfqs/` β€” requests for quote (small purchases) - `GET /api/dibbs/rfps/` β€” solicitations (RFP/IFB) - `GET /api/dibbs/awards/` β€” awards (line items) Each resource supports list + filtering + search + ordering, plus a detail lookup by `uuid` (`GET /api/dibbs/{resource}/{uuid}/`). The path segment must be a valid RFC 4122 UUID. DIBBS is an NSN and part-number world, so `nsn`, `fsc`, `part_number`, `solicitation`, and `search` filter every resource. All three carry an `organization(*)` expansion (always the Defense Logistics Agency, resolved to the canonical 7-key office payload). > **Read this before you total awards.** A DIBBS award record is a **line item**, not a whole award. A delivery order covering many items appears as one record per item, and `total_contract_price` is the **order's** total repeated on every one of them. Summing it across records badly overstates spend. To total spend, count each order once. See [Awards](#awards) below. ## Shared filters These apply to all three resources. Identifier filters accept `|` for OR; date filters require `YYYY-MM-DD` (invalid dates or inverted ranges return **400**, see [Date filters](shared.md#date-filters)). | Param | What it does | | --- | --- | | `nsn` | National Stock Number (exact, case-insensitive). Multi-value: use `|` for OR. | | `fsc` | Federal Supply Class: the first four digits of the NSN, e.g. `6515` matches NSN `6515-01-234-5678`. Each value must be exactly four digits; anything else returns **400**. Multi-value: use `|` for OR. | | `part_number` | Manufacturer part number (exact, case-insensitive). Multi-value: use `|` for OR. | | `solicitation` | DLA solicitation number, e.g. `SPE1C126Q0337` (exact, case-insensitive). Multi-value: use `|` for OR. | | `organization` | Filter by the federal-hierarchy key of the buying organization (always DLA). Multi-value: use `|` for OR. | | `search` | Full-text search over nomenclature, NSN, part number, and solicitation number. | The `organization(*)` expansion resolves to the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`) β€” the same object used on awards, opportunities, vehicles, forecasts, grants, and IT Dashboard responses. It is omitted from the default list shape (constant DLA) and included in the default detail shape. ## Pagination All three resources use standard page-number pagination: - `page` (default 1) - `limit` (default 25, max 100) Default ordering is newest-modified first; `uuid` is appended to any client ordering to guarantee a stable total order across pages. `rank` is a valid ordering field on all three but is only meaningful with `?search=`. --- ## RFQs `GET /api/dibbs/rfqs/` β€” small-purchase requests for quote. ### Open RFQs `?open=true` returns the RFQs **still accepting quotes today**, derived from `return_by_date` (a passed or missing date is not open). `?open=false` returns the complement. Every result carries a computed `is_open` boolean regardless of the filter. Because open/closed is derived at query time, an RFQ simply reaching its `return_by_date` is not a change to the record. ### Filtering Shared filters (above), plus: | Param | What it does | | --- | --- | | `open` | Boolean. `true` returns RFQs still accepting quotes today. | | `purchase_request` | Purchase request number (exact, case-insensitive). Multi-value: use `|` for OR. | | `set_aside` | Set-aside flag (`Y` / `N`). Multi-value: use `|` for OR. | | `status_code` | 11-character composite DIBBS status code, e.g. `DLK00L1N000` (exact, case-insensitive). Multi-value: use `|` for OR. | | `quantity_min`, `quantity_max` | Quantity range. | | `return_by_date_after`, `return_by_date_before` | Close-date range (`YYYY-MM-DD`). | | `issue_date_after`, `issue_date_before` | Issue-date range (`YYYY-MM-DD`). | ### Ordering `ordering=` allowlist: `rank`, `return_by_date`, `issue_date`, `quantity`, `modified`. ### Shaping - **List default:** `uuid`, `solicitation`, `purchase_request`, `nsn`, `part_number`, `nomenclature`, `quantity`, `unit_of_issue`, `set_aside`, `status_code`, `return_by_date`, `issue_date`, `is_open`, `document_url` - **Detail default:** the list fields plus `solicitation_formatted` and `organization(*)` --- ## RFPs `GET /api/dibbs/rfps/` β€” solicitations (RFP/IFB). ### Open solicitations `?open=true` returns the solicitations **still accepting offers today**, derived from `closes_date` (a passed or missing date is not open). `?open=false` returns the complement. Every result carries a computed `is_open` boolean. ### Filtering Shared filters (above), plus: | Param | What it does | | --- | --- | | `open` | Boolean. `true` returns solicitations still accepting offers today. | | `buyer_code` | DLA buyer code (exact, case-insensitive). Multi-value: use `|` for OR. | | `issued_date_after`, `issued_date_before` | Issue-date range (`YYYY-MM-DD`). | | `closes_date_after`, `closes_date_before` | Close-date range (`YYYY-MM-DD`). | Solicitations do not carry `quantity`, `set_aside`, `status_code`, or `purchase_request` (those are RFQ-only). ### Ordering `ordering=` allowlist: `rank`, `closes_date`, `issued_date`, `modified`. ### Shaping - **List default:** `uuid`, `solicitation`, `nsn`, `part_number`, `nomenclature`, `buyer_code`, `issued_date`, `closes_date`, `is_open`, `document_url`, `tech_docs_url` - **Detail default:** the list fields plus `organization(*)` --- ## Awards `GET /api/dibbs/awards/` β€” DIBBS awards, **one record per line item**. An award has no open/closed lifecycle, so there is no `open` filter or `is_open` field. The resolved `awardee` entity is included when the awardee's CAGE code matches a registered Tango entity; `awardee_cage` is always present either way. ### The line-item total-price warning `total_contract_price` is the **order's** total, replicated verbatim on every line item of that order. **Never `SUM()` it across records** β€” one real order spanning 483 line items reads $9,000,000.00 on all of them, so a naive total reports $4.35 billion for that one order. To total spend, count each order once (dedupe by `award_number` + `delivery_order_number`). Filtering and ordering by the per-order price is fine; summing is not. `total_contract_price` is null on the ~3.5% of rows whose price cell is non-numeric β€” the raw cell is preserved verbatim in `total_contract_price_text` (e.g. `See Award Doc`). ### Coverage Awards are complete for those DLA posted to DIBBS on or after **2026-06-09**. Before that only a fraction is held, the earliest posted 2026-06-01, so an empty result for an older award number is a coverage gap, not evidence the award does not exist. For those, query the contract by PIID: `GET /api/contracts/?piid=SPE7MC26V3036`. `award_number` holds the award or basic contract. A delivery order's own number (9th character `F`, the PIID FPDS and USAspending report for the order) is in `delivery_order_number`, with its parent contract in `award_number` β€” so filter orders on `delivery_order_number`. ### Filtering Shared `nsn`, `fsc`, `part_number`, `solicitation`, `organization`, `search` (above), plus: | Param | What it does | | --- | --- | | `award_number` | Award or basic contract number β€” for a delivery order, its parent contract (exact, case-insensitive). Multi-value: use `|` for OR. | | `delivery_order_number` | The delivery order's own number (null on basic awards). Multi-value: use `|` for OR. | | `purchase_request` | Purchase request number. Multi-value: use `|` for OR. | | `awardee_cage` | Awardee CAGE code (populated on every award row). Multi-value: use `|` for OR. | | `entity` | UEI of the resolved Tango entity (set only when the CAGE matched a registered entity). Multi-value: use `|` for OR. | | `award_date_after`, `award_date_before` | Award-date range (`YYYY-MM-DD`). | | `posted_date_after`, `posted_date_before` | Posted-date range (`YYYY-MM-DD`). | | `total_contract_price_min`, `total_contract_price_max` | Order price range (per-order, not summable across rows). | ### Ordering `ordering=` allowlist: `rank`, `award_date`, `posted_date`, `total_contract_price`, `modified`. ### Shaping - **List default:** `uuid`, `award_number`, `delivery_order_number`, `delivery_order_counter`, `nsn`, `part_number`, `purchase_request`, `nomenclature`, `awardee_cage`, `total_contract_price`, `total_contract_price_text`, `award_date`, `posted_date`, `last_mod_posting_date`, `solicitation`, plus `awardee(uei,cage_code,legal_business_name)` - **Detail default:** the list fields plus `awardee(*)` and `organization(*)` The `awardee(*)` expansion resolves to `uei`, `cage_code`, `legal_business_name` from the linked entity (null when the CAGE is unresolved). --- ## Examples ```bash # Open RFQs for a stock number GET /api/dibbs/rfqs/?open=true&nsn=5310-00-123-4567&shape=uuid,nsn,nomenclature,quantity,return_by_date,is_open # Open RFQs in two Federal Supply Classes GET /api/dibbs/rfqs/?open=true&fsc=6515|6530&shape=uuid,nsn,nomenclature,return_by_date # Solicitations closing in a window GET /api/dibbs/rfps/?closes_date_after=2026-08-01&closes_date_before=2026-08-31&shape=uuid,solicitation,nsn,closes_date,is_open # Awards to one vendor by UEI (remember: line items, not orders) GET /api/dibbs/awards/?entity=ABC123DEF456&shape=uuid,award_number,delivery_order_number,total_contract_price,award_date,awardee(*) # Detail by uuid GET /api/dibbs/awards/550e8400-e29b-41d4-a716-446655440000/?shape=uuid,award_number,total_contract_price,awardee(*),organization(*) ``` Notes: - `*` is only valid inside expansions. Use explicit field lists at the root. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Endpoints, access, filtering and attachment downloads for /api/ebuy/requests/, GSA eBuy requests scoped to your own Schedule contracts." tags: [gsa, api, reference] updated: 2026-11-10 --- # eBuy GSA eBuy requests β€” the RFQs, RFPs and RFIs agencies post to GSA Schedule holders β€” are exposed at `/api/ebuy/requests/`. For field definitions, see the [eBuy Data Dictionary](../data-dictionary/ebuy.md). !!! note "eBuy is scoped to your own contracts" eBuy is not public data. GSA shows a Schedule holder only the requests posted under the SINs on that holder's own contracts, and Tango keeps the same boundary: **you see a request only while your account is linked to a contract it was posted under.** Access needs **two things**: a **Medium plan or above**, and a **contract link** that MakeGov sets up for your account. [Reach out](mailto:hello@makegov.com) to get started. [`/api/ebuy/access/`](#checking-your-access) tells you which of the two you have. **Authentication**: eBuy endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. **Plans**: Medium and above. On a Free or Small plan, `/api/ebuy/requests/` and every route under it return HTTP 403 β€” see [Below Medium](#below-medium). ## Endpoints - `GET /api/ebuy/access/` β€” whether eBuy is enabled for your account, and through which contracts - `GET /api/ebuy/requests/` β€” list, with filtering, search, ordering and pagination - `GET /api/ebuy/requests/{rfq_id}/` β€” one request, with its attachments - `GET /api/ebuy/requests/{rfq_id}/attachments/{doc_seq_num}/download/` β€” download one attachment The detail path segment is the eBuy request id, e.g. `RFQ1835158`. ## Checking your access On a Medium plan or above without a contract link, `/api/ebuy/requests/` returns an **empty list** β€” the same answer as a search with no matches. `GET /api/ebuy/access/` tells the two apart: ```json { "enabled": false, "reason": "no_contract_grant", "contracts": [] } ``` | Field | Meaning | | --- | --- | | `enabled` | `true` when your plan is Medium or above **and** your account has at least one active contract link. | | `reason` | Why `enabled` is `false`: `tier_required` (your plan is below Medium) or `no_contract_grant` (no contract link yet). `tier_required` wins when both apply. `null` when enabled. | | `contracts` | The GSA Schedule contract numbers linked to your account, sorted. Only ever your own. | `/api/ebuy/access/` answers on every plan, so a Free or Small account gets `200` with `"reason": "tier_required"` rather than an error. ### Below Medium On a Free or Small plan, the list, detail, and download routes refuse with **HTTP 403** β€” not an empty list β€” whether or not your account has a contract link: ```json { "error": "This endpoint requires Medium tier or above. Your current tier is Small.", "code": "tier_required", "required_tier": "Medium", "current_tier": "Small", "upgrade_url": "https://docs.makegov.com/getting-started/pricing/" } ``` Upgrade from the [pricing page](https://tango.dev/subscriptions/pricing/); see [Plans & pricing](../getting-started/pricing.md). ## What you can see - **A request outside your contracts does not exist, as far as the API is concerned.** It is absent from the list, and its detail URL returns **404** β€” the same answer as an id that was never issued. Nothing in a response tells you that a request exists under someone else's contract. - **Access follows the link, not the moment you fetched.** Every call re-checks your contract links. If a link is removed, the requests behind it disappear from the list and their detail and download URLs start returning 404. - **No response names which contract a request was posted under.** `?contract_number=` narrows to one of your own contracts, but the contract is never a field on the request. A contract can be linked to you directly or to your team. Your access is the union of the two, so everyone on a team sees the requests under the team's linked contracts. ## `status` is frozen `status` is stored exactly as eBuy supplied it β€” `Open` or `Cancelled` β€” and is **never recomputed**. eBuy's feed carries only the requests that are currently active. A request that closes simply stops appearing; it never arrives with a final closed status. So **an `Open` request may have closed months ago.** - Read **`last_seen`** β€” when Tango last observed the request in eBuy β€” to judge whether it is still live. A request seen this week is current; one last seen in the spring is not, whatever its `status` says. - `close_date` is the buyer's stated deadline, and `?close_date_after=` is the practical way to ask for requests that have not yet closed. - There is deliberately no `is_open` flag and no `?open=` filter: a flag derived from the clock would call a months-dead request open. ## Filtering Most filters accept `|` (or the word `OR`) for OR, and match case-insensitively. Date filters require `YYYY-MM-DD`; invalid dates or inverted ranges return **400** (see [Date filters](shared.md#date-filters)). The `_before` date filters include the whole of that day. | Param | What it does | | --- | --- | | `search` | Ranked full-text search β€” see [Search](#search). Multi-value: use `\|` for OR. | | `rfq_id` | Exact match on the eBuy request id, e.g. `RFQ1835158`. Multi-value: use `\|` for OR. | | `reference_number` | The buying office's own solicitation or reference number. Matches every spelling variant, dashed and undashed. Multi-value: use `\|` for OR. | | `request_type` | `RFQ`, `RFP` or `RFI`. Multi-value: use `\|` for OR. | | `status` | `Open` or `Cancelled` β€” as supplied, and [frozen](#status-is-frozen). Multi-value: use `\|` for OR. | | `sin` | The Special Item Number the request was posted under, e.g. `54151S`. Multi-value: use `\|` for OR. | | `schedule` | The GSA schedule the request was posted under. Multi-value: use `\|` for OR. | | `buyer_agency` | The buying department's name as eBuy gives it. Multi-value: use `\|` for OR. | | `agency` | Agency, resolved to the buyer's organization and rolled up its hierarchy, so a department includes the sub-agencies and offices beneath it. Matches by name, abbreviation or code (CGAC, FPDS, organization key or AAC), e.g. `?agency=GSA`. Multi-value: use `\|` for OR. A value that resolves to no organization falls back to an exact match on `buyer_agency` and never returns **400**. `buyer_agency` alone is the department name as eBuy gives it, with no roll-up. | | `contract_number` | Narrow to the requests under one or more of **your own** linked contracts. A contract your account is not linked to returns nothing, not an error. Multi-value: use `\|` for OR. | | `issue_date_after`, `issue_date_before` | Issue-date range (`YYYY-MM-DD`). | | `close_date_after`, `close_date_before` | Close-date range (`YYYY-MM-DD`). | ### Search `?search=` is a ranked full-text query over each request's **title, description, reference number and request id, and the extracted text of its attachments** β€” statements of work, pricing schedules and the like. A match on the request itself **always ranks above** a match that is only in an attachment. Attachment text is long, repetitive contracting boilerplate, so a hit there is a weaker signal than a hit in what the buyer wrote; an attachment-only match is still returned, just after every direct match. Under `search=` with no explicit `ordering`, results come back by relevance. An explicit `ordering` overrides it. ## Ordering `ordering=` allowlist: - `issue_date` β€” the default is `-issue_date` (newest first) - `close_date` - `last_seen` - `modified` Results are tie-broken deterministically, so paging through a large result set never repeats or skips a request. **Sorting descending on `close_date` puts requests without a close date first.** Pair it with `close_date_after`, which excludes them. ## Pagination Standard page-number pagination: - `page` (default 1) - `limit` (default 25, max 100) Responses carry `count / next / previous / results`. ## Rate limits eBuy endpoints β€” list, detail and attachment downloads β€” count against your account's standard daily and per-minute [rate limits](../guides/patterns/rate-limits.md), like every other endpoint. ## Shaping See [Response shaping](../guides/patterns/response-shaping.md) for the syntax. - **List default:** `rfq_id`, `request_type`, `title`, `schedule`, `sin`, `status`, `buyer_name`, `buyer_agency`, `buyer_agency_code`, `reference_number`, `issue_date`, `close_date`, `attachment_count`, `link_count`, `last_seen` - **Detail default:** every field, plus `organization(*)` and `attachments(*)` Two expansions are available: - **`organization(*)`** β€” the buying office resolved to the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`), the same object used on awards and opportunities. Best-effort: some buyers eBuy lists are not federal agencies (the judiciary, Congress, state and local governments), and those resolve to `null`. - **`attachments(*)`** β€” `doc_seq_num`, `doc_name`, `doc_type`, `doc_path`, `is_link`, `doc_session_date`. - **`attachments(extracted_text)`** β€” the text extracted from each document. It must be named: `attachments(*)` and the detail default do not include it. See [Attachment text](#attachment-text). `description` is long-form and is in the detail default only; name it in `?shape=` to get it on a list. ## Attachments ```bash GET /api/ebuy/requests/RFQ1835158/attachments/3/download/ ``` A request's `attachments` include both **documents** and **links**, told apart by `is_link`: - **A document** (`is_link: false`) downloads through the endpoint above, addressed by its `doc_seq_num`. The response is a **redirect** to a download URL that **expires after five minutes** β€” fetch it right away, and request a new one rather than storing it. - **A link** (`is_link: true`) is an outbound URL with no file behind it; `doc_path` is the URL. The download endpoint returns **400** for a link, with the URL in the response body. A download returns **404** when the document has not been captured yet, and β€” like every eBuy route β€” when the request is outside your contracts. ### Attachment text ```bash GET /api/ebuy/requests/RFQ1835158/?shape=rfq_id,title,attachments(doc_seq_num,doc_name,extracted_text) ``` `extracted_text` is the text extracted from a document β€” the same text `?search=` matches β€” so you can read a statement of work or pricing schedule without downloading the file. - **Name it to get it.** It is not in the detail default and `attachments(*)` does not include it, because a document's text can be long. - **It works on the list too.** Name it in `?shape=` on `/api/ebuy/requests/` to get the text for every request on the page. - **A missing key means there is no text.** A link, a scanned document with no readable text, or a document not yet processed omits `extracted_text` rather than returning `null`. `attachment_count` counts every document ever observed on a request, including ones an amendment later removed from eBuy's own page, so it can exceed what eBuy currently shows. ## Alerts `ebuy_request` is an alertable query type β€” `alerts.ebuy_request.match`, using the same filters documented above. See the [webhooks guide](../webhooks/index.md). - **An alert only ever matches requests under your own contracts.** Matching uses the contract links of the account that owns the webhook endpoint, re-read on every evaluation, so a removed link stops alerts on the next run. - **An alert fires when a matching request appears or changes.** A request **closing does not fire**, because a closed request simply stops appearing β€” see [`status` is frozen](#status-is-frozen). ## Examples ```bash # Is eBuy enabled for this key? GET /api/ebuy/access/ # Open requests under one SIN GET /api/ebuy/requests/?status=Open&sin=54151S # Still-open requests closing in the next month GET /api/ebuy/requests/?close_date_after=2026-10-01&close_date_before=2026-10-31&ordering=close_date # Search titles, descriptions and attachment text GET /api/ebuy/requests/?search=cybersecurity%20assessment # Look a request up by the buyer's own number GET /api/ebuy/requests/?reference_number=W912DY-26-Q-0012 # Only one of your own contracts GET /api/ebuy/requests/?contract_number=47QTCA26D0001 # Detail with the buying office and attachments GET /api/ebuy/requests/RFQ1835158/?shape=rfq_id,title,close_date,organization(*),attachments(doc_seq_num,doc_name,is_link) # Detail with each document's text GET /api/ebuy/requests/RFQ1835158/?shape=rfq_id,title,attachments(doc_seq_num,doc_name,extracted_text) ``` Notes: - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Filtering, response shaping, and pagination for /api/entities/, Tango's vendor and recipient endpoint." tags: [entities, api, reference] updated: 2026-10-27 --- # Entities Entities are vendors/recipients exposed at `/api/entities/` (UEI is canonical). For field definitions, see the [Entities Data Dictionary](../data-dictionary/entities.md). Entities are SAM.gov registrants. Most financial-assistance recipients never register, so they aren't entities; each has a shared, entity-shaped recipient record instead, returned as `recipient(...)` on [financial-assistance awards](assistance.md). A recipient with a UEI carries the same UUID as its entity, and the assistance `uei` filter finds its awards. See [Recipients](assistance.md#recipients). ## Endpoints - `GET /api/entities/` (list + filtering + search) - `GET /api/entities/{uei}/` (detail; UEI lookup is case-insensitive) Related β€œscoped” list endpoints (awards for an entity): - `GET /api/entities/{uei}/contracts/` - `GET /api/entities/{uei}/idvs/` - `GET /api/entities/{uei}/otas/` - `GET /api/entities/{uei}/otidvs/` - `GET /api/entities/{uei}/subawards/` **Metrics:** Time-series obligation/award metrics for an entity: `GET /api/entities/{uei}/metrics///`. See [Metrics](metrics.md) for parameters and behavior. **Budget flows (Beta):** Federal accounts that paid this vendor, with surrounding account context and hydrated contracts: `GET /api/entities/{uei}/budget-flows/`. See [Budget](budget.md#entity-budget-flows). ## Response Shaping Entities default to the shaping pipeline β€” all responses go through shaping even without `?shape=`. Use `?shape=` to customize which fields are returned. - **List default:** `uei`, `legal_business_name`, `dba_name`, `entity_url`, `cage_code`, `business_types(*)`, `sba_business_types(*)`, `primary_naics`, `physical_address(*)`, `purpose_of_registration(*)`, `relationships(*)` - **Detail default:** All list fields plus `display_name`, `uuid`, `dodaac`, `description`, `email_address`, `capabilities`, `congressional_district`, `keywords`, `registered`, `registration_status`, `federal_obligations(*)`, `naics_codes(*)`, `psc_codes`, `highest_owner(*)`, `immediate_owner(*)`, `mailing_address(*)`, all date fields, and structured code/description expands: `entity_structure(*)`, `entity_type(*)`, `profit_structure(*)`, `organization_structure(*)`, `state_of_incorporation(*)`, `country_of_incorporation(*)`. - **On-demand expand:** `past_performance(*)` β€” aggregated contract history with `summary` and `top_agencies`. Accepts `[top=N]` bracket param (default 5, max 100). Example: `?shape=uei,past_performance[top=10](*)`. Complex fields are **normalized** by the shaping pipeline: address keys are always snake_case (address normalization now includes `county`, `county_code`, `fips_code` when available from DSBS), `business_types` and `sba_business_types` are always `[{code, description, ...}]` arrays, `naics_codes` are always `[{code, sba_small_business}]` objects, and code/description pairs (entity_structure, purpose_of_registration, etc.) are always `{code, description}` objects with map-based description fallback. See [Response Shaping](../guides/patterns/response-shaping.md) for full syntax and the [Entities Data Dictionary](../data-dictionary/entities.md) for field definitions. ## Filtering Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day. ### Identity / text search | Param | What it does | | --- | --- | | `search` | Search entities (name + aliases + other indexed fields). | | `uei` | Filter by UEI (exact, case-insensitive). | | `cage_code` | Filter by CAGE code (exact, case-insensitive). | | `name` | Filter by legal business name (substring match). | ### Location | Param | What it does | | --- | --- | | `state` | Filter by entity physical address state/province code. | | `zip_code` | Filter by ZIP code (exact). | ### Classification | Param | What it does | | --- | --- | | `naics` | Filter by NAICS. | | `psc` | Filter by PSC. | | `socioeconomic` | Filter by business type / socioeconomic code. | ### Other | Param | What it does | | --- | --- | | `purpose_of_registration_code` | Filter by purpose-of-registration code (when present). | | `total_awards_obligated_gte` | Filter entities with total obligated amount greater than or equal to a USD value. | | `total_awards_obligated_lte` | Filter entities with total obligated amount less than or equal to a USD value. | ### Multi-value filter syntax Use `|` (or the literal word `OR`) to match any of several values: ``` socioeconomic=8A|WOSB ``` The same syntax works on every filter that accepts multiple values. ## Ordering `/api/entities/` does **not** currently support `ordering=...`. If you send `?ordering=...` anyway, Tango returns **HTTP 400** (ordering is opt-in per endpoint). ## Pagination Entities use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). ### List entities (search + filters + shaping) === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_entities( search="acme", state="VA", naics="541511", limit=10, shape=ShapeConfig.ENTITIES_MINIMAL, ) for e in resp.results: print(e.uei, e.legal_business_name) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listEntities({ search: "acme", state: "VA", naics: "541511", limit: 10, shape: ShapeConfig.ENTITIES_MINIMAL, }); for (const e of resp.results) { console.log(e.uei, e.legal_business_name); } ``` ### Get an entity (detail) === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) entity = client.get_entity( "ZQGGHJH74DW7", shape=ShapeConfig.ENTITIES_COMPREHENSIVE, ) print(entity.uei, entity.legal_business_name) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const entity = await client.getEntity("ZQGGHJH74DW7", { shape: ShapeConfig.ENTITIES_COMPREHENSIVE, }); console.log(entity.uei, entity.legal_business_name); ``` --- --- description: "Endpoints and filtering for /api/exclusions/, and how SAM.gov debarment and suspension currency is derived at query time." tags: [exclusions, api, reference] updated: 2026-07-19 --- # Exclusions Exclusions are SAM.gov exclusion records β€” debarments, suspensions, and other exclusions from federal awards β€” exposed at `/api/exclusions/`. For field definitions, see the [Exclusions Data Dictionary](../data-dictionary/exclusions.md). **Authentication**: Exclusions endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. Available on every plan, including Free β€” no tier gating on any field. ## Endpoints - `GET /api/exclusions/` (list + filtering + search + ordering) - `GET /api/exclusions/{exclusion_key}/` (detail) The detail path segment is the `exclusion_key` β€” a 64-character SHA-256 hex digest that is the record's primary key. Any other shape returns HTTP 404. ## Currency: who is excluded *today* Whether an exclusion is in force is derived at query time from its dates, not stored as a flag: - `?active=true` returns the exclusions **in force today**. `?active=false` returns the complement (expired, not-yet-active, or lifted). Omitting `active` returns everything. - Every result carries a computed `is_currently_excluded` boolean regardless of the filter. - An exclusion is current when it has **not** been lifted (`delisted_at` is null), its `activate_date` is null or on/before today, and its `termination_date` is null or after today. A null `activate_date` counts as current (fails closed for OFAC/SDN-style records). - `termination_date` of year **2227** is SAM.gov's INDEFINITE sentinel, stored as a real date β€” such records read as current until explicitly lifted. Because currency is derived, an exclusion merely reaching its `termination_date` is not a change to the record β€” see [Webhooks](../webhooks/index.md) for what does and does not fire an alert. ## Filtering Core filters (identifier and classification filters accept `|` for OR; date filters require `YYYY-MM-DD` format β€” invalid dates or inverted ranges return **400**, see [Date filters](shared.md#date-filters)): | Param | What it does | | --- | --- | | `active` | Boolean. `true` returns exclusions in force today; `false` returns the complement. | | `classification_type` | Classification (e.g. `Firm`, `Individual`, `Special Entity Designation`). Multi-value: use `|` for OR. | | `exclusion_type` | Exclusion type (e.g. `Ineligible (Proceedings Pending)`, `Prohibition/Restriction`). Multi-value: use `|` for OR. | | `exclusion_program` | Exclusion program (e.g. `Reciprocal`, `Non-Procurement`, `Procurement`). Multi-value: use `|` for OR. | | `agency` | Agency, resolved to an organization and rolled up its hierarchy, so a department includes exclusions its components issued (`?agency=TREAS` includes the Treasury offices'). Multi-value: separate values with a pipe for OR. A value that resolves to no organization falls back to a case-insensitive exact match on `excluding_agency_code`, with a warning in `meta`. | | `excluding_agency_code` | Code of the agency that created the exclusion, matched exactly with no hierarchy rollup. Multi-value: separate values with a pipe for OR. | | `excluding_agency_name` | Name of the excluding agency. Multi-value: use `|` for OR. | | `uei` | SAM.gov Unique Entity Identifier on the exclusion record. Multi-value: use `|` for OR. | | `cage_code` | CAGE code on the exclusion record. Multi-value: use `|` for OR. | | `npi` | National Provider Identifier. Multi-value: use `|` for OR. | | `entity_uei` | UEI of the resolved Tango entity (set when the exclusion links to a registered entity). Multi-value: use `|` for OR. | | `delisted` | Boolean. `true` returns only lifted exclusions (`delisted_at` is set); `false` returns those still in the catalog. | | `activate_date_after`, `activate_date_before` | Activation date range (`YYYY-MM-DD`). | | `termination_date_after`, `termination_date_before` | Termination date range (`YYYY-MM-DD`). | | `update_date_after`, `update_date_before` | SAM update-date range (`YYYY-MM-DD`). | | `search` | Full-text search over names, excluding agency, and comments. | ## Ordering Exclusions support `ordering=` with a strict allowlist: - `activate_date` - `termination_date` - `create_date` - `update_date` - `modified` - `rank` β€” relevance; meaningful only when `?search=` is present (results default to relevance order under search) Examples: - Most recently updated first: `GET /api/exclusions/?ordering=-update_date` - Soonest to terminate: `GET /api/exclusions/?ordering=termination_date` ## Pagination Exclusions use standard page-number pagination: - `page` (default 1) - `limit` (default 25, max 100) ## Shaping Exclusions default to the shaping pipeline β€” all responses render through shaping even without `?shape=`. There is one expandable relation, `organization(*)`, and neither default includes it: ask for it by name. - **List default:** `exclusion_key`, `classification_type`, `exclusion_type`, `excluding_agency_name`, `entity_name`, `display_name`, `activate_date`, `termination_date`, `termination_type`, `is_currently_excluded` - **Detail default:** every allowed field, including identifiers, name parts, addresses, free text, the vessel block, provenance dates, and `organization_id`. Expandable relation: - `organization(*)` β†’ the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`) for the excluding agency, resolved from `excluding_agency_code` (or `excluding_agency_name` when there is no code) at the most specific level the code names β€” an exclusion SAM files under a Treasury office links to that office, not to the department. `null` when it doesn't resolve. The API field `references` maps to the underlying `exclusion_references` payload. See the [Exclusions Data Dictionary](../data-dictionary/exclusions.md) for the full field list and [Response Shaping](../guides/patterns/response-shaping.md) for syntax. Examples: ```bash # Firms currently excluded, timeline fields GET /api/exclusions/?active=true&classification_type=Firm&shape=exclusion_key,entity_name,exclusion_type,activate_date,termination_date # By UEI, minimal payload GET /api/exclusions/?uei=ABC123DEF456&shape=exclusion_key,entity_name,is_currently_excluded # Recently lifted exclusions GET /api/exclusions/?delisted=true&ordering=-update_date&shape=exclusion_key,entity_name,delisted_at # Detail by exclusion_key GET /api/exclusions/{exclusion_key}/?shape=exclusion_key,entity_name,exclusion_type,references ``` Notes: - `*` is only valid inside expansions; exclusions have none, so use explicit field lists. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Endpoints, filtering, CFR citation matching and full-text search for /api/federal_register/, Tango's Federal Register documents from 1994 onward." tags: [federal-register, api, reference] updated: 2026-10-06 --- # Federal Register Federal Register documents β€” every rule, proposed rule, notice and presidential document published since 1994 β€” are exposed at `/api/federal_register/`. For field definitions, see the [Federal Register Data Dictionary](../data-dictionary/federal-register.md). About 1.01 million documents are available, from January 1994 to the present, and the dataset is updated daily. **Authentication**: Federal Register endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. **Plans**: every endpoint, every filter and every field β€” including a document's `full_text` β€” is available on **every plan, including Free**. ## Endpoints - `GET /api/federal_register/` β€” list, with filtering, search, ordering and pagination - `GET /api/federal_register/{uuid}/` β€” one document The detail path segment is the document's `uuid`, and it must be a valid RFC 4122 UUID β€” anything else is a 404. The `uuid` is derived from the document number and publication date rather than assigned, so it survives a rebuild of the dataset and is safe to store alongside your own records. ## One row is one published document Each row is one document as the Federal Register published it, identified by its **document number and publication date together**. Three consequences are worth knowing before your first query: - **A document number is not unique on its own.** The Federal Register reused document numbers across genuinely different documents, as late as 2015 β€” `94-1021` is both a trademark-fee rule and a National Library of Medicine meeting notice. `?document_number=` therefore can return more than one document; add a publication-date filter, or read `publication_date` on each result, to tell them apart. - **A correction is its own document.** Corrections are published as separate documents with their own numbers (`R1-`, `C1-`, and older `X`, `Z` and `E` prefixes). `correction_of` on the correction and `corrections` on the original carry the link; the two are never merged into one row. - **`type` undercounts 1994.** About 32,600 documents carry `Uncategorized Document`, and nearly all of them are from 1994, where it covers 92% of the year. `?type=Rule` therefore misses most 1994 rules; use `search`, a CFR citation or an agency filter to reach them. The `agencies`, `cfr_references`, `dockets` and `topics` fields are the Federal Register's own structures, served as it publishes them. In particular, the `agencies` field carries the Federal Register's agency records, not Tango [organizations](organizations.md). To filter by the agency code or name you already have from an award or opportunity, use `agency` β€” see [Filtering by agency](#filtering-by-agency). ## Filtering Identifier and classification filters accept `|` (or the word `OR`) for OR. Date filters require `YYYY-MM-DD`; invalid dates or inverted ranges return **400** (see [Date filters](shared.md#date-filters)). `search` must be at least 2 characters. | Param | What it does | | --- | --- | | `search` | Ranked full-text search over the document's title, abstract and action β€” see [Search](#search). Min 2 characters. | | `document_number` | Exact match on the Federal Register document number, e.g. `2016-31922`. Multi-value: use `\|` for OR, up to 500 values. | | `publication_date_after`, `publication_date_before` | Publication-date range (`YYYY-MM-DD`). | | `effective_on_after`, `effective_on_before` | Effective-date range (`YYYY-MM-DD`). | | `comments_close_on_after`, `comments_close_on_before` | Comment-deadline range (`YYYY-MM-DD`). | | `comments_open` | Boolean β€” see [Open comment periods](#open-comment-periods). | | `cfr_title` | A CFR title number, e.g. `40`. Matches documents citing any part of that title. | | `cfr_part` | A CFR part number, e.g. `52`. Requires `cfr_title` β€” see [Matching a CFR citation](#matching-a-cfr-citation). | | `agency` | A federal agency or department by name, abbreviation, CGAC or FPDS code, or organization key, e.g. `VA`, `3600` or `HHS`. A department includes its sub-agencies. Multi-value: use `\|` for OR. See [Filtering by agency](#filtering-by-agency). | | `fr_agency` | The Federal Register's agency slug, e.g. `environmental-protection-agency`. Case-insensitive. Multi-value: use `\|` for OR. | | `type` | `Rule`, `Proposed Rule`, `Notice`, `Presidential Document`, `Correction`, `Sunshine Act Document` or `Uncategorized Document`. Case-insensitive; any other value returns **400**. Multi-value: use `\|` for OR. | | `significant` | Boolean. Documents designated significant under Executive Order 12866. Most documents carry no designation either way, so `false` returns only documents explicitly marked not significant. | | `rin` | A Regulation Identifier Number, e.g. `2060-AV16`. Case-insensitive. Multi-value: use `\|` for OR. | | `executive_order_number` | Exact match on an executive order number. | An unrecognized query parameter on the list endpoint returns **400** with a did-you-mean suggestion rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page. ### Filtering by agency There are two agency filters, and they answer different questions. `agency` takes the identifier you already hold from the rest of Tango: an abbreviation (`VA`), a name (`Veterans Affairs`), a CGAC code (`036`), an FPDS agency code (`3600`) or an organization key. It resolves through the same federal hierarchy as `agency` on awards and opportunities, so the code on a SAM.gov opportunity works here unchanged, and a department includes its sub-agencies (`HHS` includes NIH and FDA). A document matches when any agency it lists falls inside that organization. ```bash # Everything the VA has published, using the FPDS code from an award or opportunity GET /api/federal_register/?agency=3600 # VA acquisition-regulation rulemakings (48 CFR) GET /api/federal_register/?agency=VA&cfr_title=48 ``` `fr_agency` takes the Federal Register's own slug (`veterans-affairs-department`) and matches it exactly, with no roll-up. The response's `meta.resolved_filters.agency` reports which organization each value matched. Names are matched loosely, so read it whenever you pass a name instead of a code. Two cases are worth checking it for: - **A value that matches no organization** is rejected with a **400** when every value misses; when only some miss, the rest still apply and the misses are listed in `meta.warnings`. - **A value that resolves to an organization with no Federal Register agency mapped into it** returns an empty list with a `meta.warnings` entry saying so. This happens when the value lands on a single office below the level the Federal Register names; pass the department or agency instead. Agencies that no longer exist and have no current organization are reachable only through `fr_agency`. ### Matching a CFR citation `cfr_title` and `cfr_part` match against the document's `cfr_references` β€” the parts of the Code of Federal Regulations the document amends or affects. ```bash GET /api/federal_register/?cfr_title=40 GET /api/federal_register/?cfr_title=40&cfr_part=52 ``` - **`cfr_title` alone** finds every document that cites any part of that title. - **`cfr_title` with `cfr_part`** finds documents with **one** reference to that exact title and part β€” `cfr_title=40&cfr_part=52` is 40 CFR Part 52. A document citing 40 CFR 60 and 49 CFR 52 does not match. - **`cfr_part` without `cfr_title`** returns **400**: a part number means nothing outside its title. - `cfr_title` must be a number; anything else returns **400**. ### Open comment periods `?comments_open=true` returns documents whose comment period closes **today or later**. `?comments_open=false` returns documents whose comment period has already closed. Documents with no comment deadline match **neither** β€” `false` is the closed set, not everything that is not open. Most notices and final rules carry no deadline, so `?comments_open=false` is far smaller than the resource. "Today" is evaluated when you make the request, so the same query returns fewer documents tomorrow. For a fixed window, use `comments_close_on_after` and `comments_close_on_before` instead. ### Search `?search=` is a ranked full-text query over each document's **title, abstract and action**. Wrap a value in double quotes for a phrase: `?search="regional haze"`. Without quotes, the terms are matched individually. **Search does not reach the body of the document.** `full_text` is served, but it is not searched; a term that appears only in a document's body will not match. Pair `search` with a CFR, agency or RIN filter to narrow by subject instead. Under `search=` with no explicit `ordering`, results come back by relevance. `ordering=rank` asks for that explicitly and requires a non-empty `search` β€” passing it alone returns **400**. ## Ordering `ordering=` allowlist: - `publication_date` β€” the default is `-publication_date` (newest first) - `effective_on` - `comments_close_on` - `document_number` - `rank` β€” relevance; requires a non-empty `search`, and is the implicit default under one Results are tie-broken deterministically, so paging through a large result set never repeats or skips a document. **Sorting descending on `effective_on` or `comments_close_on` puts documents without that date first.** Most documents have neither date, so `?ordering=-comments_close_on` alone opens on undated notices. Pair it with the matching range filter, which excludes them: `?comments_close_on_after=2026-01-01&ordering=-comments_close_on`. ## Pagination Standard page-number pagination: - `page` (default 1) - `limit` (default 10, max 100) Responses carry `count / next / previous / results`. ## Shaping Federal Register documents are a **flat** resource: every field is a leaf, and there are no expandable relations (so no `*` expansions). See [Response shaping](../guides/patterns/response-shaping.md) for the syntax. - **List default:** `uuid`, `document_number`, `publication_date`, `type`, `subtype`, `title`, `abstract`, `action`, `agencies`, `cfr_references`, `citation`, `significant`, `comments_close_on`, `effective_on`, `html_url`, `pdf_url` - **Detail default:** the list fields plus `dates`, `signing_date`, `start_page`, `end_page`, `volume`, `docket_ids`, `dockets`, `regulation_id_numbers`, `topics`, `correction_of`, `corrections`, `executive_order_number`, `presidential_document_number`, `proclamation_number`, `comment_url`, `regulations_dot_gov_url`, `raw_text_url`, `body_html_url` Every other field β€” `page_length`, `toc_doc`, `toc_subject`, `disposition_notes`, `executive_order_notes`, `not_received_for_publication`, `public_inspection_pdf_url`, `regulation_id_number_info`, `regulations_dot_gov_info` and, on the detail endpoint only, `full_text` β€” is available by naming it in `?shape=`. The full list is in the [data dictionary](../data-dictionary/federal-register.md#fields). ### `full_text` β€” the document body ```bash GET /api/federal_register/{uuid}/?shape=uuid,document_number,title,full_text ``` `full_text` is the plain-text body of the document, populated for nearly every document in every year from 1994 on. It is available on every plan, and it is **detail only, and only when named**: it is in neither default shape, and a list request naming it in `shape` returns **400**. A single document can run to several megabytes, so a list page never carries it β€” find documents on the list endpoint, then fetch each body by `uuid`. ## Alerts `federal_register` is an alertable query type β€” `alerts.federal_register.match`, using the same filters documented above. See the [webhooks guide](../webhooks/index.md). An alert fires when a matching document is first published and when a matching document changes. The Federal Register commonly fills in a document's details over the few days after it is published, so expect a document you were alerted to as new to arrive again as modified. **A comment period closing does not fire.** `comments_open` is evaluated at query time from `comments_close_on`, so a deadline passing is not a change to the document. A `comments_open=true` alert tells you when a matching document opens for comment, not when its period ends. ## Examples ```bash # Proposed rules still open for comment GET /api/federal_register/?type=Proposed%20Rule&comments_open=true # Everything amending 40 CFR Part 52 since the start of 2025 GET /api/federal_register/?cfr_title=40&cfr_part=52&publication_date_after=2025-01-01 # Significant EPA documents GET /api/federal_register/?fr_agency=environmental-protection-agency&significant=true # Proposed rules from one department and its sub-agencies, still open for comment GET /api/federal_register/?agency=HHS&type=Proposed%20Rule&comments_open=true # A phrase, ranked by relevance GET /api/federal_register/?search=%22greenhouse%20gas%22 # Every document under one RIN GET /api/federal_register/?rin=2060-AV16&ordering=publication_date # Comment deadlines closing soonest first, within a window GET /api/federal_register/?comments_close_on_after=2026-10-01&comments_close_on_before=2026-10-31&ordering=comments_close_on # One document number (may return more than one document before 2016) GET /api/federal_register/?document_number=2016-31922 # Detail, with the body GET /api/federal_register/{uuid}/?shape=uuid,document_number,publication_date,title,full_text ``` Notes: - `*` is only valid inside expansions; Federal Register documents have none, so use explicit field lists. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Filtering, ordering, and response shaping for /api/forecasts/, Tango's agency procurement forecast endpoint." tags: [forecasts, api, reference] updated: 2026-08-02 --- # Forecasts Forecasts are procurement forecasts exposed at `/api/forecasts/`. For field definitions, see the [Forecasts Data Dictionary](../data-dictionary/forecasts.md). For which agency sources we ingest (HHS, DHS, GSA, COMMERCE, DOE, ED, TREASURY, DOI, DOL, DOT, USDA, VA, NRC, NSF), see [Forecasts we track](../data-dictionary/forecasts.md#forecasts-we-track). ## Endpoints - `GET /api/forecasts/` (list + filtering + search + ordering) - `GET /api/forecasts/{pk}/` (detail) ## Response Shaping Forecasts default to the shaping pipeline β€” all responses go through shaping even without `?shape=`. Use `?shape=` to customize which fields are returned. - **List default:** `id`, `source_system`, `external_id`, `agency`, `title`, `description`, `anticipated_award_date`, `fiscal_year`, `naics_code`, `is_active`, `status`, `primary_contact`, `place_of_performance`, `estimated_period`, `set_aside`, `contract_vehicle`, `organization(*)` - **Detail default:** Same as list, plus `raw_data` and `display(*)` The `organization(*)` expand is the canonical 7-key office payload, resolved deterministically from the forecast's `agency` text against Tango's department-level agency aliases. All 14 agency values currently in the data resolve: HHS, DHS, DOI, GSA, DOE, ED, DOT, VA, DOL, NRC, NSF, COMMERCE, TREASURY, USDA. A forecast whose `agency` value matches no department alias returns `organization: null`. See [Response Shaping](../guides/patterns/response-shaping.md) for full syntax and the [Forecasts Data Dictionary](../data-dictionary/forecasts.md) for field definitions. ## Filtering Core filters (multi-value filters accept `|` for OR; date filters require `YYYY-MM-DD` format β€” invalid dates or inverted ranges return **400**, see [Date filters](shared.md#date-filters)): | Param | What it does | | --- | --- | | `agency` | Filter by agency acronym. | | `source_system` | Filter by source system identifier. | | `naics_code` | Filter by exact NAICS. | | `naics_starts_with` | Filter by NAICS prefix (e.g. `54`). | | `fiscal_year` | Filter by exact fiscal year. | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range. | | `award_date_after`, `award_date_before` | Anticipated award date range (`YYYY-MM-DD`). | | `modified_after`, `modified_before` | Modified-in-Tango date range (`YYYY-MM-DD`). | | `status` | Status (case-insensitive, partial match). | | `search` | Full-text search over title/description (vector-backed). | ## Ordering Forecasts support `ordering=` with a strict allowlist: - `anticipated_award_date` - `fiscal_year` - `title` Examples: - Soonest award first: `GET /api/forecasts/?ordering=anticipated_award_date` - Most recent fiscal year first: `GET /api/forecasts/?ordering=-fiscal_year` ## Pagination Forecasts use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_forecasts( agency="GSA", naics_starts_with="54", ordering="-anticipated_award_date", limit=10, shape=ShapeConfig.FORECASTS_MINIMAL, ) for f in resp.results: print(f.title, f.anticipated_award_date) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listForecasts({ agency: "GSA", naics_starts_with: "54", ordering: "-anticipated_award_date", limit: 10, shape: ShapeConfig.FORECASTS_MINIMAL, }); for (const f of resp.results) { console.log(f.title, f.anticipated_award_date); } ``` --- --- description: "Filtering, ordering, and response shaping for /api/grants/, Tango's Grants.gov opportunity endpoint." tags: [grants, api, reference] updated: 2026-05-13 --- # Grants Grant opportunities are exposed at `/api/grants/`. For field definitions, see the [Grants Data Dictionary](../data-dictionary/grants.md). These are funding announcements from Grants.gov. Grant **awards**, the money agencies have obligated to recipients, are at [`/api/assistance/grants/`](assistance-grants.md); an award's `funding_opportunity_number` names the opportunity it was made under. ## Endpoints - `GET /api/grants/` (list + filtering + search + ordering) - `GET /api/grants/{grant_id}/` (detail) ## Response Shaping Grants default to the shaping pipeline β€” all responses go through shaping even without `?shape=`. Use `?shape=` to customize which fields are returned. - **List default:** `grant_id`, `opportunity_number`, `agency_code`, `title`, `description`, `applicant_eligibility_description`, `funding_activity_category_description`, `grantor_contact`, `last_updated`, plus expanded `organization(*)`, `status(*)`, `category(*)`, `cfda_numbers(*)`, `applicant_types(*)`, `funding_categories(*)`, `funding_instruments(*)`, `funding_details(*)`, `important_dates(*)`, `additional_info(*)` - **Detail default:** Same as list, plus `synopsis`, `forecast`, `opportunity_history` The `organization(*)` expand is the canonical 7-key office payload, resolved from the grant's `agency_code` via a segment-walk (e.g. `HHS-NIH11` β†’ NIH; `USDOJ-OJP-BJA` β†’ BJA; trailing fiscal-cycle digits stripped where applicable). Grants from agencies without a canonical organization mapping return `organization: null`. See [Response Shaping](../guides/patterns/response-shaping.md) for full syntax and the [Grants Data Dictionary](../data-dictionary/grants.md) for field definitions. ## Filtering Core filters (date filters require `YYYY-MM-DD` format; invalid dates or inverted ranges return **400** β€” see [Date filters](shared.md#date-filters)): | Param | What it does | | --- | --- | | `search` | Full-text search (vector-backed). | | `agency` | Filter by agency abbreviation (substring). | | `opportunity_number` | Exact opportunity number. | | `cfda_number` | CFDA number (substring match). | | `status` | Opportunity status (case-insensitive choice). | | `applicant_types` | Eligibility/applicant types (case-insensitive choice). | | `funding_categories` | Funding category codes (case-insensitive choice). | | `funding_instruments` | Funding instruments (case-insensitive choice). | | `posted_date_after`, `posted_date_before` | Posted date range (inclusive, `YYYY-MM-DD`). | | `response_date_after`, `response_date_before` | Response/deadline date range. | ## Ordering Grants support `ordering=` with a strict allowlist: - `posted_date` (also accepts `last_updated`) - `deadline_current` - `rank` (relevance ranking; most useful when `search` is present) Examples: - Most recently posted first: `GET /api/grants/?ordering=-posted_date` - Soonest deadline first: `GET /api/grants/?ordering=deadline_current` ## Pagination Grants use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_grants( agency="HHS", search="opioid", ordering="-posted_date", limit=10, shape=ShapeConfig.GRANTS_MINIMAL, ) for g in resp.results: print(g.grant_id, g.opportunity_number, g.title) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listGrants({ agency: "HHS", search: "opioid", ordering: "-posted_date", limit: 10, shape: ShapeConfig.GRANTS_MINIMAL, }); for (const g of resp.results) { console.log(g.grant_id, g.opportunity_number, g.title); } ``` --- --- description: "Filtering and ordering for /api/gsa_elibrary_contracts/, the persisted GSA eLibrary MAS contract endpoint." updated: 2026-05-11 --- # GSA eLibrary contracts Persisted GSA eLibrary contract metadata is exposed directly at `/api/gsa_elibrary_contracts/`. For field definitions, see the [GSA eLibrary Contracts Data Dictionary](../data-dictionary/gsa-elibrary-contracts.md). These endpoints exist in addition to the `gsa_elibrary` enrichment on `/api/idvs/`. ## Endpoints - `GET /api/gsa_elibrary_contracts/` (list + filtering + ordering) - `GET /api/gsa_elibrary_contracts/{uuid}/` (detail) ## Response shape (non-shaped) Each result includes: - `uuid`, `schedule`, `contract_number` - `sins`, `cooperative_purchasing`, `disaster_recovery_purchasing`, `file_urls` - `recipient` (cached lookup by UEI; fields: `uei`, `display_name`) - `idv` (best-effort; fields: `key`, `award_date`) ## Filtering Core filters: | Param | What it does | | --- | --- | | `schedule` | Filter by schedule (exact). Example: `MAS` | | `contract_number` | Filter by contract number (exact, case-insensitive). Example: `GS-07F-0251W` | | `uei` | Filter by recipient UEI (from eLibrary provenance; exact). Multi-value: use `\|` for OR. | | `sin` | Filter by SIN code (exact). Multi-value: use `\|` for OR. | | `search` | Search across schedule, contract_number, UEI, SIN, and linked IDV fields. Multi-value: use `\|` for OR. | | `key` | Filter by linked IDV key (exact, case-insensitive). | | `piid` | Filter by linked IDV PIID (exact, case-insensitive). | ## Ordering Supports `ordering=` with: - `last_updated` - `schedule` - `contract_number` Example: ```bash /api/gsa_elibrary_contracts/?schedule=MAS&ordering=-last_updated ``` ## Pagination Uses page-number pagination. ## Response shaping Like other endpoints, shaping is available via `shape=`: ```bash /api/gsa_elibrary_contracts/?contract_number=47QRAA26D003K&shape=uuid,schedule,contract_number,sins,file_urls,recipient(uei,display_name),idv(key,award_date) ``` --- --- description: "Filtering, ordering, and pagination for /api/idvs/, Tango's indefinite delivery vehicle award endpoint." tags: [idvs, api, reference] updated: 2026-10-16 --- # IDVs IDVs (Indefinite Delivery Vehicles) are awards exposed at `/api/idvs/`. If you’re trying to work at the β€œsolicitation that produced many IDV awards” level, also see [Vehicles](vehicles.md). For field definitions, see the [IDVs Data Dictionary](../data-dictionary/idvs.md). IDV responses include a vehicle UUID when the IDV is grouped under a Tango Vehicle, which you can use to fetch vehicle details at `GET /api/vehicles/{uuid}/`. ## Endpoints - `GET /api/idvs/` (list + filtering + search + ordering) - `GET /api/idvs/{key}/` (detail) - `GET /api/idvs/{key}/transactions/` (detail transactions) - `GET /api/idvs/{key}/awards/` (child awards / task orders under an IDV; behaves like `/api/contracts/`) - `GET /api/idvs/{key}/idvs/` (child IDVs under an IDV; behaves like `/api/idvs/`) Removed (legacy solicitation grouping β€” these routes no longer exist): - `GET /api/idvs/{identifier}/summary/` β€” returns 404 - `GET /api/idvs/{identifier}/summary/awards/` β€” returns 404 ## Filtering Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day. ### Text / parties | Param | What it does | | --- | --- | | `search` | Full-text-ish search across IDV search vectors (good for keywords). | | `recipient` | Search by recipient/vendor name. | | `uei` | Filter by recipient UEI (exact). | | `piid` | Filter by PIID (case-insensitive). | | `solicitation_identifier` | Filter by solicitation identifier. Matches every spelling of the number (`N6600120R0002` or `N66001-20-R-0002`, any case). Multi-value: use `|` for OR. | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | | `ordering` | Sort results (allowlist: `award_date`, `obligated`, `total_contract_value`; prefix with `-` for descending). | ### Agencies | Param | What it does | | --- | --- | | `awarding_agency` | Filter by awarding agency (code/name/abbrev; best-effort matching). | | `funding_agency` | Filter by funding agency (code/name/abbrev; best-effort matching). | ### Codes / set-asides / types | Param | What it does | | --- | --- | | `naics` | Filter by NAICS. | | `psc` | Filter by PSC. | | `set_aside` | Filter by set-aside. | | `idv_type` | Filter by IDV type code. | | `commercial_item_acquisition_procedures` | Filter by FPDS commercial item acquisition procedures code (`A`–`E`, case-insensitive). Multi-value: use `|` for OR. See [Commercial item acquisition procedures](#commercial-item-acquisition-procedures). | ### Commercial item acquisition procedures `commercial_item_acquisition_procedures` matches the FPDS code recorded on the IDV. | Code | Meaning | | --- | --- | | `A` | Commercial Products/Services | | `B` | Products or services pursuant to FAR 12.102(f) | | `C` | Services pursuant to FAR 12.102(g) | | `D` | Commercial Products/Services Procedures not used | | `E` | DoD - Section 803 CSO Procedures | `E` marks awards made through a DoD Section 803 Commercial Solutions Opening (CSO). To list them: ``` GET /api/idvs/?commercial_item_acquisition_procedures=E ``` Codes are case-insensitive, and `A|E` matches either code. An unknown or multi-character value matches nothing rather than returning an error. This filter is not available on [OTAs](otas.md) or [OT IDVs](otidvs.md). ### Dates / fiscal years All date filters require `YYYY-MM-DD` format. Invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters) for details. | Param | What it does | | --- | --- | | `award_date` | Award date (exact). | | `award_date_gte`, `award_date_lte` | Award date range. | | `fiscal_year` | Fiscal year (exact, `YYYY`). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range (`YYYY`). | ### Period of performance / ordering window IDVs differ from contracts: - They do **not** have contract-style period-of-performance end dates. - The ordering window is typically expressed via last-date-to-order fields. | Param | What it does | | --- | --- | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance **start** date range. | | `last_date_to_order_gte`, `last_date_to_order_lte` | Last date to order range (primary IDV β€œexpiring” concept). | | `expiring_gte`, `expiring_lte` | Alias for last-date-to-order range filters. | ### Multi-value filter syntax Use `|` (or the literal word `OR`) to match any of several values: ``` naics=541511|541512 ``` The same syntax works on every filter that accepts multiple values. ## Ordering IDVs support `ordering=` with a strict allowlist: - `award_date` - `obligated` - `total_contract_value` Examples: - Newest first: `GET /api/idvs/?ordering=-award_date` - Largest obligations first: `GET /api/idvs/?ordering=-obligated` ## Pagination High-volume award endpoints use **cursor-based (keyset) pagination**. - Use `limit` to control page size. - Follow the `next` / `previous` URLs in responses. - If you’re constructing requests manually, you’ll typically pass a `cursor` parameter from the `next` URL. ## Response shaping IDV responses use the shaping pipeline by default β€” even without an explicit `?shape=` parameter, responses go through the shaping system with a default shape that includes all standard fields plus expanded choice fields (`idv_type(*)`, `type_of_idc(*)`, `multiple_or_single_award_idv(*)`), relationships, and period of performance. Use `?shape=` to customize the response. See [Response Shaping](../guides/patterns/response-shaping.md#idvs-apiidvs) for the full field reference. ```bash # Expand idv_type to structured code/description /api/idvs/?shape=key,piid,idv_type(code,description) # Period of performance (uses last_date_to_order, not end_date) /api/idvs/?shape=key,piid,period_of_performance(start_date,last_date_to_order) # Resolved NAICS/PSC lookups /api/idvs/?shape=key,piid,naics(code,description),psc(code,description) ``` ## GSA eLibrary enrichment IDV list and detail responses include best-effort enrichment from GSA eLibrary under `gsa_elibrary` (or `null` when no matching eLibrary row exists). You can use shaping to request only the subfields you care about: ```bash /api/idvs/?piid=&shape=key,piid,gsa_elibrary(schedule,contract_number,sins,file_urls) ``` You can also query persisted eLibrary rows directly via `GET /api/gsa_elibrary_contracts/`. ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don’t yet expose a first-class `list_idvs()` / `listIdvs()` method. Until they do, you can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) # Workaround until the SDK ships a first-class list_idvs() data = client._get( "/api/idvs/", params={ "search": "SEWP", "ordering": "-award_date", "limit": 10, }, ) print("count:", data.get("count")) print("first key:", (data.get("results") or [{}])[0].get("key")) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); // Workaround until the SDK ships a first-class listIdvs() const http = (client as any).http; const data = await http.get("/api/idvs/", { search: "SEWP", ordering: "-award_date", limit: 10, }); console.log("count:", data.count); console.log("first key:", data?.results?.[0]?.key); ``` --- --- description: "Index of Tango's API reference pages, organized by resource, with filtering, ordering, and pagination details for the highest-traffic endpoints." tags: [api, reference] updated: 2026-11-10 --- # API Reference These pages are a curated reference for **filtering**, **ordering**, and **pagination** on Tango's highest-traffic endpoints, with copy/pasteable examples (including SDK usage). Swagger is still the canonical surface-area reference, but these pages aim to be faster to use day-to-day. - Swagger (OpenAPI): [https://tango.dev/api/](https://tango.dev/api/) - For field definitions, see the [Data Dictionary](../data-dictionary/index.md). ## Awards Definitive contracts, indefinite-delivery vehicles, other transactions, subawards, and solicitation-level groupings. - [Contracts](contracts.md) β€” Definitive contract awards. [Response shaping β†’](../guides/patterns/response-shaping.md#contracts-apicontracts) - [IDVs](idvs.md) β€” Indefinite delivery vehicles (GWACs, IDIQs, etc.). [Response shaping β†’](../guides/patterns/response-shaping.md#idvs-apiidvs) - [OTAs](otas.md) β€” Other Transaction Agreements from FPDS. [Response shaping β†’](../guides/patterns/response-shaping.md#otas-apiotas) - [OTIDVs](otidvs.md) β€” Other Transaction IDVs from FPDS. [Response shaping β†’](../guides/patterns/response-shaping.md#otidvs-apiotidvs) - [Subawards](subawards.md) β€” Sub-contracts and sub-grants under prime awards. [Response shaping β†’](../guides/patterns/response-shaping.md#subawards-apisubawards) - [Vehicles](vehicles.md) β€” Solicitation-centric grouping of IDVs. [Response shaping β†’](../guides/patterns/response-shaping.md#vehicles-apivehicles) - [GSA eLibrary contracts](gsa-elibrary-contracts.md) β€” Persisted GSA eLibrary contract metadata (direct endpoint). ## Financial assistance - [Overview](assistance.md) β€” How financial-assistance awards are shaped: awards versus transactions, assistance listings, retired award IDs, recipients without a UEI, and grant awards versus Grants.gov opportunities. - [Grant awards](assistance-grants.md) β€” Grants and cooperative agreements (`F001`, `F002`) from USAspending. [Response shaping β†’](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype) - [Loans](assistance-loans.md) β€” Direct loans and loan guarantees (`F003`, `F004`), with face value and subsidy cost. - [Direct payments](assistance-direct-payments.md) β€” Direct payments for a specified use or with unrestricted use (`F006`, `F007`). - [Other assistance](assistance-other.md) β€” Insurance, asset forfeiture, property and other assistance (`F005`, `F008`–`F010`, not specified). - [Assistance listings (CFDA)](assistance-listings.md) β€” CFDA program numbers and titles for federal grants/assistance. [Response shaping β†’](../guides/patterns/response-shaping.md#assistance-listings-apiassistance_listings) - [Subgrants](subgrants.md) β€” Subawards reported under federal grants and cooperative agreements, keyed by the SAM.gov report UUID. [Response shaping β†’](../guides/patterns/response-shaping.md#subgrants-apiassistancesubgrants) ## Entities - [Entities](entities.md) β€” Vendors and recipients in federal contracting and assistance; UEI is the canonical identifier (from SAM.gov). [Response shaping β†’](../guides/patterns/response-shaping.md#entities-apientities) - [Exclusions](exclusions.md) β€” SAM.gov exclusions (debarments, suspensions); `?active=true` for records in force today. [Data dictionary β†’](../data-dictionary/exclusions.md) ## DIBBS - [DIBBS](dibbs.md) β€” DLA Internet Bid Board System: requests for quote, solicitations (RFP/IFB), and awards from the Defense Logistics Agency. [Data dictionary β†’](../data-dictionary/dibbs.md) ## SBIR/STTR - [SBIR/STTR](sbir.md) β€” SBIR/STTR topics across every participating agency plus the DoD DSIP solicitation cycles behind them. [Data dictionary β†’](../data-dictionary/sbir.md) ## State & Local β€” **Beta** - [State & Local](sled.md) β€” State, local and education (SLED) solicitations and planned procurements from individual government portals, with a per-state coverage endpoint. Does not join to the federal data: no UEI, no PIID, no NAICS/PSC crosswalk. [Data dictionary β†’](../data-dictionary/sled.md) ## eBuy - [eBuy](ebuy.md) β€” GSA eBuy requests (RFQs, RFPs, RFIs), scoped to the requests posted under your own Schedule contracts, with attachment text search and downloads. Available on Medium plans and above, by arrangement: requires a contract link from MakeGov. [Response shaping β†’](../guides/patterns/response-shaping.md#ebuy-apiebuyrequests) Β· [Data dictionary β†’](../data-dictionary/ebuy.md) ## Forecasts - [Forecasts](forecasts.md) β€” Upcoming procurement opportunities from agency feeds (e.g., HHS, DHS) before they appear as SAM.gov solicitations. [Response shaping β†’](../guides/patterns/response-shaping.md#forecasts-apiforecasts) ## Grants - [Grants](grants.md) β€” Grant opportunities from Grants.gov (funding opportunities, not awards; for awards see [Grant awards](assistance-grants.md)). [Response shaping β†’](../guides/patterns/response-shaping.md#grants-apigrants) ## Budget β€” **Beta** - [Budget](budget.md) β€” Federal-account budget data (requested β†’ enacted β†’ apportioned β†’ obligated β†’ outlayed) joined to FPDS contract activity. Includes `/recipients/` and `/quarters/` drill-downs and the entity `/budget-flows/` action. [Data dictionary β†’](../data-dictionary/budget.md) Β· [Exploration guide β†’](../guides/how-to/explore-federal-budget.md) ## IT Dashboard - [IT Dashboard](itdashboard.md) β€” Federal IT investment data from [itdashboard.gov](https://www.itdashboard.gov/), keyed by Unique Investment Identifier (UII). Some filters are tier-gated; all shape expansions are available on every plan (only the `business_case_html` leaf is gated). [Response shaping β†’](../guides/patterns/response-shaping.md#it-dashboard-apiitdashboard) ## Protests - [Protests](protests.md) β€” Bid protest decisions from GAO and SBA OHA (2015 onward) and the Court of Federal Claims (2026 onward), with subordinate dockets available via `?shape=...,dockets(...)`. Requires authentication. [Response shaping β†’](../guides/patterns/response-shaping.md#protests-apiprotests) Β· [Data dictionary β†’](../data-dictionary/protests.md) ## Contract appeals - [Contract appeals](contract-appeals.md) β€” Contract Disputes Act decisions of the Civilian Board of Contract Appeals (CBCA, 2007 onward) and the Armed Services Board of Contract Appeals (ASBCA, 2010 onward). Disputes under a contract already awarded, not bid protests. Free on every plan; only the `decision_text` field is gated. [Response shaping β†’](../guides/patterns/response-shaping.md#contract-appeals-apicontract_appeals) Β· [Data dictionary β†’](../data-dictionary/contract-appeals.md) ## Federal Register - [Federal Register](federal-register.md) β€” Every rule, proposed rule, notice and presidential document published in the Federal Register since 1994, filterable by CFR citation, agency, RIN, type, dates and open comment period. Free on every plan, including the full text. [Response shaping β†’](../guides/patterns/response-shaping.md#federal-register-apifederal_register) Β· [Data dictionary β†’](../data-dictionary/federal-register.md) ## News - [Award announcements](award-announcements.md) β€” The Department of War's daily contracts release and MakeGov-generated announcements of new civilian IDVs and OTAs, with every row naming its `source`. Available on every plan. [Response shaping β†’](../guides/patterns/response-shaping.md#award-announcements-apinewsaward_announcements) ## Opportunities SAM.gov contract opportunity and notice data. - [Opportunities](opportunities.md) β€” Contract opportunities aggregated by parent. [Response shaping β†’](../guides/patterns/response-shaping.md#opportunities-apiopportunities) - [Notices](notices.md) β€” Individual SAM.gov notice records (amendments, updates) under an opportunity. [Response shaping β†’](../guides/patterns/response-shaping.md#notices-apinotices) ## Metrics - [Metrics](metrics.md) β€” Time-series obligation and award-count metrics for entities, NAICS codes, and PSC codes (same URL pattern and query params for all). ## Reference data Lookup tables and codes used across awards and entities. - [Business types](business-types.md) β€” SAM.gov business type codes (e.g., small business, 8(a), HUBZone). [Response shaping β†’](../guides/patterns/response-shaping.md#business-types-apibusiness_types) - [MAS SINs](mas-sins.md) β€” MAS Special Item Numbers (SINs) reference data. [Response shaping β†’](../guides/patterns/response-shaping.md#mas-sins-apimas_sins) - [NAICS](naics.md) β€” North American Industry Classification System codes. [Response shaping β†’](../guides/patterns/response-shaping.md#naics-apinaics) - [Organizations](organizations.md) β€” Unified federal hierarchy (departments, agencies, offices in one tree with search and obligations). [Response shaping β†’](../guides/patterns/response-shaping.md#organizations-apiorganizations) - [PSC](psc.md) β€” Product/Service Codes for federal contracting. [Response shaping β†’](../guides/patterns/response-shaping.md#psc-apipsc) ## Shared Objects and legacy endpoints shared across multiple resources. These data structures appear in response shaping expands on many endpoints (e.g., `awarding_office(...)`, `department(...)`, `set_aside(...)`). - [Shared response objects](shared.md) β€” Common expanded objects (set-aside, office) returned across endpoints. - [Agencies](agencies.md) *(deprecated)* β€” Federal agencies (legacy endpoint; use [Organizations](organizations.md) instead). [Response shaping β†’](../guides/patterns/response-shaping.md#agencies-apiagencies) - [Departments](departments.md) *(deprecated)* β€” Top-level federal departments (legacy endpoint; use [Organizations](organizations.md) instead). [Response shaping β†’](../guides/patterns/response-shaping.md#departments-apidepartments) - [Offices](offices.md) *(deprecated)* β€” Sub-agency offices (legacy endpoint; use [Organizations](organizations.md) instead). [Response shaping β†’](../guides/patterns/response-shaping.md#offices-apioffices) - [Set-aside codes](set-aside.md) β€” Set-aside type codes and descriptions. --- --- description: "Tiered filtering and response shaping for /api/itdashboard/, Tango's federal IT investment endpoint." updated: 2026-05-13 --- # IT Dashboard Federal IT investment data from [itdashboard.gov](https://www.itdashboard.gov/) exposed at `/api/itdashboard/`. For field definitions, see the [IT Dashboard Data Dictionary](../data-dictionary/itdashboard.md). ## Endpoints - `GET /api/itdashboard/` (list + filtering + search) - `GET /api/itdashboard/{uii}/` (detail by Unique Investment Identifier) ## Filtering ### Free tier | Param | What it does | | --- | --- | | `search` | Full-text search over UII, investment title, description, agency name, and bureau name (vector-backed). | | `agency_name` | Text search on agency name (e.g., `?agency_name=defense`). | ### Pro+ tier | Param | What it does | | --- | --- | | `agency_code` | Filter by numeric agency code (e.g., `?agency_code=21` for the Department of Transportation). | | `type_of_investment` | Filter by investment type (case-insensitive, e.g., `?type_of_investment=Major IT Investment`). | | `updated_time_after`, `updated_time_before` | Filter by updated time range (e.g., `?updated_time_after=2026-01-01`). | ### Business+ tier | Param | What it does | | --- | --- | | `cio_rating` | Filter by exact CIO risk rating: 1=High Risk, 2=Moderately High, 3=Medium, 4=Moderately Low, 5=Low Risk. | | `cio_rating_max` | Filter investments at or below a CIO rating threshold (e.g., `?cio_rating_max=2` returns High + Moderately High Risk). | | `performance_risk` | Boolean. `?performance_risk=true` returns investments with at least one NOT MET performance metric. | !!! note "Tier gating" Filters marked Pro+ or Business+ require the corresponding subscription tier. Lower-tier users attempting to use a gated filter receive a 403 response with structured upgrade information. ## Pagination IT Dashboard uses page-number pagination (`page`, `limit`) and returns `count`, `next`, `previous`, and `results`. ## Response Shaping IT Dashboard supports the `?shape=` query parameter. When no `?shape=` is provided, the endpoint returns a default shape. **Default shape (list):** `uii,agency_name,bureau_name,investment_title,type_of_investment,part_of_it_portfolio,updated_time,url,organization(*)` **Default shape (detail):** adds `agency_code` and `bureau_code` (otherwise identical to list). ### Available fields (all tiers) | Field | Type | Description | | --- | --- | --- | | `uii` | String | Unique Investment Identifier (e.g., `021-488119819`). | | `agency_code` | Integer | Numeric agency code. | | `agency_name` | String | Agency name. | | `bureau_code` | Integer | Numeric bureau code. | | `bureau_name` | String | Bureau name. | | `investment_title` | String | Investment title. | | `type_of_investment` | String | Investment type (e.g., "Major IT Investment"). | | `part_of_it_portfolio` | String | IT portfolio classification. | | `updated_time` | DateTime | Last updated timestamp from source. | | `url` | String | Canonical URL on itdashboard.gov. | | `organization_id` | UUID | Underlying foreign key to `agencies.Organization`; `null` when no canonical org match. | ### Tier-gated leaf field | Field | Tier | Description | | --- | --- | --- | | `business_case_html` | Business+ | Full business case HTML from IT Dashboard. | ### Available expansions All shape expansions are available to every tier β€” the underlying source data is public from itdashboard.gov. Only the `business_case_html` **leaf** field requires Business+. | Expansion | Description | | --- | --- | | `organization(*)` | Canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Resolved deterministically from `(agency_code, bureau_code)`. Included in default shape. | | `funding(*)` | Fiscal-year funding breakdown (FY2020–FY2025 internal funding and contributions). | | `details(*)` | Extended metadata: description, previous/current UII, classification, business case URL, public URLs. | | `cio_evaluation(*)` | CIO risk ratings over time (rating, comment, date, latest indicator). | | `contracts(*)` | Associated IT contracts. | | `projects(*)` | Project details under the investment. | | `cost_pools_towers(*)` | Cost pool and tower breakdowns. | | `funding_sources(*)` | Funding source details. | | `performance_metrics(*)` | Performance metrics with targets and actuals. | | `performance_actual(*)` | Historical performance actuals. | | `operational_analysis(*)` | Operational analysis data. | ### Examples ```bash # Free tier: basic search GET /api/itdashboard/?search=navy # Pro+ tier: filter by agency + expand funding GET /api/itdashboard/?agency_code=7&shape=uii,investment_title,url,funding(*) # Business+ tier: find high-risk investments with full details GET /api/itdashboard/?cio_rating_max=2&shape=uii,investment_title,agency_name,cio_evaluation(*),performance_metrics(*) # Business+ tier: underperforming investments GET /api/itdashboard/?performance_risk=true&shape=uii,investment_title,agency_name,url,performance_metrics(*) # Detail with everything GET /api/itdashboard/021-488119819/?shape=uii,investment_title,agency_name,url,funding(*),details(*),cio_evaluation(*),contracts(*),projects(*) ``` See [Response Shaping](../guides/patterns/response-shaping.md) for syntax and examples. --- --- description: "Filtering and ordering for the CALC labor category rate endpoints nested under IDVs and entities." updated: 2026-08-17 --- # CALC Labor Category Rates CALC (Contract Awarded Labor Category) labor rates are exposed as nested endpoints under IDVs and entities. For field definitions, see the [CALC Labor Rates Data Dictionary](../data-dictionary/lcats.md). **Access:** Requires Pro tier or above. ## Endpoints - `GET /api/idvs/{key}/lcats/` (rates for a specific IDV) - `GET /api/entities/{uei}/lcats/` (rates for a specific entity, via IDV recipient linkage) These are nested endpoints -- there is no top-level `/api/lcats/` route. Use the IDV key or entity UEI to scope the results. ## Filtering Core filters: | Param | What it does | | --- | --- | | `search` | Full-text search across vendor name, labor category, category, and subcategory. | | `vendor_name` | Case-insensitive partial match on vendor name. | | `labor_category` | Case-insensitive partial match on labor category title. | | `price_gte`, `price_lte` | Filter by current price range (decimal). | | `education_level` | Exact match on education level (case-insensitive). | | `min_years_experience_gte`, `min_years_experience_lte` | Filter by minimum years of experience range. | | `security_clearance` | Exact match on security clearance requirement (case-insensitive). | | `worksite` | Exact match on work location type (case-insensitive). | | `business_size` | Exact match on business size code (case-insensitive). | | `sin` | Exact match on Special Item Number (case-insensitive). | | `category` | Case-insensitive partial match on service category. | | `idv_piid` | Exact match on the stored PIID from CALC. | | `key` | IDV key (case-insensitive). | | `piid` | IDV PIID (case-insensitive). | ## Ordering CALC labor rates support `ordering=` with a strict allowlist: - `current_price` - `vendor_name` - `labor_category` - `education_level` - `min_years_experience` - `modified` Prefix with `-` for descending order. Examples: - Cheapest first: `GET /api/idvs/{key}/lcats/?ordering=current_price` - Most experienced first: `GET /api/idvs/{key}/lcats/?ordering=-min_years_experience` ## Pagination Uses page-number pagination: - `page` (default 1) - `limit` (default 10, max 100) ## Response shaping Use `?shape=` to customize the response. Root fields: - `uuid`, `labor_category`, `current_price` - `education_level`, `min_years_experience`, `experience_range` - `security_clearance`, `worksite` - `sin`, `category`, `subcategory`, `schedule` - `contract_start`, `contract_end` Expansions: - `idv(key, piid, award_date)` -- linked IDV details (Pro tier required) - `recipient(uei, display_name)` -- entity details via IDV recipient (Pro tier required) - `business_size(code, description)` -- business size with human-readable description A default shape is applied when no `?shape=` parameter is provided, so `?flat=true` works without needing an explicit shape. Example: ```bash /api/idvs/{key}/lcats/?shape=uuid,labor_category,current_price,idv(key,piid) ``` Flat example: ```bash /api/idvs/{key}/lcats/?flat=true ``` ## Rate limiting These endpoints (`GET /api/idvs/{key}/lcats/` and `GET /api/entities/{uei}/lcats/`) carry a separate **premium query budget** that replaces your account's standard daily and per-minute rate limits β€” it is not additive. A premium budget is tied to an endpoint family (these LCATS endpoints share one counter). Requests count as **one request per API call, regardless of how many rows are returned**. The budget resets daily at **00:00 UTC**. Check your current premium usage and limits on your [account profile](https://tango.makegov.com/accounts/profile/). To request a higher limit, email [hello@makegov.com](mailto:hello@makegov.com). For header details and how 429 responses work, see the [Rate limits guide](../guides/patterns/rate-limits.md). --- --- description: "Filtering, value formats, and pagination for /api/mas_sins/, the GSA MAS Special Item Number reference endpoint." updated: 2026-05-13 --- # MAS SINs MAS SIN reference data is exposed at `/api/mas_sins/`. For field definitions, see the [MAS SINs Data Dictionary](../data-dictionary/mas-sins.md). ## Endpoints - `GET /api/mas_sins/` (list) - `GET /api/mas_sins/{sin}/` (detail) ## Value formats and normalization - **`sin`**: String SIN code (examples: `334310`, `541611`, `561210FS`, `ANCILLARY`). - **`large_category_code`**: Single-letter category code (example: `A`). - **`sub_category_code`**: 3-character subcategory code (example: `A01`). - **`set_aside_code`**: One of `Y`, `N`, `B`. - **`service_comm_code`**: One of `B`, `C`, `S`, `P`. - **`naics_codes`**: List of NAICS code integers. Some SINs may use special values (e.g. `0` for `ANCILLARY`). - **`expiration_date`**: Parsed to an ISO date. The source uses a `YYYYDDD` (year + day-of-year) numeric format in some rows (example: `2022181` β†’ 2022-06-30). ## Filtering - `search`: matches against SIN code, NAICS code, PSC code, title, and description. Examples: - Search by SIN: `GET /api/mas_sins/?search=334310` - Search by NAICS: `GET /api/mas_sins/?search=541611` - Search by PSC: `GET /api/mas_sins/?search=R799` - Search by text: `GET /api/mas_sins/?search=facilities` ## Ordering `/api/mas_sins/` does **not** support `ordering=...`. ## Pagination MAS SINs use page-number pagination (static reference pagination defaults to larger pages): - `page` (default 1) - `limit` (default 1000, max 10000) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `sin`, `large_category_code`, `large_category_name`, `sub_category_code`, `sub_category_name`, `psc_code`, `state_local`, `set_aside_code`, `service_comm_code`, `expiration_date`, `tdr`, `olm`, `naics_codes`, `title`, `description` - No expansions. Default shape (no `?shape=` param): all 15 fields above. ```bash # Select a subset of fields /api/mas_sins/?shape=sin,title,description ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). --- --- description: "How the shared time-series metrics endpoints for entities, NAICS codes, and PSC codes work, and the path and query parameters they take." updated: 2026-05-13 --- # Metrics Metrics endpoints return **time-series obligation and award counts** for a specific entity, NAICS code, or PSC code. They share the same URL pattern and query parameters, so this page describes behavior once, then lists the available endpoints. ## How metrics work Each metrics endpoint is: `GET /api/{resource}/{id}/metrics///` - **Path parameters** (required): - `{id}` β€” The resource identifier (entity UEI, NAICS code, or PSC code). - `months` β€” Lookback window in months (positive integer). Example: `24` for the last 24 months. - `period_grouping` β€” How to bucket time: `year`, `quarter`, or `month`. - **Query parameters** (optional): - `group_by` β€” Comma-separated list of dimensions to break out: `agency`, `department`. When used, each result row includes the grouped dimension(s). Rolling averages are not supported when grouping; if both are used, rolling is skipped and a `warning` is returned. - `fiscal_year` β€” If `true` or `1`, buckets use federal fiscal year (Oct–Sep). Default is calendar year. - `rolling` β€” If `true` or `1`, adds a rolling average to each result (when not using `group_by`). Response shape (same for all three): - `count` β€” Number of result rows. - `description` β€” Human-readable description of the time range and grouping. - `warning` β€” Present only when e.g. rolling was requested with `group_by` (rolling skipped). - The resource object β€” `recipient` (entity), `naics_code`, or `psc_code` (the one you queried). - `results` β€” Array of objects. Each has: - `year` (and optionally `month`, `quarter` depending on `period_grouping`), - `awards_obligated` β€” obligation amount (USD) for the period, - `subawards_obligated` β€” subaward obligation amount (entity endpoints only), - `awards_count` β€” number of awards (NAICS and PSC endpoints only), - `rolling_avg` (if `rolling=true` and no `group_by`), - `department`, `agency` (if `group_by` includes them). Invalid `period_grouping`, non-positive `months`, or invalid `group_by` values return HTTP 400 with an `error` message. ## Available endpoints | Resource | Endpoint | Identifier | | --- | --- | --- | | **Entity** | `GET /api/entities/{uei}/metrics///` | Entity UEI. See [Entities](entities.md). | | **NAICS** | `GET /api/naics/{code}/metrics///` | NAICS code. See [NAICS](naics.md). | | **PSC** | `GET /api/psc/{code}/metrics///` | PSC code. See [PSC](psc.md). | All three support the same optional query parameters: `group_by`, `fiscal_year`, `rolling`. ## Example Entity obligations for the last 12 months, by month, with rolling average: ```http GET /api/entities/ABC123DEF456/metrics/12/month/?rolling=true ``` NAICS code `541512` for the last 24 months by quarter, grouped by department: ```http GET /api/naics/541512/metrics/24/quarter/?group_by=department ``` ## SDK > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don’t yet expose first-class methods for metrics. Use the HTTP helper with the paths above: === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/entities/ABC123DEF456/metrics/12/month/", params={"rolling": "true"}, ) print("count:", data.get("count"), "results:", len(data.get("results", []))) ``` === "Node (tango-node)" ```ts 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/entities/ABC123DEF456/metrics/12/month/", { rolling: "true", }); console.log("count:", data.count, "results:", data.results?.length ?? 0); ``` --- --- description: "Filtering and response shaping for /api/naics/, including its SBA size-standard and obligation-rollup expansions." updated: 2026-05-13 --- # NAICS NAICS codes are exposed at `/api/naics/`. For field definitions, see the [NAICS Data Dictionary](../data-dictionary/naics.md). ## External references - [Official NAICS information (U.S. Census Bureau)](https://www.census.gov/naics/) - [NAICS Association (third-party reference)](https://www.naics.com/) ## Endpoints - `GET /api/naics/` (list + filtering) - `GET /api/naics/{code}/` (detail) **Metrics:** Time-series obligation/award metrics for a NAICS code: `GET /api/naics/{code}/metrics///`. See [Metrics](metrics.md) for parameters and behavior. ## Filtering | Param | What it does | | --- | --- | | `search` | Matches `code__startswith` or `description__icontains`. | | `revenue_limit` | Filter by SBA revenue size standard (in **millions** of USD). | | `revenue_limit_gte`, `revenue_limit_lte` | Revenue size standard range (in **millions**). | | `employee_limit` | Filter by SBA employee size standard. | | `employee_limit_gte`, `employee_limit_lte` | Employee size standard range. | Example: - NAICS starting with 54: `GET /api/naics/?search=54` - NAICS with revenue limit \(\le 15M\): `GET /api/naics/?revenue_limit_lte=15` ## Ordering `/api/naics/` does **not** support `ordering=...`. ## Pagination NAICS uses page-number pagination (static reference pagination defaults to larger pages): - `page` (default 1) - `limit` (default 1000, max 10000) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `code`, `description` - Expansions: - `size_standards(employee_limit,revenue_limit)` β€” SBA size standards. `revenue_limit` is in whole dollars. - `federal_obligations(total,active)` β€” obligation rollups with `awards_obligated` and `awards_count`. Default shape (list, no `?shape=` param): `code,description` Default shape (detail or `?show_limits=1`): `code,description,size_standards(*),federal_obligations(*)` **Deprecation note:** The legacy `?show_limits=1` parameter is still supported but produces the same result as `?shape=code,description,size_standards(*),federal_obligations(*)`. Prefer `?shape=` directly. ```bash # List defaults /api/naics/?shape=code,description # Full detail equivalent (replaces ?show_limits=1) /api/naics/?shape=code,description,size_standards(*),federal_obligations(*) # Size standards only /api/naics/541330/?shape=code,description,size_standards(*) # Just the total obligations /api/naics/541330/?shape=code,federal_obligations(total) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don’t yet expose a first-class `list_naics()` / `listNaics()` method. You can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get("/api/naics/", params={"search": "5415", "limit": 25}) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/naics/", { search: "5415", limit: 25 }); console.log("count:", data.count); ``` --- --- description: "Filtering, ordering, and pagination for /api/notices/, Tango's individual SAM.gov notice endpoint." tags: [notices, api, reference] updated: 2026-10-06 --- # Notices Notices are individual SAM.gov notice records exposed at `/api/notices/`. If you want β€œone row per solicitation/opportunity”, use [Opportunities](opportunities.md). For field definitions, see the [Notices Data Dictionary](../data-dictionary/notices.md). ## Endpoints - `GET /api/notices/` (list + filtering) - `GET /api/notices/{notice_id}/` (detail) ## Filtering Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day. All date filters require `YYYY-MM-DD` format; invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `search` | Full-text search over title, description, and solicitation number, ranked by relevance. Requires Small tier or above. Matches **active notices only**. | | `agency` | Filter by agency or department (vector-backed). | | `naics` | Filter by NAICS. | | `psc` | Filter by PSC. | | `set_aside` | Filter by set-aside. | | `notice_type` | Filter by notice type (valid values are validated). | | `solicitation_number` | Filter by solicitation number. Matches every spelling of the number (`N6600120R0002` or `N66001-20-R-0002`, any case). Multi-value: use `|` for OR. | | `posted_date_after`, `posted_date_before` | Posted date range (`YYYY-MM-DD`). | | `response_deadline_after`, `response_deadline_before` | Response deadline range (`YYYY-MM-DD`). | | `active` | Filter active/inactive. | ## Ordering `/api/notices/` does **not** support `ordering=...`. ## Pagination Notices use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## Response Shaping Notices support the `?shape=` query parameter. When no `?shape=` is provided, the endpoint returns a default shape. **Default shape (list):** `active,address(*),attachment_count,award_number,description,file_count,last_updated,link_count,meta(*),naics_code,notice_id,office(*),opportunity(*),place_of_performance(*),posted_date,psc_code,response_deadline,sam_url,set_aside,solicitation_number,title` **Default shape (detail):** adds `archive(*)`, `primary_contact(*)`, `secondary_contact(*)` `file_count` and `link_count` are in both default shapes from API version 5.9.0; `GET /api/version` reports what you are calling. `attachment_count` counts every attachment, including links that point somewhere else, so use `file_count` greater than 0 to tell whether a notice has documents. See [Attachments: files and links](../data-dictionary/opportunities.md#attachments-files-and-links). `set_aside` is available as a leaf (returns the description text) or as an expansion `set_aside(code,description)` for the structured form. See [Response Shaping](../guides/patterns/response-shaping.md) for syntax and examples. ### Notices shaping notes - **New leaf**: `opportunity_id` is available directly as a leaf (UUID). - **Award leaves**: `award_date`, `award_amount`, `awardee` and `awardee_uei` are available alongside `award_number`. They are filled only on award notices and are `null` otherwise; `award_amount` is a string, as SAM publishes it. None of them is in a default shape, so name them in `shape`. - **Bare expand shorthand**: common expansions can be requested without parentheses when the runtime must expand them for safety (e.g., `office` behaves like `office(*)`, and `opportunity` behaves like `opportunity(*)`). Examples: ```bash # Leaf opportunity_id + bare office/opportunity expansions /api/notices/?shape=notice_id,opportunity_id,office,opportunity&limit=1 # Award details on award notices /api/notices/?notice_type=a&shape=notice_id,title,award_number,award_date,award_amount,awardee,awardee_uei&limit=5 ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_notices( agency="DOD", notice_type="Presolicitation", limit=10, shape=ShapeConfig.NOTICES_MINIMAL, ) for n in resp.results: print(n.notice_id, n.title) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listNotices({ agency: "DOD", notice_type: "Presolicitation", limit: 10, shape: ShapeConfig.NOTICES_MINIMAL, }); for (const n of resp.results) { console.log(n.notice_id, n.title); } ``` --- --- description: "Filtering, ordering, and pagination for the deprecated /api/offices/ endpoint; new integrations should use Organizations instead." updated: 2026-05-13 --- # Offices !!! warning "Deprecated endpoint" This endpoint is deprecated. Use [Organizations](organizations.md) for the unified federal hierarchy. This endpoint will be removed in a future version. Offices are sub-agency organizations exposed at `/api/offices/`. If you need the unified Federal Hierarchy model (departments/agencies/offices all as one tree), see [Organizations](organizations.md). For field definitions, see the [Organizations Data Dictionary](../data-dictionary/organizations.md). ## Endpoints - `GET /api/offices/` (list) - `GET /api/offices/{code}/` (detail) ## Filtering | Param | What it does | | --- | --- | | `search` | Full-text search over offices (vector-backed). | ## Ordering `/api/offices/` does **not** support `ordering=...`. ## Pagination Offices use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `code`, `name`, plus flat aliases `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` - Expansions: - `agency(code,name,abbreviation)` - `department(code,name,abbreviation,description,cgac,website,congressional_justification)` Default shape (no `?shape=` param): `office_code,office_name,agency_code,agency_name,department_code,department_name` (flat aliases) ```bash # Default flat format /api/offices/?shape=office_code,office_name,agency_name # Direct leaves with nested expansion /api/offices/4700/?shape=code,name,agency(code,name,abbreviation) # Office with department details /api/offices/4700/?shape=code,name,department(name,description,website) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The SDKs don’t yet expose a first-class `list_offices()` / `listOffices()` method. You can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get("/api/offices/", params={"search": "OIG", "page": 1, "limit": 25}) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/offices/", { search: "OIG", page: 1, limit: 25 }); console.log("count:", data.count); ``` --- --- description: "Filtering, ordering, and notice-UUID resolution for /api/opportunities/, Tango's SAM.gov opportunity endpoint." tags: [opportunities, api, reference] updated: 2026-10-06 --- # Opportunities Opportunities are SAM.gov opportunities/solicitations exposed at `/api/opportunities/` (with a latest-notice pointer and history behind the scenes). For field definitions, see the [Opportunities Data Dictionary](../data-dictionary/opportunities.md). ## Endpoints - `GET /api/opportunities/` (list + filtering + search + ordering) - `GET /api/opportunities/{opportunity_id}/` (detail) ## Notice UUID Resolution If you pass a **notice UUID** (instead of an opportunity UUID) to the detail endpoint, the API automatically redirects (HTTP 302) to the parent opportunity. This is useful when you have a subsequent notice UUID (e.g., from an amendment) and want to reach the parent opportunity directly. ```bash # Using a notice UUID redirects to the parent opportunity GET /api/opportunities/{notice_id}/ β†’ 302 /api/opportunities/{opportunity_id}/ ``` If the notice UUID has no parent opportunity, the endpoint returns 404. ## Filtering Swagger is the canonical list of query parameters. These are the core filters most people use day-to-day. All date filters require `YYYY-MM-DD` format; invalid dates or inverted ranges return **400**. See [Date filters](shared.md#date-filters). | Param | What it does | | --- | --- | | `search` | Search across notice metadata (title, description, etc.) and the text of attached solicitation documents. Hybrid keyword + semantic matching: results that literally match your terms rank ahead of results found only by meaning. | | `agency` | Filter by agency or department (vector-backed). | | `naics` | Filter by NAICS. | | `psc` | Filter by PSC. | | `set_aside` | Filter by set-aside. | | `notice_type` | Filter by notice type (valid values are validated). | | `solicitation_number` | Filter by solicitation number. Matches every spelling of the number (`N6600120R0002` or `N66001-20-R-0002`, any case). Multi-value: use `|` for OR. | | `first_notice_date_after`, `first_notice_date_before` | First notice date range (inclusive, `YYYY-MM-DD`). | | `last_notice_date_after`, `last_notice_date_before` | Last notice date range (inclusive, `YYYY-MM-DD`). | | `response_deadline_after`, `response_deadline_before` | Response deadline range (inclusive, `YYYY-MM-DD`). | | `place_of_performance` | Full-text-ish filter over place-of-performance text. | | `active` | Filter active/inactive (default true). | | `awarded` | `true` for opportunities that carry an award or have award notices linked back to them; `false` for the rest. See [Awards](#awards). | | `awardee_uei` | Filter by the awardee UEI on the opportunity's own award notice. Case-insensitive. Multi-value: use `|` for OR. | ### Active-only by default A list request returns **active opportunities only** unless it sends `active`, `solicitation_number`, `notice_type`, `award_number`, `awarded` or `awardee_uei` β€” any of which widens the request (including `search`) to the full dataset. Send `active=true` alongside them to keep the active-only scope. ### Multi-value filter syntax Use `|` (or the literal word `OR`) to match any of several values: ``` naics=541511|541512 agency=DOD|GSA ``` The same syntax works on every filter that accepts multiple values. ### Search snippets On a `?search=` request, a result row carries an extra `snippet` field when one of its attached documents yields a matching excerpt: a short passage from the best-matching attachment, with the matched terms wrapped in HTML `` tags. Rows with no matching attachment text omit the field. ```json { "opportunity_id": "…", "title": "Cybersecurity Support Services", "snippet": "...requirements for cybersecurity incident response and vulnerability management across...", … } ``` - The excerpt is one fragment of roughly 15–35 words around the densest cluster of matched terms, with `...` marking text cut before or after it. - `snippet` is accepted in `shape=`, but listing it changes nothing: it is added after shaping whenever applicable, and only if the shape includes `opportunity_id`, which is how a snippet is matched to its row. - A snippet is a convenience, not part of the match. If the excerpt lookup fails, the search still returns its results, just without `snippet`. ## Ordering Opportunities support `ordering=` with a strict allowlist: - `first_notice_date` (alias: `posted_date`) - `last_notice_date` - `response_deadline` Examples: - Newest posted first: `GET /api/opportunities/?ordering=-posted_date` - Soonest deadline first: `GET /api/opportunities/?ordering=response_deadline` Note: if you use `search` **without** an explicit `ordering=...`, results default to relevance ordering (rank). ## Pagination Opportunities use page-number pagination (`page`, `limit`) and return `next`/`previous` URLs. ## Response Shaping Opportunities support the `?shape=` query parameter. When no `?shape=` is provided, the endpoint returns a default shape. **Default shape (list):** `active,award_number,awarded,first_notice_date,last_notice_date,meta(*),naics_code,office(*),opportunity_id,place_of_performance(*),psc_code,response_deadline,sam_url,set_aside,solicitation_number,title` **Default shape (detail):** `active,attachments(attachment_id,file_size,mime_type,name,posted_date,resource_id,type,url),award_amount,award_count,award_date,award_number,awarded,awardee,awardee_uei,awards(*),description,first_notice_date,last_notice_date,meta(*),naics_code,notice_history(*),office(*),opportunity_id,place_of_performance(*),primary_contact(*),psc_code,response_deadline,sam_url,set_aside,solicitation_number,solicitation_opportunity_id,title` Compared with the list default, the detail default adds `attachments(...)`, the award fields (see [Awards](#awards)), `description`, `notice_history(*)`, `primary_contact(*)` and `solicitation_opportunity_id`. The default `attachments(...)` expansion lists `attachment_id, file_size, mime_type, name, posted_date, resource_id, type, url` β€” note that the **`doc_role`, `doc_role_alt` and `extracted_text` sub-fields are Pro+ tier** and are *not* in the default. Free-tier callers who request one receive the response without it plus a `meta.upgrade_hints` entry. None of the three is returned by `attachments(*)` β€” name them explicitly. Not every attachment is a document. Each row's `type` is `file` (a document, the only kind with extracted text and a document role) or `link` (a URL pointing somewhere else), and `meta.attachments_count` counts both. From API version 5.9.0, `meta(*)` also carries `files_count` and `links_count`. `meta.files_count` greater than 0 means the opportunity has documents, 0 means it has none, and `null` means not yet counted. See [Attachments: files and links](../data-dictionary/opportunities.md#attachments-files-and-links) for the definitions, the `null` case and a worked example. ### Document roles `doc_role` says what job a document does inside its solicitation package, so you can decide which attachments are worth opening (or worth sending to a model) without downloading them: | Value | What it means | | --- | --- | | `requirement` | What the government wants β€” statements of work, specifications, drawings of the work to be performed | | `instructions` | How to bid β€” submission instructions, forms to fill in, evaluation criteria | | `pricing` | Where the money goes β€” schedules, line-item worksheets, wage determinations | | `terms` | The deal's conditions β€” clauses, representations and certifications, contract terms | | `reference` | Context rather than obligation β€” existing-conditions drawings, amendments' cover pages, background material | | `unknown` | The classifier could not read enough of the document to decide | `doc_role_alt` carries a runner-up label when the classifier saw a close second, and is absent otherwise. An attachment the classifier has not reached yet omits both keys rather than returning null. ```http GET /api/opportunities/{id}/?shape=title,attachments(name,doc_role) ``` ### Awards SAM.gov posts a contract award as a separate award notice, which appears in Tango as its own opportunity. The award details (`award_date`, `award_amount`, `awardee`, `awardee_uei`) are filled only where SAM has posted an award notice and are `null` otherwise. | Field | What it holds | | --- | --- | | `awarded` | Boolean. `true` when the opportunity carries an award number or has award notices linked back to it; never `null`. | | `award_number`, `award_date`, `award_amount`, `awardee`, `awardee_uei` | The award as posted on this opportunity's own award notice. `award_date`, `award_amount`, `awardee` and `awardee_uei` always come from the same notice. `award_amount` is a string, as SAM publishes it. | | `solicitation_opportunity_id` | On an award, the `opportunity_id` of the solicitation it was made under; `null` when the award is unlinked. | | `award_count` | On a solicitation, the total number of award opportunities linked back to it (not capped); `null` when none are linked. | | `awards(...)` | On a solicitation, up to ten of the most recent linked awards, each `{opportunity_id, notice_id, award_number, award_date, award_amount, awardee, awardee_uei}`. Use `award_count` for the total. | An award is linked to its solicitation only when SAM's award notice references that solicitation. An award notice posted without that reference stays unlinked: it still carries its own award fields, but has no `solicitation_opportunity_id` and does not count toward any solicitation's `award_count`. `awarded` does not change what `active` means. An award can be posted while its solicitation is still open β€” multiple-award vehicles are the common case β€” so an opportunity can be both `active` and `awarded`. ```bash # Awards made to one vendor, across the full dataset /api/opportunities/?awardee_uei=ABC123XYZ456&shape=opportunity_id,title,award_date,award_amount,solicitation_opportunity_id # A solicitation and the awards linked to it /api/opportunities/{opportunity_id}/?shape=opportunity_id,title,awarded,award_count,awards(*) ``` The `office(*)` expansion is the canonical 7-key office payload β€” `organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name` β€” same shape used on awards, vehicles, forecasts, grants, IT Dashboard, and protests. `set_aside` is available as a leaf (returns the code string) or as an expansion `set_aside(code,description)` for the full label. See [Response Shaping](../guides/patterns/response-shaping.md) for syntax and examples. ### Opportunities shaping notes - **New leaves**: `latest_notice_id`, `archive_date`, plus relation id leaves `agency_id`, `department_id`, `office_id`. - **New expansions**: `agency(*)`, `department(*)`, `latest_notice(notice_id,link)`. - **File and link counts**: `meta(files_count,links_count)` alongside `meta(attachments_count)`, from API version 5.9.0. See [Attachments: files and links](../data-dictionary/opportunities.md#attachments-files-and-links). - **Award leaves and expansion**: `awarded`, `award_date`, `award_amount`, `awardee`, `awardee_uei`, `award_count`, `solicitation_opportunity_id`, and `awards(opportunity_id,notice_id,award_number,award_date,award_amount,awardee,awardee_uei)`. See [Awards](#awards). - **Bare expand shorthand**: common expansions can be requested without parentheses when the runtime must expand them for safety (e.g., `office` behaves like `office(*)`, and `attachments` behaves like `attachments(*)`). Examples: ```bash # Include latest notice pointer + org expansions /api/opportunities/?shape=opportunity_id,title,latest_notice_id,latest_notice(*),agency(*),department(*),office&limit=1 # Attachments without specifying subfields (shorthand) /api/opportunities/{opportunity_id}/?shape=opportunity_id,title,attachments ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). ### Search opportunities (with shaping) === "Python (tango-python)" ```python import os from tango import ShapeConfig, TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_opportunities( search="cybersecurity", agency="DOD", limit=10, shape=ShapeConfig.OPPORTUNITIES_MINIMAL, ) for o in resp.results: print(o.opportunity_id, o.title) ``` === "Node (tango-node)" ```ts import { ShapeConfig, TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listOpportunities({ search: "cybersecurity", agency: "DOD", limit: 10, shape: ShapeConfig.OPPORTUNITIES_MINIMAL, }); for (const o of resp.results) { console.log(o.opportunity_id, o.title); } ``` --- --- description: "Filtering, response shaping, and lookups for /api/organizations/, Tango's unified federal hierarchy endpoint." tags: [organizations, api, reference] updated: 2026-05-26 --- # Organizations Organizations are the unified Federal Hierarchy model exposed at `/api/organizations/` (departments, agencies, offices, and other intermediate nodes). If you’re looking for field definitions, see the [Organizations Data Dictionary](../data-dictionary/organizations.md). ## Endpoints - `GET /api/organizations/` (list + filtering + search) - `GET /api/organizations/{identifier}/` (detail β€” accepts either an integer Federal Hierarchy key or a UUID primary key) ## Filtering | Param | What it does | | --- | --- | | `search` | Multi-stage org search (aliases β†’ trigram β†’ full-text β†’ fuzzy). | | `type` | Filter by organization type (lenient allowlist; invalid values are ignored + warnings may be returned). | | `level` | Filter by hierarchy level (1 = department, 2 = agency, etc.). | | `cgac` | Filter by CGAC code. | | `parent` | Filter by parent organization (accepts organization key or common names/abbreviations). | | `include_inactive` | Include inactive orgs in list results (default false). Detail lookups always return the org regardless of active status. | ## Response shaping Organizations support `shape=...` (see [Response Shaping](../guides/patterns/response-shaping.md)). **Default shape** (no `?shape=` param): `key, fh_key, name, short_name, type, level, is_active, code, fpds_code, cgac, canonical_code, parent_fh_key, full_parent_path_name` All responses go through the shaping pipeline, even without a `?shape=` parameter. **Root fields** available via shaping: | Field | Description | | --- | --- | | `key` | Tango's internal UUID primary key. | | `fh_key` | Zero-padded 9-character string (e.g., `"000000001"`). Accepted for detail lookups alongside `key` (UUID). | | `name` | Full official name. | | `short_name` | Abbreviation or common name (e.g., `"DOD"`). | | `type` | Organization type (`DEPARTMENT`, `AGENCY`, `OFFICE`, etc.). | | `level` | Hierarchy depth (1 = department). | | `is_active` | Whether the organization is currently active. | | `code` | Office or agency code. | | `fpds_code` | FPDS 4-digit agency code. | | `cgac` | CGAC 3-character code. | | `canonical_code` | Level-prefixed canonical code (e.g., `"L1:097"`). | | `fpds_org_id` | FPDS organization identifier. | | `aac_code` | Activity Address Code. | | `parent_fh_key` | Parent's `fh_key` (zero-padded). | | `full_parent_path_name` | Human-readable hierarchy path. | | `l1_fh_key` .. `l8_fh_key` | Ancestor `fh_key` at each hierarchy level (zero-padded). | | `start_date` | Organization start date from Federal Hierarchy. | | `end_date` | Organization end date from Federal Hierarchy. | | `logo` | Logo URL, when available. | | `summary` | Short description or mission summary. | | `mod_status` | Modification status (`ACTIVE`, `INACTIVE`). | | `description` | Organization description. | | `obligations` | Total rolled-up obligations (alias for `tree_obligations`). | | `total_obligations` | Direct obligations for this organization. | | `tree_obligations` | Obligations for the entire subtree. | | `obligation_rank` | Percentile ranking (1–100) by obligations. | **Expansions:** | Expand | Fields | Notes | | --- | --- | --- | | `parent(...)` | `key`, `fh_key`, `name`, `short_name`, `type`, `level`, `is_active`, `code`, `cgac` | Immediate parent org. | | `ancestors(...)` | `fh_key`, `name`, `short_name`, `level` | All ancestors from L1 down to immediate parent. | | `children(...)` | `key`, `fh_key`, `name`, `short_name`, `type`, `level`, `is_active`, `code`, `cgac` | Immediate child organizations. | | `department(...)` | `code`, `name`, `abbreviation` | L1 ancestor as a department. Returns `null` for level 1 orgs (they are the department). | | `agency(...)` | `code`, `name`, `abbreviation` | L2 ancestor as an agency. Returns `null` for level 1 and 2 orgs (no agency above them). | | `budget_appropriation(...)` | `scope`, `cgac`, `fiscal_year`, `n_accounts`, `summary`, `top_accounts` | **Beta.** Department-level appropriation rollup keyed by the org's CGAC. `scope` is `"self"` for L1 orgs (the org is the dept) and `"department"` for L2+ (totals describe the parent dept; sub-orgs inherit the dept's CGAC). When summing across siblings, filter on `scope == "self"` to avoid double-counting. Supports `[fiscal_year=YYYY]` bracket param. See [Budget](budget.md). | | `budget_spending(...)` | `organization_id`, `fiscal_year`, `n_orgs_in_rollup`, `summary`, `top_accounts` | **Beta.** Funding-office spending rollup across the org's subtree (self + descendants via FH). Returns `null` when nothing in the subtree has funding-office activity. Supports `[fiscal_year=YYYY]` bracket param. See [Budget](budget.md). | ```bash # Default response (no shape param) /api/organizations/ # Select specific fields /api/organizations/?shape=fh_key,name,type,level # Include department and agency expands /api/organizations/?shape=fh_key,name,department(code,name),agency(code,name,abbreviation) # Include enriched ancestors /api/organizations/?shape=fh_key,name,ancestors(fh_key,name,short_name,level) ``` !!! note "`department` and `agency` expand level behavior" The `department` expand returns `null` for level 1 organizations (a department doesn't have a department β€” it is one). The `agency` expand returns `null` for level 1 or 2 organizations (departments and agencies don't have an agency above them). This means list responses with mixed levels work without errors. ## Ordering `/api/organizations/` does **not** support `ordering=...`. (Results are returned in a stable way; searches preserve their own relevance ordering, and non-search lists are returned in a consistent key order.) ## Pagination Organizations use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_organizations( search="Treasury", type="DEPARTMENT|AGENCY", include_inactive=False, limit=25, ) print("count:", resp.count) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listOrganizations({ search: "Treasury", type: "DEPARTMENT|AGENCY", include_inactive: false, limit: 25, }); console.log("count:", resp.count); ``` --- --- description: "Filtering, ordering, and pagination for /api/otas/, Tango's Other Transaction Agreement endpoint." updated: 2026-05-13 --- # OTAs OTAs (Other Transaction Awards) are awards exposed at `/api/otas/`. For field definitions, see the [OTAs Data Dictionary](../data-dictionary/otas.md). ## Endpoints - `GET /api/otas/` (list + filtering + search + ordering) - `GET /api/otas/{key}/` (detail) Entity-scoped list: - `GET /api/entities/{uei}/otas/` (behaves like `/api/otas/` scoped to an entity) ## Filtering OTAs share most of the "award" filtering surface with contracts/IDVs, except they do not support some contracts-specific filters (like NAICS). Common filters you can use: | Param | What it does | | --- | --- | | `search` | Full-text-ish search over award search vectors. | | `recipient` | Search by recipient/vendor name. | | `uei` | Filter by recipient UEI (exact). | | `piid` | Filter by PIID (case-insensitive). | | `awarding_agency`, `funding_agency` | Filter by awarding/funding agency (best-effort matching). | | `psc` | Filter by PSC. | | `award_date`, `award_date_gte`, `award_date_lte` | Award date filters. | | `fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year filters. | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance start date range (when present). | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance end date range (when present). | | `expiring_gte`, `expiring_lte` | Expiration window range filters. | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | | `ordering` | Sort results (allowlist: `award_date`, `obligated`, `total_contract_value`; prefix with `-` for descending). | ## Ordering OTAs support `ordering=` with a strict allowlist: - `award_date` - `obligated` - `total_contract_value` Examples: - Newest first: `GET /api/otas/?ordering=-award_date` - Largest obligations first: `GET /api/otas/?ordering=-obligated` ## Pagination High-volume award endpoints use **cursor-based (keyset) pagination**: - `limit` - `cursor` (follow `next` / `previous` URLs) ## Response Shaping OTA endpoints support the `?shape=` parameter for customizing response fields. See [Response Shaping](../guides/patterns/response-shaping.md) for full syntax. ### Shapeable fields | Field | Type | Notes | | --- | --- | --- | | `key` | scalar | Award key | | `piid` | scalar | | | `award_date` | scalar | | | `award_type` | scalar or expand | Expandable to `{code, description}` (OTA-specific: "O" = Other Transaction Non-Research, "R" = Other Transaction for Research) | | `fiscal_year` | scalar | | | `obligated` | scalar | | | `total_contract_value` | scalar | | | `description` | scalar | | | `base_and_exercised_options_value` | scalar | | | `psc_code` | scalar | | | `consortia` | scalar | | | `consortia_uei` | scalar | | | `dod_acquisition_program` | scalar | | | `non_governmental_dollars` | scalar | | | `non_traditional_government_contractor_participation` | scalar | | | `parent_award_modification_number` | scalar | | | `type_of_ot_agreement` | scalar or expand | Expandable to `{code, description}` | | `extent_competed` | scalar or expand | Expandable to `{code, description}` | | `transactions` | scalar | Raw snapshot list | ### Expandable fields | Expand | Fields | | --- | --- | | `recipient(*)` | `uei`, `display_name`, `legal_business_name`, `cage`, `duns` | | `place_of_performance(*)` | `country_code`, `country_name`, `state_code`, `state_name`, `city_name`, `zip_code` | | `awarding_office(*)` | `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `funding_office(*)` | same as `awarding_office` | | `parent_award(key,piid)` | `key`, `piid` | | `period_of_performance(*)` | `start_date`, `current_end_date`, `ultimate_completion_date` | | `transactions(*)` | `modification_number`, `transaction_date`, `obligated`, `description`, `action_type` | | `psc(*)` | `code`, `description` | | `award_type(*)` | `code`, `description` (OTA-specific choices) | | `type_of_ot_agreement(*)` | `code`, `description` | | `extent_competed(*)` | `code`, `description` | ### Examples Request only key fields: ``` GET /api/otas/?shape=key,piid,award_date,obligated ``` Expand recipient and extent competed with description: ``` GET /api/otas/?shape=key,piid,recipient(uei,display_name),extent_competed(code,description) ``` Expand type of OT agreement: ``` GET /api/otas/?shape=key,type_of_ot_agreement(code,description) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose a first-class `list_otas()` / `listOTAs()` method. You can still call the endpoint via the SDK's internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/otas/", params={"search": "DARPA", "ordering": "-award_date", "limit": 10}, ) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/otas/", { search: "DARPA", ordering: "-award_date", limit: 10, }); console.log("count:", data.count); ``` --- --- description: "Filtering, ordering, and pagination for /api/otidvs/, Tango's Other Transaction IDV endpoint." updated: 2026-05-13 --- # OTIDVs OTIDVs (Other Transaction IDVs) are awards exposed at `/api/otidvs/`. For field definitions, see the [OTIDVs Data Dictionary](../data-dictionary/otidvs.md). ## Endpoints - `GET /api/otidvs/` (list + filtering + search + ordering) - `GET /api/otidvs/{key}/` (detail) - `GET /api/otidvs/{key}/awards/` (child OTAs under an OTIDV; behaves like `/api/otas/` scoped to the OTIDV) Entity-scoped list: - `GET /api/entities/{uei}/otidvs/` (behaves like `/api/otidvs/` scoped to an entity) ## Filtering OTIDVs share most of the "award" filtering surface with contracts/IDVs, except they do not support some contracts-specific filters (like NAICS). Common filters you can use: | Param | What it does | | --- | --- | | `search` | Full-text-ish search over award search vectors. | | `recipient` | Search by recipient/vendor name. | | `uei` | Filter by recipient UEI (exact). | | `piid` | Filter by PIID (case-insensitive). | | `awarding_agency`, `funding_agency` | Filter by awarding/funding agency (best-effort matching). | | `psc` | Filter by PSC. | | `award_date`, `award_date_gte`, `award_date_lte` | Award date filters. | | `fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year filters. | | `pop_start_date_gte`, `pop_start_date_lte` | Period of performance start date range (when present). | | `pop_end_date_gte`, `pop_end_date_lte` | Period of performance end date range (when present). | | `expiring_gte`, `expiring_lte` | Expiration window range filters. | | `obligated_gte`, `obligated_lte` | Obligated amount range (USD). | | `ordering` | Sort results (allowlist: `award_date`, `obligated`, `total_contract_value`; prefix with `-` for descending). | ## Ordering OTIDVs support `ordering=` with a strict allowlist: - `award_date` - `obligated` - `total_contract_value` Examples: - Newest first: `GET /api/otidvs/?ordering=-award_date` - Largest obligations first: `GET /api/otidvs/?ordering=-obligated` ## Pagination High-volume award endpoints use **cursor-based (keyset) pagination**: - `limit` - `cursor` (follow `next` / `previous` URLs) ## Response Shaping OTIDV endpoints support the `?shape=` parameter for customizing response fields. See [Response Shaping](../guides/patterns/response-shaping.md) for full syntax. ### Shapeable fields | Field | Type | Notes | | --- | --- | --- | | `key` | scalar | Award key | | `piid` | scalar | | | `award_date` | scalar | | | `idv_type` | scalar | Raw code | | `fiscal_year` | scalar | | | `obligated` | scalar | | | `total_contract_value` | scalar | | | `description` | scalar | | | `base_and_exercised_options_value` | scalar | | | `psc_code` | scalar | | | `consortia` | scalar | | | `consortia_uei` | scalar | | | `dod_acquisition_program` | scalar | | | `non_governmental_dollars` | scalar | | | `non_traditional_government_contractor_participation` | scalar | | | `type_of_ot_agreement` | scalar or expand | Expandable to `{code, description}` | | `extent_competed` | scalar or expand | Expandable to `{code, description}` | | `transactions` | scalar | Raw snapshot list | ### Expandable fields | Expand | Fields | | --- | --- | | `recipient(*)` | `uei`, `display_name`, `legal_business_name`, `cage`, `duns` | | `place_of_performance(*)` | `country_code`, `country_name`, `state_code`, `state_name`, `city_name`, `zip_code` | | `awarding_office(*)` | `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` | | `funding_office(*)` | same as `awarding_office` | | `period_of_performance(*)` | `start_date`, `current_end_date`, `ultimate_completion_date` | | `transactions(*)` | `modification_number`, `transaction_date`, `obligated`, `description`, `action_type` | | `psc(*)` | `code`, `description` | | `type_of_ot_agreement(*)` | `code`, `description` | | `extent_competed(*)` | `code`, `description` | ### Examples Request only key fields: ``` GET /api/otidvs/?shape=key,piid,award_date,obligated ``` Expand recipient and extent competed with description: ``` GET /api/otidvs/?shape=key,piid,recipient(uei,display_name),extent_competed(code,description) ``` Expand type of OT agreement: ``` GET /api/otidvs/?shape=key,type_of_ot_agreement(code,description) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don't yet expose a first-class `list_otidvs()` / `listOTIDVs()` method. You can still call the endpoint via the SDK's internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/otidvs/", params={"search": "DARPA", "ordering": "-award_date", "limit": 10}, ) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/otidvs/", { search: "DARPA", ordering: "-award_date", limit: 10, }); console.log("count:", data.count); ``` --- --- description: "Filtering and coverage notes for /api/protests/, Tango's GAO, COFC and SBA OHA bid protest endpoint." tags: [protests, api, reference] updated: 2026-09-29 --- # Protests Protests are bid protest records exposed at `/api/protests/`. For field definitions, see the [Protests Data Dictionary](../data-dictionary/protests.md). A bid protest challenges an award or a solicitation β€” who should have won. A dispute *under* a contract already awarded goes to a different forum entirely: see [Contract appeals](contract-appeals.md) for the Contract Disputes Act decisions of the CBCA and the ASBCA. The two resources share no records. **Authentication**: Protests endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. **Coverage**: The API covers protest decisions from **2015 onward** for GAO and SBA OHA. COFC coverage starts in 2026 and moves forward, and COFC records leave several filterable fields empty β€” see the [Data Dictionary](../data-dictionary/protests.md#overview). ## Endpoints - `GET /api/protests/` (list + filtering + search + pagination) - `GET /api/protests/{case_id}/` (detail by deterministic case UUID) Both list and detail return **case-level** objects identified by `case_id` (a deterministic UUID derived from `source_system` + `base_case_number`). Subordinate dockets are available via `?shape=...,dockets(...)` expansion. The path segment must be a valid RFC 4122 UUID (version 1–5, variant 8/9/a/b). ## Filtering Core filters: | Param | What it does | | --- | --- | | `source_system` | Filter by source system (`gao`, `cofc`, or `sba_oha`). Multi-value: use `|` for OR. | | `outcome` | Filter by protest outcome (for example `Denied`, `Dismissed`, `Withdrawn`, `Sustained`; SBA OHA also returns `Granted`, `Remanded`, `Reversed`, `Vacated`). COFC records carry an outcome only once the court issues an opinion. Multi-value: use `|` for OR. | | `case_type` | Filter by case type (for example `Bid Protest`, `Bid Protest: Cost`; SBA OHA uses `SIZE`, `NAICS`, `VSBC`, `CVE`, `BDPE`, and others). Multi-value: use `|` for OR. | | `agency` | Filter by protested agency text. COFC records carry an agency only once the court issues an opinion. Multi-value: use `|` for OR. | | `case_number` | Filter by case number (B-number, for example `b-423274`). Multi-value: use `|` for OR. | | `solicitation_number` | Filter by solicitation number. Matches every spelling of the number (`W91RUS22R0082` or `W91RUS-22-R-0082`, any case). Multi-value: use `|` for OR. | | `naics_code` | Filter by the NAICS code at issue, for example `541512`. Populated only on SBA OHA size and NAICS appeals. | | `protester` | Filter by protester name text. Multi-value: use `|` for OR. | | `filed_date_after`, `filed_date_before` | Filed date range filters. Bounded by the 2015 coverage floor. | | `decision_date_after`, `decision_date_before` | Decision date range filters. Bounded by the 2015 coverage floor. | | `search` | Full-text search over protest searchable fields. | ## Ordering Protests do not support custom ordering via `ordering=`. Results are returned in a fixed timeline order: - `decision_date` when present, otherwise `filed_date` (newest first) - UUID descending as a deterministic tie-breaker If `ordering` is provided, the API returns HTTP 400. ## Pagination Protests use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## List response: one result per case The list endpoint returns **one result per case** (distinct `base_case_number`), not one per docket. Each result includes case-level fields from the most recent docket in the case. `case_id` is a deterministic UUID from `(source_system, base_case_number)` used for grouping and detail lookup. Pagination and filters apply to dockets first; results are then grouped, so `count` is the total number of matching **cases** across all pages. The default (unshaped) response does **not** include nested dockets. To get dockets, use the `dockets` expansion via `?shape=...,dockets(...)`. ## Detail response: case-level The detail endpoint (`GET /api/protests/{case_id}/`) returns a single **case-level** object, the same structure as a list item. Use `?shape=...,dockets(...)` to include nested dockets. ## Shaping Protests support `shape` on both list and detail endpoints: - `GET /api/protests/?shape=...` - `GET /api/protests/{case_id}/?shape=...` Both list and detail return case-level objects. You can request case-level fields and the `dockets` expansion (e.g. `shape=case_id,case_number,title,dockets(case_number,docket_number,filed_date)`). Allowed shape fields (case-level for both list and detail): - `case_id` (deterministic case UUID; use for detail lookup) - `source_system`, `case_number` (base B-number), `title`, `protester`, `agency` - `solicitation_number`, `case_type`, `outcome` - `filed_date`, `posted_date`, `decision_date`, `due_date` - `docket_url`, `decision_url` - `digest` (opt-in only; from `raw_data.digest`, e.g. decision summary text) - `challenged_party`, `naics_code`, `size_standard`, `outcome_reason`, `judge` (opt-in only; populated on SBA OHA decisions, null on GAO and COFC) - `dockets` (expand with docket fields, e.g. `dockets(case_number,docket_number,filed_date)`) - `organization` (expand: deterministic resolution of the protested agency to a canonical Tango organization β€” included in the **default** response shape; canonical 7-key office payload) - `resolved_protester` (expand: Bayesian entity resolution for the protester name; **Pro+ tier**) - `resolved_agency` (expand: Bayesian organization resolution for the agency name; **Pro+ tier**) Allowed shape fields inside `dockets(...)`: - `source_system`, `case_number` (base B-number), `docket_number` (specific docket, e.g. `b-424046.1`) - `title`, `protester`, `agency`, `solicitation_number`, `case_type`, `outcome` - `filed_date`, `posted_date`, `decision_date`, `due_date` - `docket_url`, `decision_url` - `digest` - `challenged_party`, `naics_code`, `size_standard`, `outcome_reason`, `judge` The `case_number` field (e.g. `b-424214`) identifies the case. The `docket_number` field (e.g. `b-424214.1`, `b-424214.2`) identifies the specific sub-docket within a case and is only available inside `dockets(...)`. ### Organization (deterministic): `organization(...)` The default response shape includes an `organization(*)` expansion: the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`) resolved deterministically at ingest time to a canonical Tango organization. This is the same payload used on awards, opportunities, vehicles, forecasts, grants, and IT Dashboard responses. The deterministic `organization` expand and the Bayesian `resolved_agency` expand **coexist** intentionally: - `organization` is the canonical "what does our matching pipeline think?" answer β€” fast, cached, and suitable for joining against the rest of your data. - `resolved_agency` (Pro+) carries `match_confidence` (`"confident"` / `"review"`) and a human-readable `rationale`. Useful when you need to know *why* a particular org was chosen or to surface review-worthy matches to a human. When the two disagree, prefer `organization` for canonical use and consult `resolved_agency.match_confidence` / `.rationale` to understand the discrepancy. ### Entity Resolution: `resolved_protester(...)` When a protester name has been resolved to a canonical entity in Tango, you can expand the match via `resolved_protester(...)`. Only high-confidence (`confident`) and medium-confidence (`review`) matches are returned; unresolved or low-confidence names return `null`. Allowed fields inside `resolved_protester(...)`: - `uei` β€” Unique Entity Identifier of the matched entity - `name` β€” Display name of the matched entity - `match_confidence` β€” `"confident"` (auto-linkable) or `"review"` (needs human review) - `rationale` β€” Human-readable explanation of why the match was made ### Organization Resolution: `resolved_agency(...)` When an agency name has been resolved to a canonical organization in Tango, you can expand the match via `resolved_agency(...)`. Same confidence rules as `resolved_protester`. Allowed fields inside `resolved_agency(...)`: - `key` β€” UUID key of the matched organization - `name` β€” Display name of the matched organization - `match_confidence` β€” `"confident"` or `"review"` - `rationale` β€” Human-readable explanation Not exposed in the API (internal only): - `raw_data`, `field_provenance`, `external_id`, `data_quality`, `source_last_updated`, `created`, `modified` - internal search/index fields (for example `search_vector`) Examples: ```bash # Case-level fields and nested dockets GET /api/protests/?shape=case_id,case_number,title,dockets(case_number,docket_number,filed_date,outcome) # Case-level only GET /api/protests/?shape=case_id,source_system,case_number,title,outcome,filed_date ``` More examples: ```bash # Timeline-focused list payload GET /api/protests/?source_system=gao&shape=case_id,title,outcome,filed_date,decision_date # Link-focused payload GET /api/protests/?shape=case_id,docket_url,decision_url # Detail by case UUID with shaped response GET /api/protests/550e8400-e29b-41d4-a716-446655440000/?shape=case_id,source_system,title,agency,protester,filed_date,decision_date # Detail with nested dockets GET /api/protests/550e8400-e29b-41d4-a716-446655440000/?shape=case_id,title,dockets(docket_number,filed_date,outcome) # Entity resolution for protester GET /api/protests/?shape=case_id,protester,resolved_protester(*) # Organization resolution for agency GET /api/protests/?shape=case_id,agency,resolved_agency(*) # Selective resolution fields GET /api/protests/?shape=case_id,resolved_protester(uei,match_confidence) ``` Notes: - Use the `dockets` expansion to request nested docket fields (e.g. `dockets(docket_number,case_number)`). - `*` is only valid inside expansions. Use explicit field lists at the root. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "Filtering and response options for /api/psc/, the Product and Service Code reference endpoint." updated: 2026-05-13 --- # Product and Service Code (PSC) Product and Service Code (PSC) reference data is exposed at `/api/psc/`. For field definitions, see the [PSC Data Dictionary](../data-dictionary/psc.md). ## External references - [Product and Service Code Manual](https://www.acquisition.gov/psc-manual) ## Endpoints - `GET /api/psc/` (list) - `GET /api/psc/{code}/` (detail) **Metrics:** Time-series obligation/award metrics for a PSC code: `GET /api/psc/{code}/metrics///`. See [Metrics](metrics.md) for parameters and behavior. ## Filtering | Param | What it does | | --- | --- | | `has_awards` | If truthy, restrict to PSCs that appear in award data. | Response options: | Param | What it does | | --- | --- | | `complete` | If truthy, returns a β€œcomplete” representation (serializer context-dependent). | ## Ordering `/api/psc/` does **not** support `ordering=...`. ## Pagination PSC uses page-number pagination (static reference pagination defaults to larger pages): - `page` (default 1) - `limit` (default 1000, max 10000) **Note:** Reference-data endpoints like `/api/psc/` allow larger page sizes than transactional award endpoints because the underlying datasets are relatively small and static, and larger pages reduce client round-trips. ## Response shaping This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. - Leaves: `code`, `parent`, `category`, `level_1_category`, `level_1_category_code`, `level_2_category`, `level_2_category_code` - Expansions: - `current(name,active,start_date,end_date,description,includes,excludes)` β€” active or latest description - `historical(name,active,start_date,end_date,description,includes,excludes)` β€” all descriptions Default shape (no `?shape=` param): `code,current(*),parent,category,level_1_category,level_1_category_code,level_2_category,level_2_category_code` ```bash # Just code and current description name /api/psc/?shape=code,current(name) # Code with current and historical descriptions /api/psc/AD12/?shape=code,current(name,active),historical(name,active) ``` ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The official SDKs don’t yet expose a first-class `list_psc()` / `listPsc()` method. You can still call the endpoint via the SDK’s internal HTTP helper. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get("/api/psc/", params={"has_awards": "true", "limit": 25}) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/psc/", { has_awards: "true", limit: 25 }); console.log("count:", data.count); ``` --- --- description: "The request and response contract for POST /api/resolve/, Tango's free-text entity and organization name resolver." updated: 2026-08-18 --- # Name Resolution Resolve an entity or organization name to ranked candidates using Tango's Bayesian resolver. This endpoint is useful for data enrichment workflows, entity linking, and research. **Endpoint**: `POST /api/resolve/` ## Overview Given a name and target type, the endpoint returns a ranked list of entity or organization candidates. Results are ranked by quality and filtered based on your access tier: - **Free tier**: Up to 3 candidates (identifier and display name only) - **Pro tier and above**: Up to 5 candidates (includes match quality tier) The resolver learns from location context (state, city), industry signals (NAICS, PSC codes), and any additional information you provide in the `context` field. More context typically leads to better matches. **Authentication required:** API key or OAuth2 token (all callers must be authenticated; unauthenticated requests receive HTTP 401). **Rate limiting**: Standard API rate limits apply (no additional premium throttling for this endpoint). ## Request ```http POST /api/resolve/ Content-Type: application/json X-API-KEY: { "name": "Lockheed Martin", "target_type": "entity", "state": "MD", "city": "Bethesda", "context": "fighter aircraft maintenance, NAICS 336411" } ``` ### Request body fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Name to resolve (must be non-blank). | | `target_type` | string | Yes | Type of target: `"entity"` or `"organization"`. | | `state` | string | No | 2-letter state code (e.g., `"MD"`, `"CA"`). | | `city` | string | No | City name. | | `context` | string | No | Freeform text with additional context for better matching. Can include industry references, contract descriptions, agency names, solicitation details, or any other relevant information. More context generally produces more accurate matches. The API does not document which specific signals are extracted from this field. | **Constraints:** - `name` cannot be empty or whitespace-only (400 error) - `target_type` must be exactly `"entity"` or `"organization"` (400 error) - `state` should be a valid 2-letter code, but is not validated - `city` and `context` are free-form text with no constraints ## Response ### Success (HTTP 200) ```json { "candidates": [ { "identifier": "ABC123DEF456", "display_name": "Lockheed Martin Corporation" }, { "identifier": "GHI789JKL012", "display_name": "Lockheed Martin Aeronautics" }, { "identifier": "MNO345PQR678", "display_name": "LMC Holdings LLC" } ], "count": 3 } ``` **Free tier**: Returns up to 3 candidates with `identifier` and `display_name` fields only. **Pro tier and above**: Returns up to 5 candidates with an additional `match_tier` field: ```json { "candidates": [ { "identifier": "ABC123DEF456", "display_name": "Lockheed Martin Corporation", "match_tier": "high" }, { "identifier": "GHI789JKL012", "display_name": "Lockheed Martin Aeronautics", "match_tier": "medium" }, { "identifier": "MNO345PQR678", "display_name": "LMC Holdings LLC", "match_tier": "low" }, { "identifier": "STU901VWX234", "display_name": "Lockheed Martin Space", "match_tier": "low" }, { "identifier": "YZA567BCD890", "display_name": "Lockheed Martin Rotary", "match_tier": "low" } ], "count": 5 } ``` The `match_tier` field indicates the quality of the match: - `"high"` β€” Confident match, likely the intended target - `"medium"` β€” Reasonable match, but consider alternatives - `"low"` β€” Possible match, but verify before using When fewer candidates are returned than the tier limit, `count` reflects the actual number returned. ### No matches (HTTP 200) ```json { "candidates": [], "count": 0 } ``` ### Validation errors (HTTP 400) Missing or blank `name`: ```json { "error": "name is required and must not be blank", "code": "validation_error" } ``` Invalid `target_type`: ```json { "error": "target_type must be 'entity' or 'organization'", "code": "validation_error" } ``` ### Authentication error (HTTP 401) Standard 401 response for unauthenticated requests. ### Server error (HTTP 500) If an unexpected error occurs during resolution (rare), the response is: ```json { "error": "An unexpected error occurred during resolution", "code": "server_error" } ``` ## Examples ### Example 1: Entity resolution with full context ```bash curl -X POST https://tango.dev/api/resolve/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Boeing", "target_type": "entity", "state": "WA", "city": "Seattle", "context": "aerospace defense contractor, NAICS 336414, Department of Defense supplier" }' ``` **Response (Pro tier):** ```json { "candidates": [ { "identifier": "ABC123DEF456", "display_name": "The Boeing Company", "match_tier": "high" }, { "identifier": "GHI789JKL012", "display_name": "Boeing Defense, Space and Security", "match_tier": "high" }, { "identifier": "MNO345PQR678", "display_name": "Boeing Commercial Airplanes", "match_tier": "medium" } ], "count": 3 } ``` ### Example 2: Minimal request (free tier) ```bash curl -X POST https://tango.dev/api/resolve/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Corp", "target_type": "entity" }' ``` **Response (Free tier):** ```json { "candidates": [ { "identifier": "ABC123DEF456", "display_name": "Acme Corporation" } ], "count": 1 } ``` ### Example 3: Organization resolution ```bash curl -X POST https://tango.dev/api/resolve/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{ "name": "Naval Sea Systems Command", "target_type": "organization", "context": "Department of the Navy" }' ``` **Response:** ```json { "candidates": [ { "identifier": "N6233A00", "display_name": "Naval Sea Systems Command", "match_tier": "high" } ], "count": 1 } ``` ## Best practices 1. **Provide context**: The `context` field significantly improves match quality. Include any relevant details: industry (NAICS/PSC codes), agency, contract purpose, solicitation details, or other business context. 2. **Use the right target_type**: Use `"entity"` for vendors/contractors and `"organization"` for government agencies or organizational units. 3. **Location helps**: When available, provide `state` and/or `city` to disambiguate between entities with similar names in different regions. 4. **Check match_tier** (Pro tier): Use the `match_tier` to gauge confidence. High matches are generally safe to use; medium and low matches should be verified. 5. **Handle no matches**: Plan for empty result sets. When no candidates are returned, consider trying alternative names or reducing specificity in the `context` field. ## SDK support > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). Both SDKs expose a typed `resolve()` method. The Python version returns a `ResolveResult` dataclass with `candidates` (list of `ResolveCandidate`) and `count`; the Node version returns the same envelope as a typed object. === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) result = client.resolve( name="Lockheed Martin", target_type="entity", state="MD", context="aerospace defense", ) print("Found", result.count, "candidates") for candidate in result.candidates: print(f" - {candidate.display_name} ({candidate.identifier}) [{candidate.match_tier}]") # Older SDK versions without client.resolve(): # response = client._post("/api/resolve/", {"name": "...", "target_type": "entity", ...}) # for c in response["candidates"]: # print(c["display_name"], c["identifier"]) ``` === "Node (tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const response = await client.resolve({ name: "Lockheed Martin", target_type: "entity", state: "MD", context: "aerospace defense", }); console.log(`Found ${response.count} candidates`); response.candidates.forEach((candidate) => { console.log(` - ${candidate.display_name} (${candidate.identifier})`); }); ``` ## Tier-based access All requests must be authenticated. Free tier and pro+ tier users receive different response shapes: | Aspect | Free | Pro+ | |--------|------|------| | Max candidates | 3 | 5 | | Fields | identifier, display_name | identifier, display_name, match_tier | | Rate limit | Standard | Standard | See [Plans & Data Access](../getting-started/pricing.md) for tier definitions. --- --- description: "Endpoints, parent resolution, and filtering for the SBIR/STTR topics and DoD DSIP solicitation resources." updated: 2026-08-01 --- # SBIR/STTR The SBIR/STTR endpoints expose Small Business Innovation Research and Small Business Technology Transfer topics across every participating agency (DoD, NIH, NSF, NASA, DOE, DOT and more), plus the DoD DSIP solicitation cycles they belong to. For field definitions, see the [SBIR Data Dictionary](../data-dictionary/sbir.md). **Authentication**: SBIR endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. Available on every plan, including Free β€” no tier gating on any field. ## Endpoints - `GET /api/sbir/topics/` β€” SBIR/STTR topics (all agencies). Detail lookup by `topic_id`. - `GET /api/sbir/solicitations/` β€” DoD DSIP solicitation cycles. Detail lookup by `solicitation_id`. Each topic belongs to a parent that funds it β€” a DoD DSIP cycle, a SAM.gov notice, or a Grants.gov announcement β€” so you can follow a topic through to the opportunity or grant behind it. Topics span every participating agency; solicitations are DoD (DSIP) only. ## Topics `GET /api/sbir/topics/` β€” one record per SBIR/STTR topic. Detail: `GET /api/sbir/topics/{topic_id}/`. ### The parent ladder Each topic links to at most one parent, resolved in priority order: 1. `solicitation(*)` β€” the parent DoD DSIP cycle (most DoD topics), joined on the topic's `cycle_name` or its `solicitation_number`. When both match, the `cycle_name` match wins: topics fed from DSIP carry a cycle name, while a cycle's `solicitation_number` can be empty. 2. `opportunity(*)` β€” the parent SAM.gov notice (e.g. DOT, ARPA-H topics that hang off a notice). 3. `grant(*)` β€” the parent Grants.gov announcement (e.g. NIH topics, joined on opportunity number). A non-DoD topic with no DSIP parent returns `solicitation: null` and links through `opportunity` or `grant` instead. A topic's own `close_date` reflects its individual schedule and outranks the parent BAA's window β€” a topic can close on its own date inside an otherwise-open parent. ### Lifecycle: `activity` `activity` is derived at query time as `open`, `closed`, or `unknown` (topics with no usable date roster). Filter on it with `?activity=open`. `solicitation_status` is sbir.gov's own raw Open/Closed string (source data, not derived) and is exposed separately. ### Filtering Date filters require `YYYY-MM-DD` (invalid dates or inverted ranges return **400**, see [Date filters](shared.md#date-filters)). Apart from `agency`, these filters are single-value (no `|` OR). | Param | What it does | | --- | --- | | `activity` | Lifecycle: `open`, `closed`, or `unknown`. | | `agency` | Agency, resolved to an organization and rolled up its hierarchy; accepts several values for OR, separated by a pipe or by `OR` (`?agency=DOD OR NSF`). Topics carry department-level values (`DOD`, `NSF`, `DOE`, `NASA`, `HHS`, `DHS`, `DOT`, `EPA`, `DOC`, `USDA`, `ED`) and link to that department, so a component agency resolves but matches nothing β€” NIH topics are filed under `HHS`, and `?agency=NIH` returns none. A value that resolves to no organization falls back to a partial match on the raw `agency` text, with a warning in `meta`. | | `topic_number` | Topic number, partial match. | | `solicitation_number` | Parent solicitation (BAA) number, partial match. | | `cycle_name` | DoD DSIP cycle name, **exact match** (case-sensitive), e.g. `DOD_SBIR_2026_P1_CBZ`. Only topics fed from DSIP carry one; the rest hold an empty string. This differs from `cycle_name` on `/api/sbir/solicitations/`, which is a partial match. | | `year` | Solicitation year (exact). | | `doc_source` | Document source: `grants_gov`, `dsip`, `sam_gov`, `other`, `none` (exact, case-insensitive). | | `open_date_after`, `open_date_before` | Open-date range. | | `close_date_after`, `close_date_before` | Close-date range. | | `release_date_after`, `release_date_before` | Release-date range. | | `search` | Full-text search over title, description, and topic number. | There is no `program` filter on topics β€” SBIR/STTR program lives on the parent solicitation. Filter topics by their parent instead (`solicitation_number`), or query `/api/sbir/solicitations/?program=STTR`. ### Ordering `ordering=` allowlist: `activity`, `close_date`, `open_date`, `release_date`, `year`, `modified`. Default is newest-modified first. ### Shaping - **List default:** `topic_id`, `title`, `agency`, `year`, `topic_number`, `solicitation_number`, `cycle_name`, `release_date`, `open_date`, `close_date`, `activity`, `solicitation_status`, `topic_url`, `official_solicitation_url` - **Detail default:** every allowed leaf field plus `solicitation(*)`, `opportunity(*)`, `grant(*)`, `organization(*)` Expandable relations and the keys they resolve to: - `solicitation(*)` β†’ `solicitation_id`, `solicitation_number`, `title`, `program`, `cycle_name`, `year`, `start_date`, `end_date`, `out_of_cycle`, `solicitation_status` - `opportunity(*)` β†’ `opportunity_id`, `title`, `solicitation_number`, `response_deadline` - `grant(*)` β†’ `grant_id`, `opportunity_number`, `title`, `response_date` - `organization(*)` β†’ the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`), resolved from the topic's `agency` text. `null` when the value resolves to no organization. ## Solicitations `GET /api/sbir/solicitations/` β€” one record per DoD DSIP solicitation cycle. Detail: `GET /api/sbir/solicitations/{solicitation_id}/`. ### Lifecycle: `activity` `activity` is derived from `end_date` as `open` or `closed` (no `unknown` state β€” solicitations always have a cycle window). `solicitation_status` is the raw feed status token, exposed separately. ### BAA documents The `documents(*)` expansion returns the solicitation's BAA PDF inventory. Each document resolves to `document_id`, `filename`, `cycle_name`, `s3_key`, `file_size`, `extraction_status`, `n_pages`, `n_chars`. ### Filtering Date filters require `YYYY-MM-DD`. Single-value (no `|` OR). | Param | What it does | | --- | --- | | `activity` | Lifecycle: `open` or `closed`. | | `program` | Program: `SBIR` or `STTR` (exact, case-insensitive). | | `solicitation_number` | Solicitation number, partial match. | | `cycle_name` | DSIP cycle directory name, partial match. (The topics filter of the same name is an exact match.) | | `solicitation_status` | Raw feed status token (exact, case-insensitive). | | `out_of_cycle` | Boolean. | | `year` | Solicitation year (exact). | | `start_date_after`, `start_date_before` | Cycle start-date range. | | `end_date_after`, `end_date_before` | Cycle end-date range. | | `search` | Full-text search over title and solicitation number. | There is no `agency` filter β€” DSIP solicitations are DoD only. ### Ordering `ordering=` allowlist: `activity`, `start_date`, `end_date`, `year`, `modified`. Default is newest-modified first. ### Shaping - **List default:** `solicitation_id`, `solicitation_number`, `title`, `program`, `cycle_name`, `year`, `start_date`, `end_date`, `out_of_cycle`, `activity`, `solicitation_status`, `sol_download_url` - **Detail default:** every allowed leaf field plus `topics(*)`, `documents(*)` and `organization(*)` Expandable relations: - `documents(*)` β†’ `document_id`, `filename`, `cycle_name`, `s3_key`, `file_size`, `extraction_status`, `n_pages`, `n_chars` - `topics(*)` β†’ `topic_id`, `title`, `agency`, `topic_number`, `close_date`, `topic_url` (a reduced view; the full topic shape lives at `/api/sbir/topics/`) - `organization(*)` β†’ the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Always the Department of Defense, since DSIP solicitations are DoD only. ## Pagination Both resources use standard page-number pagination: - `page` (default 1) - `limit` (default 25, max 100) ## Examples ```bash # Open HHS topics (this is where NIH topics live), timeline fields GET /api/sbir/topics/?activity=open&agency=HHS&shape=topic_id,title,agency,open_date,close_date,activity # A topic with its parent solicitation GET /api/sbir/topics/?solicitation_number=SB251-01&shape=topic_id,title,topic_number,solicitation(solicitation_number,program,cycle_name) # Open STTR solicitation cycles with their BAA documents GET /api/sbir/solicitations/?activity=open&program=STTR&shape=solicitation_id,title,cycle_name,documents(filename,s3_key,n_pages) # Solicitation detail with topics GET /api/sbir/solicitations/{solicitation_id}/?shape=solicitation_id,title,program,topics(topic_id,title,close_date) ``` Notes: - `*` is only valid inside expansions. Use explicit field lists at the root. - Invalid `shape` fields return HTTP 400 with structured validation errors. --- --- description: "The set-aside codes used across Tango's award and opportunity endpoints, with what each one means." updated: 2026-02-27 --- # Set-aside codes This page documents the set-aside codes used across Tango’s awards and opportunities APIs (including shaped `set_aside(code,description)` expansions). ## Codes | Code | Meaning | | --- | --- | | `NONE` | No set aside used | | `SBA` | Small Business Set Aside - Total | | `8A` | 8a Competed | | `SBP` | Small Business Set Aside - Partial | | `HMT` | HBCU or MI Set Aside - Total | | `HMP` | HBCU or MI Set Aside - Partial | | `VSB` | Very Small Business | | `ESB` | Emerging Small Business Set-Aside | | `HZC` | HUBZone Set Aside | | `SDVOSBC` | Service-Disabled Veteran-Owned Small Business Set Aside | | `BI` | Buy Indian | | `IEE` | Indian Economic Enterprise | | `ISBEE` | Indian Small Business Economic Enterprise | | `HZS` | HUBZone Sole Source | | `SDVOSBS` | SDVOSB Sole Source | | `8AN` | 8(a) Sole Source | | `RS` | Reserved for Small Business | | `HS3` | 8(a) with HUBZone Preference | | `VSA` | Veteran Set Aside | | `VSS` | Veteran Sole Source | | `WOSB` | Women-Owned Small Business | | `EDWOSB` | Economically Disadvantaged Women-Owned Small Business | | `WOSBSS` | Women-Owned Small Business Sole Source | | `EDWOSBSS` | Economically Disadvantaged Women-Owned Small Business Sole Source | ## Source of truth Tango maintains a canonical mapping internally and publishes it here for API consumers. --- --- description: "Shared response objects and conventions β€” set-aside, date filters, and office shapes β€” that recur across multiple Tango endpoints." updated: 2026-05-13 --- # Shared response objects This page defines shared objects returned across Tango API endpoints, especially when using **response shaping** (`?shape=`). ## Set-aside Many endpoints expose a `set_aside` field. When expanded (e.g. `set_aside(code,description)`), it returns an object: ```json { "code": "SBA", "description": "Small Business Set Aside - Total" } ``` If the underlying value is missing, the API returns `null` for `set_aside`. For the full list of codes and their meanings, see [Set-aside codes](set-aside.md). ## Date filters All date range filters across the API require **YYYY-MM-DD** format (e.g. `2024-06-15`). The API validates date inputs and returns **HTTP 400** for: - **Invalid format**: any value that is not a valid `YYYY-MM-DD` string (e.g. `2024-13-01`, `not-a-date`, `01/15/2024`). - **Inverted range**: when the "after" / "gte" value exceeds the "before" / "lte" value (e.g. `award_date_gte=2025-01-01&award_date_lte=2024-01-01`). The error response body includes a human-readable message identifying the invalid parameter and value. Endpoints use two naming conventions for range pairs, but validation is identical: | Convention | Example params | | --- | --- | | `_gte` / `_lte` | `pop_start_date_gte`, `pop_start_date_lte` | | `_after` / `_before` | `posted_date_after`, `posted_date_before` | Fiscal year filters (`fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte`) use **YYYY** format and are validated separately. ## Office Several endpoints expand an office into a common office object (for example: `office(...)`, `awarding_office(...)`, or `funding_office(...)` depending on the endpoint). When expanded, office objects use this shape: ```json { "office_code": "1234AB", "office_name": "Office Name", "agency_code": "12", "agency_name": "Agency Name", "department_code": "1", "department_name": "Department Name" } ``` For **awarding offices**, `office_code` returns the 6-character Activity Address Code (AAC) that matches positions 1-6 of the contract PIID, with a fallback to the local office code. For **funding offices**, `office_code` returns the local office code. --- --- description: "Endpoints, filters, coverage semantics, shapes, and tier gates for state, local, and education procurement data." tags: [state-opportunities, api, provisional, reference] updated: 2026-09-17 --- # State & Local β€” **Beta** State, local and education (SLED) procurement: solicitations that never appear on SAM.gov because they were never federal. For field definitions, see the [State & Local Data Dictionary](../data-dictionary/sled.md). !!! warning "Beta β€” coverage is partial and grows by jurisdiction" There is no national SLED feed. Every jurisdiction publishes on its own portal, in its own vocabulary, on its own schedule, and Tango reads them one at a time. **A thin result for a state is at least as likely to be a portal we do not read yet as a quiet market**, so call [`/api/sled/opportunities/coverage/`](#coverage) before treating a per-state count as market size. Field availability varies by state in ways the federal endpoints never taught you to expect β€” `description` is absent on every row in several states, and `solicitation_number` is null wherever the portal publishes none. Fields and filters may still be added; nothing documented here will be removed without a version bump. The `raw(*)` expansion is explicitly unstable at any tier (see [Shaping](#shaping)). **Authentication**: SLED endpoints require authentication (API key or OAuth2). Unauthenticated requests receive HTTP 401. Every filter, every endpoint and the full-text search are available on **every plan including Free**; three shape leaves β€” `attachments(extracted_text)`, `revisions(changes)` and `raw(*)` β€” require **Small or above**. `attachments(extracted_text)` needs API version 4.25.1 or later; `GET /api/version` reports what you are calling. ## Endpoints - `GET /api/sled/opportunities/` β€” state, local and education solicitations - `GET /api/sled/opportunities/{opportunity_id}/` β€” one solicitation - `GET /api/sled/opportunities/{opportunity_id}/revisions/` β€” that solicitation's observed amendment history - `GET /api/sled/opportunities/coverage/` β€” what this dataset actually covers, per state - `GET /api/sled/forecasts/` β€” planned state procurements - `GET /api/sled/forecasts/{forecast_id}/` β€” one forecast Detail routes are keyed by a Tango-minted UUID (`opportunity_id` / `forecast_id`) and the path segment must be a valid RFC 4122 UUID β€” anything else is a 404, not a 500. SLED is its own namespace rather than a domain on `/api/opportunities/`, and deliberately so: the state schema shares almost no columns with a SAM notice. There is no NAICS or PSC on most rows, no set-aside, no office, no notice type, and no entry in the federal agency hierarchy. Folding these rows into the federal endpoint would degrade the federal shape and drag state solicitations into every existing federal filter, search and alert. **`/api/opportunities/` returns no SLED rows, and `/api/sled/opportunities/` returns no federal ones.** --- ## Two things to read before your first query ### A list request with no liveness filter returns open solicitations only Only about a fifth of the corpus is open at any time, and a state portal *drops* a closed solicitation rather than restating it as closed. So the list endpoint defaults to `status=open`. - To page the whole corpus, pass an explicit `status=` (or `active=`) filter. - `status=unknown` β€” standing vendor rosters and dateless RFIs, which have no deadline to have passed β€” is hidden by that default. Reach it with `status=open|unknown`. - **A detail request returns the solicitation whatever its status.** The default lives on the list action only, so a closed solicitation still resolves on its own URL. ### `status` is Tango's answer, not the portal's `status` is one of `open`, `closed`, `awarded`, `cancelled` or `unknown`, derived from the portal's own word, the response deadline and the clock β€” and refreshed every fifteen minutes whether or not the feed moved. `status_reason` says which input decided it (`deadline_future`, `deadline_past`, `no_deadline`, `source_terminal`, `delisted`), and `status_computed_at` says when. **A solicitation the portal stops listing before its deadline reads `closed` with `status_reason=delisted`.** `delisted_at` is when a complete crawl of that portal first found it gone; it is null on anything never delisted. The portal's own terminal word (`awarded`, `cancelled`) still outranks a delisting, and a delisting outranks the deadline. If the portal lists the solicitation again, `delisted_at` clears and `status` is derived from the deadline as before. `delisted_at` needs API version 4.25.3 or later. The portal's own status word is a different and much weaker fact: it is frozen at last capture, and **most of what the feeds call open already has a deadline in the past**. That word is served as `source_status` so you can see the disagreement, but do not filter liveness on it. The portal's full raw status vocabulary lives behind the Small-and-above `raw(*)` expansion. Forecasts carry no `status` at all β€” see [Forecasts](#forecasts). --- ## Coverage `GET /api/sled/opportunities/coverage/` takes no parameters and returns one cached rollup (counts below are illustrative β€” call the endpoint for live ones): ```json { "generated_at": "2026-09-10T14:00:00Z", "totals": { "opportunities": 46479, "forecasts": 1452, "jurisdictions_covered": 51, "by_status": {"open": 9207, "closed": 35102, "awarded": 812, "cancelled": 604, "unknown": 754} }, "states": [ { "state": "AL", "total_count": 812, "by_status": {"open": 131, "closed": 651, "awarded": 12, "cancelled": 4, "unknown": 14}, "jurisdictions": ["local", "state"], "last_change_observed_at": "2026-09-10T06:12:44Z" } ] } ``` Every state row carries **all five status buckets whether or not they have rows**, so a total and two buckets never invite you to subtract. `last_change_observed_at` is the most recent scrape that saw *any* solicitation in that state β€” a stale value there means we have not read the portal lately, not that the market is quiet. The payload is counts and nothing else, by design. The caveats that make a particular state's number readable belong here in the documentation, where they can be corrected; prose shipped in a data payload cannot be kept true. Read it before concluding that a scheme-specific category filter is broken (see [Category codes](#category-codes)) or that a state is empty. --- ## Solicitations `GET /api/sled/opportunities/` One row is one advertised solicitation, arbitrated across every scrape that observed it, keyed by a stable `opportunity_id`. ### Filtering Identifier filters accept `|` (or the word `OR`) for OR. Date filters require `YYYY-MM-DD`; invalid dates or inverted ranges return **400** (see [Date filters](shared.md#date-filters)). `search` and `agency` must be at least 2 characters. | Param | What it does | | --- | --- | | `state` | Two-letter state or territory code. The primary partition. Multi-value: use `\|` for OR. | | `jurisdiction` | Level of government: `state`, `local` or `education`. `unknown` reaches the aggregator rows that cannot tell state from local. Multi-value. | | `status` | `open`, `closed`, `awarded`, `cancelled` or `unknown`. **Absent on a list request, this defaults to `open`.** Multi-value. | | `active` | Boolean sugar for federal-shaped callers: `active=true` is `status=open`, `active=false` is its complement (so it includes `unknown`). | | `agency` | Substring match on the buyer's raw text. There is no code resolution behind this β€” state agencies have no entry in the federal organization tree. Min 2 characters. | | `solicitation_number` | The number a human would quote (exact, case-insensitive). Null on roughly a third of the corpus, where the portal publishes none. Multi-value. | | `solicitation_type` | `rfp`, `ifb`, `rfq`, `rfi`, `itb`, `sole_source`, `grant` or `other`. `null` (the portal states no type) is a **distinct answer** from `other` (a type the vocabulary does not recognize). Multi-value. | | `has_documents` | Boolean. Whether the solicitation advertises at least one document. | | `revision_kind` | The kind of the most recent substantive revision: `deadline_change`, `status_change`, `documents_added`, `documents_removed`, `documents_replaced`, `title_change` or `content_change`. Multi-value. | | `naics` | Exact match within the `naics` category scheme. **Thin on purpose** β€” see [Category codes](#category-codes). Multi-value. | | `nigp` | Exact match within the `nigp` scheme (the most widely tagged of the four). Multi-value. | | `unspsc` | Exact match within the `unspsc` scheme. Multi-value. | | `category` | Exact match within the `text` scheme, where the code is the portal's own human label. Multi-value. | | `category_code` | Matches a code under **any** scheme, including the untagged strings a pre-migration row still carries. The escape hatch when a scheme-specific filter returns less than you expected. Multi-value. | | `posted_after`, `posted_before` | Posted-date range (`YYYY-MM-DD`). `posted_date` is null on a sixth of the corpus. | | `response_deadline_after`, `response_deadline_before` | Response-deadline range. | | `first_seen_after`, `first_seen_before` | When **Tango first observed** the solicitation. This is the polling primitive: everything new since your last call. | | `change_seen_after` | When Tango **observed** the last substantive change. A scrape date, not an amendment date β€” see [Revisions](#revisions). | | `modified_after`, `modified_before` | When the Tango row last changed. | | `platform`, `native_id`, `external_id` | Support filters for reproducing a specific record with us. They appear in no response shape and their values are not a contract β€” quote `solicitation_number` to a human. `external_id` accepts at most 500 values. | | `search` | Ranked full-text search β€” see [Search](#search). Min 2 characters. | | `verbose` | Boolean. `verbose=true` adds `description` and `contact(*)` to the default list shape without costing a join. | No enum filter is a strict choice list: an unrecognized value returns an empty page rather than a 400, because the live vocabularies are wider than any list transcribed into a doc. #### Category codes `category_codes` is an array of `{scheme, code}` objects over `nigp`, `unspsc`, `naics`, `text` and `unknown`, and the scheme tagging is **mid-migration**. Roughly half of all entries corpus-wide are still bare pre-migration strings carrying no scheme, which read as `unknown`. The practical consequence: **`?naics=` matches only the entries that are scheme-tagged NAICS, which is a very small share of the corpus.** That is a fact about the tagging, not about coverage. `?category_code=541620` matches that code under any scheme *and* the untagged strings, and is what you want unless you specifically need scheme precision. Nothing here resolves against the federal NAICS or PSC tables. A state's NIGP commodity code is not a PSC and there is no crosswalk in this dataset. ### Ordering `ordering=` allowlist: `rank`, `response_deadline`, `posted_date`, `first_seen_at`, `last_seen_at`, `last_change_seen_at`, `modified`. `rank` requires a non-empty `search` β€” passing `ordering=rank` without one returns **400**. Under `search=` with no explicit `ordering`, results sort by relevance. `response_deadline`, `posted_date` and `last_change_seen_at` sort nulls last in both directions, so a page of results is never headed by rows with no date. ### Search `?search=` is a ranked full-text query over **title, agency, identifiers, category labels and description, weighted in that order**, widened by the solicitations whose *attachment text* matched. Three properties worth knowing: - **A title match outranks a body match, and a document-only match ranks below both.** `description` is null on about a quarter of open rows and absent entirely in several states, so ranking body matches first would bury the states that publish well. - **`snippet` is the passage that matched.** Under `search=`, a row that matched on its description carries a `snippet` field with the matching passage rather than the whole body β€” which is the answer to "why is this row here" on a resource whose descriptions run to six figures of characters. A row that matched on title or agency alone carries **no** `snippet`; that is the honest answer rather than the opening sentence of its description. - **Document matching returns ids, never text β€” and that is not a tier gate.** When a solicitation's attached PDF matches, the solicitation appears in your results. You get no snippet, no highlight and no fragment of the document: you learn *that* a document matched, never what it said. Because the response carries none of the text, **searching it is ungated and available on every plan including Free** β€” there is no tier check anywhere on this path. Reading a document's **body** is a separate, paid thing, and it is not part of search. `attachments(extracted_text)` serves the extracted text on **Small and above** β€” see [Attachments](#attachments). Searching that text stays ungated because a search response gives none of it away; buying the body buys the body, not better search. So there are two independent questions. *Did a document match?* β€” every plan, through `search=`, as ids. *What does the document say?* β€” Small and above, through `attachments(extracted_text)`, one record at a time. Every plan also gets enough metadata to judge a document without reading it: `size_bytes`, `char_count`, `pages` and `extraction_status`. Document matching **fails open**: when it is unavailable, the metadata search answers on its own β€” you get fewer rows, never an error. Treat a document match as a bonus signal rather than something to depend on for completeness. ### Shaping See [Response shaping](../guides/patterns/response-shaping.md) for the syntax. Pass `show_shapes=true` on any request to have the API report the shape tree your plan can reach. - **List default:** `opportunity_id`, `solicitation_number`, `solicitation_type`, `title`, `organization(*)`, `status`, `status_reason`, `delisted_at`, `posted_date`, `response_deadline`, `bid_opening_date`, `source_url`, `has_documents`, `category_codes`, `first_seen_at`, `last_seen_at`, `last_change_seen_at`, `meta(*)` - **`?verbose=true` list default:** the list fields plus `description` and `contact(*)` - **Detail default:** the list fields plus `description`, `solicitation_type_source`, `status_computed_at`, `response_deadline_original`, `bid_opening_raw`, `contact(*)`, `attachments(*)`, `revisions(*)` `description` is detail-only on purpose: its median is around 550 characters and its tail runs past 120,000, so twenty-five of them is not a list page. Reach it on a list by naming it, by `?verbose=true`, or by `snippet` under `search=`. Expansions: | Expand | Leaves | Notes | | --- | --- | --- | | `organization(*)` | `state`, `level`, `agency` | The buyer. **Not** the federal 7-key office payload β€” there is no code resolution, and no `organization_id` to join on. | | `contact(*)` | `name`, `email`, `phone` | The buyer contact as the portal publishes it. | | `meta(*)` | `attachment_count`, `revision_count`, `last_revision_kind`, `last_change_source_declared` | Denormalized counts; costs no join. | | `attachments(*)` | 13 leaves β€” see [Attachments](#attachments) | Document metadata and extraction stats. **The wildcard never carries `extracted_text`** β€” name it explicitly. | | `revisions(*)` | `observed_at`, `sequence`, `kind`, `changed_fields`, `changes`, `source_declared` | The observed amendment history, minus enrichment rows. `changes` requires **Small or above**. | | `attachments(extracted_text)` | the document's extracted body | **Small or above**, and opt-in only β€” see [Attachments](#attachments). | | `raw(*)` | wildcard over the platform's own keys | The platform's unparsed payload. **Small or above, and explicitly unstable** β€” its shape varies by platform and is not a contract at any tier. | Below Small, naming `raw(*)`, `revisions(changes)` or `attachments(extracted_text)` gets the node withheld and listed in `meta.upgrade_hints`; under a bare `revisions(*)` the `changes` key is simply absent, with no hint. **`meta.attachment_count` can be lower than the length of `attachments(*)`, and that is not a bug.** Some portals auto-generate a cover sheet alongside the real documents; it is a file, not a document the agency wrote, so it is excluded from the count and from `has_documents` but still listed β€” flagged `is_generated_summary: true`. `attachment_count` answers "does this record hold its solicitation package"; the collection answers "what files exist". A record whose only file is a generated sheet holds no package. ### Attachments `attachments(*)` leaves β€” available on **every plan**: `name`, `extension`, `mime_type`, `checksum`, `size_bytes`, `char_count`, `word_count`, `pages`, `extraction_status`, `download_status`, `is_contested`, `is_generated_summary`, `first_seen_at`. One further leaf, **`extracted_text`, requires Small or above** and is **not included by `attachments(*)`** β€” see below. There is no download URL on this endpoint. The free metadata is enough to decide whether a document is worth fetching: - **`size_bytes` and `char_count` only mean something as a pair.** Three megabytes that yielded no characters is a scan awaiting OCR; three megabytes that yielded 40,000 characters is a specification. Neither number says that alone. - **`extraction_status`** is `completed`, `empty` or `failed`. `empty` is extraction succeeding with zero characters β€” almost always a scanned image, which is a different problem from one that threw. - **`is_contested: true`** means the stored object's checksum disagrees with what this record advertised β€” another solicitation's bytes under the same key. A contested attachment is served as a name and an existence, never as content. - **`is_generated_summary: true`** is the auto-generated cover sheet described above. #### `extracted_text` β€” the document body ```bash GET /api/sled/opportunities/{opportunity_id}/?shape=opportunity_id,attachments(name,size_bytes,extracted_text) ``` Requires a **Small plan or above**, and API version 4.25.1 or later. Three rules govern it: - **You have to name it.** `attachments(*)` does not carry the body, and neither default shape includes it. Add `extracted_text` to the expand when you want it, and leave it off when you are just listing what documents exist β€” a record's documents can run to megabytes of text. - **The key is absent, not null**, whenever the text is not being served to you: below Small (where it is withheld and listed in `meta.upgrade_hints`), on a contested document, or where we hold no text for that document. Read it with a default rather than assuming the key is present. - **A contested document never returns text, at any plan.** The file we retrieved for it does not match what the solicitation listed, so we cannot vouch that its text belongs to this record. `is_contested` is why the body is missing. Two entries with the same `checksum` are the same document under two filenames, and return the same body. This is a per-record read, not a search feature: a `?search=` response never carries text at any plan (see [Search](#search)). `char_count` reports whether there was text to get, whether or not this response carries it β€” which is what lets you decide on a Free plan whether the body is worth buying. --- ## Revisions `GET /api/sled/opportunities/{opportunity_id}/revisions/` A revision is a diff between two consecutive arbitrated states of one solicitation, stamped with the scrape that saw it. **No state portal emits amendment notices**, so this is observation rather than publication, and three limits follow from that: - **`kind` is Tango's inference** from the diff β€” `deadline_change`, `status_change`, `documents_added`, `documents_removed`, `documents_replaced`, `title_change`, `content_change` β€” on about 95% of revisions. `source_declared` is `true` only on the minority where a portal's own amendment marker moved in the same emission. - **Resolution is the crawl cadence, not the amendment.** A portal restates one page in place and publishes no amendment date, so `observed_at` is when we saw the change, not when the agency made it. `change_seen_after` on the parent endpoint filters on the same timestamp and inherits the same caveat. - **History starts when we started reading that jurisdiction**, not when the solicitation was posted. For the most recently added sources that is days, not months. This route serves `enrichment` rows, which the `revisions(*)` expansion does not: an enrichment is Tango filling in coverage it did not have β€” a description it had not yet read, say β€” rather than the agency amending anything. It is excluded from `revision_count` and from the expansion for that reason, but it is real provenance, and `?kind=enrichment` shows only those. ### Filtering | Param | What it does | | --- | --- | | `kind` | Revision kind, plus `enrichment`. Multi-value: use `\|` for OR. | | `source_declared` | Boolean. Whether the portal's own amendment marker moved at this emission. | | `observed_after`, `observed_before` | Observation-date range (`YYYY-MM-DD`). | Results are ordered by `sequence` (1-based within the record) and paginated like every other list. `changes` β€” the per-field before and after β€” requires **Small or above**. `changed_fields` names what moved at every plan, so the Free answer is still a usable amendment log. --- ## Forecasts `GET /api/sled/forecasts/` A forecast is a state's own advance notice of something it intends to buy. **Maryland is the only state publishing one today**; `/api/sled/opportunities/coverage/` reports the forecast total alongside the solicitation coverage. **Forecasts carry no liveness at all.** There is no deadline to have passed, so a `status` column would stamp `unknown` on every row forever. Currency is your call from `estimated_advertisement_date` β€” which is the **start of the published quarter**, not a posting date. `estimated_advertisement_raw` keeps the portal's own words (`"Q3 (Jan.-March 2027)"`), and a large share of rows publish no quarter at all. ### Filtering `search` and `agency` must be at least 2 characters; date filters require `YYYY-MM-DD`. | Param | What it does | | --- | --- | | `state` | Two-letter state code. Multi-value: use `\|` for OR. | | `agency` | Substring match on the buyer's raw text. Min 2 characters. | | `procurement_category` | The portal's own category word, passed through verbatim. Multi-value. | | `procurement_method` | The portal's own method word, passed through verbatim. Multi-value. | | `contract_number` | The number the state expects to award under, where it publishes one in advance. Multi-value. | | `incumbent_name` | Substring match on the incumbent vendor's name as published. **Not resolved to a Tango entity.** Multi-value. | | `advertisement_after`, `advertisement_before` | Estimated-advertisement-date range. Remember the date is a quarter start. | | `first_seen_after`, `first_seen_before` | When Tango first observed the forecast. | | `modified_after`, `modified_before` | When the Tango row last changed. | | `search` | Ranked full-text search over title, agency and description. Min 2 characters. | ### Ordering `ordering=` allowlist: `rank`, `estimated_advertisement_date`, `first_seen_at`, `last_seen_at`, `modified`. `rank` requires a non-empty `search`. `estimated_advertisement_date` sorts nulls last. ### Shaping - **List default:** `forecast_id`, `state`, `agency`, `title`, `description`, `organization(*)`, `estimated_advertisement_date`, `estimated_advertisement_raw`, `estimated_value(*)`, `procurement_category`, `procurement_method`, `contract_term`, `contract_number`, `incumbent_name`, `mbe_dbe_goal`, `source_url`, `first_seen_at`, `last_seen_at` - **Detail default:** the list fields plus `contact(*)`, `delivery_location`, `has_documents` | Expand | Leaves | Notes | | --- | --- | --- | | `organization(*)` | `state`, `level`, `agency` | Narrower than a solicitation's β€” the forecast feed carries no sub-state jurisdiction. | | `contact(*)` | `name`, `email`, `phone` | As published. | | `estimated_value(*)` | `min`, `max`, `raw` | Parsed from the portal's free-text award band, with the band preserved as `raw`. **A band naming one number is a floor, so `max` is null** β€” never read a missing `max` as an unbounded ceiling. | | `raw(*)` | wildcard | **Small or above**, and unstable. | --- ## Pagination Standard page-number pagination on every list, including the nested revisions route: - `page` (default 1) - `limit` (default 25, max 100) Responses carry `count / next / previous / results`. List responses are cached for up to 15 minutes and the cache is scoped by plan, so a Free caller never receives a Small caller's `raw(*)`. ## Alerts `sled_opportunity` is an alertable query type β€” `alerts.sled_opportunity.match`, using the same filters documented above. See the [webhooks guide](../webhooks/index.md). Unlike exclusions and DIBBS, **a SLED solicitation closing does fire an alert.** `status` is a stored column Tango recomputes every fifteen minutes, so a closure is a real change to the record rather than a query-time derivation. `sled_forecast` is not alertable (no deadline, so no transition); revisions and attachments are not alertable on their own β€” subscribe to the solicitation and filter on `change_seen_after` or `revision_kind`. ## What this dataset is not - **Not federal, and not joinable to it.** No UEI, no PIID, no NAICS/PSC crosswalk, no agency-hierarchy key. `organization(*)` here is three strings, not the 7-key federal office payload. - **Not a complete picture of any state.** See [Coverage](#coverage). - **Not a document repository.** Attachment metadata and extraction stats are served; bodies and download URLs are not. - **Not award data.** `status=awarded` records that a portal declared an award; there is no awardee, value or contract record behind it. ## Examples ```bash # Open solicitations in Texas closing this month GET /api/sled/opportunities/?state=TX&response_deadline_before=2026-10-01 # Local and education buyers with documents attached GET /api/sled/opportunities/?jurisdiction=local|education&has_documents=true # Everything new since your last poll, including dateless standing rosters GET /api/sled/opportunities/?first_seen_after=2026-09-01&status=open|unknown # Full-text search, with the matching passage on each row GET /api/sled/opportunities/?search=environmental%20mitigation&shape=opportunity_id,title,state,snippet,response_deadline # A category code under any scheme, since scheme tagging is partial GET /api/sled/opportunities/?category_code=541620 # One solicitation, whatever its status, with its documents GET /api/sled/opportunities/550e8400-e29b-41d4-a716-446655440000/?shape=opportunity_id,title,status,attachments(*) # What changed on it, and when we saw it change GET /api/sled/opportunities/550e8400-e29b-41d4-a716-446655440000/revisions/?kind=deadline_change # Coverage, before trusting any per-state count GET /api/sled/opportunities/coverage/ # Maryland forecasts advertising after this quarter GET /api/sled/forecasts/?state=MD&advertisement_after=2026-10-01 ``` --- --- description: "Filtering, ordering, and the default response shape for /api/subawards/, Tango's subaward endpoint built from SAM subcontract reports and USAspending." tags: [subawards, api, reference] updated: 2026-10-30 --- # Subawards Subawards (subcontracts reported under federal prime contracts and IDVs) are exposed at `/api/subawards/`. For field definitions, see the [Subawards Data Dictionary](../data-dictionary/subawards.md). ## 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 | Field | Description | | --- | --- | | `key` | The report UUID | | `award_key` | Prime award identifier, the same convention `/api/contracts/{key}/` and `/api/idvs/{key}/` use | | `piid` | Prime award PIID | | `prime_awardee_uei` | Prime awardee UEI | | `prime_recipient_id` | The prime awardee's entity id, the `uuid` of `/api/entities/` | | `recipient_uei` | Subawardee UEI | | `recipient_id` | The subawardee's entity id | | `recipient_parent_uei` | Subawardee parent UEI | | `recipient_parent_id` | The subawardee parent's entity id | | `place_of_performance_id` | The place-of-performance id, shared with the award resources | | `pop_cd_original` | Place-of-performance congressional district as reported | | `pop_cd_current` | Place-of-performance congressional district under current boundaries | | `amount_suspect` | `true` when the reported amount is not plausibly a subcontract; see [the data dictionary](../data-dictionary/subawards.md#amount_suspect) | | `retired_at` | When the report stopped being published, `null` while it is live; see [Retired reports](#retired-reports) | | `usaspending_permalink` | USAspending.gov link | ### Expansions | Expansion | Fields | | --- | --- | | `subaward_details(*)` | `description`, `type`, `number`, `amount`, `action_date`, `fiscal_year` | | `fsrs_details(*)` | `last_modified_date` (a timestamp), `id` (the report UUID, same as `key`), `year`, `month` | | `place_of_performance(*)` | `city`, `state` (the two-letter code), `zip`, `country_code`, from the shared place record | | `highly_compensated_officers(*)` | `name`, `amount`: a list of up to 5 officers | | `prime_recipient(uei,display_name)` | Prime awardee identity, resolved against the Entities resource | | `subaward_recipient(uei,display_name,duns)` | Subawardee identity, resolved against the Entities resource; a subawardee that is not a registered entity returns its `uei` with `display_name: null`. `duns` is always `null` and is kept only for callers that still request it | | `awarding_office(*)` | `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`, from the prime award | | `funding_office(*)` | Same fields as `awarding_office` | 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 ```bash # 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 | Param | What it does | | --- | --- | | `key` | One or more report UUIDs, pipe-separated (`key=a|b`); an integer is a pre-5.15.0 key and resolves until the sunset. An unknown key matches nothing. | | `award_key` | Filter by prime award key (exact). | | `prime_uei` | Filter by prime awardee UEI (exact). | | `sub_uei` | Filter by subawardee UEI (exact). | | `recipient` | Search by recipient name (best-effort mapping to UEIs). | | `awarding_agency` | Filter by prime awarding agency code (exact). | | `funding_agency` | Filter by prime funding agency code (exact). | | `fiscal_year` | Filter by subaward action-date fiscal year (exact). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range. | | `include_retired` | `true` includes retired reports in the list; see below. | ## 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](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python 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")) ``` === "Node (tango-node)" ```ts 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); ``` --- --- description: "Filtering, ordering, and the default response shape for /api/assistance/subgrants/, Tango's subgrant endpoint built from SAM.gov assistance subaward reports and USAspending." tags: [assistance, subgrants, api, reference] updated: 2026-11-03 --- # Subgrants Subgrants (subawards reported under federal grants and cooperative agreements) are exposed at `/api/assistance/subgrants/`. They are the assistance half of FFATA subaward reporting; the contract half is [Subawards](subawards.md). For field definitions, see the [Subgrants Data Dictionary](../data-dictionary/subgrants.md). ## Endpoints - `GET /api/assistance/subgrants/` (list + filtering + ordering) - `GET /api/assistance/subgrants/{key}/` (detail; `key` is the report UUID) Scoped lists: - `GET /api/assistance/grants/{key}/subgrants/`, and the same under `/loans/`, `/direct_payments/` and `/other/` (subgrants under a prime assistance award). As on the award's other sub-routes, `{key}` must name an award on that endpoint: a retired key resolves to the award that carries it now, and a key for an award on another endpoint returns an empty list. - `GET /api/entities/{uei}/subgrants/` (subgrants where the entity is the subgrantee) ## Keys A subgrant's `key` is the subaward report's own identifier: the UUID that SAM.gov assigns to an assistance subaward 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. The prime award is reached through `award_key`, the same `assistance_award_unique_key` the [financial-assistance resources](assistance.md) take, and through `fain`. Almost every subgrant sits under a grant award. `prime_assistance_group` records which of the four resources held the prime when Tango processed the report, and so where its subgrants are listed: | `prime_assistance_group` | The prime's subgrants | | --- | --- | | `grant` | `/api/assistance/grants/{award_key}/subgrants/` | | `loan` | `/api/assistance/loans/{award_key}/subgrants/` | | `direct_payment` | `/api/assistance/direct_payments/{award_key}/subgrants/` | | `other` | `/api/assistance/other/{award_key}/subgrants/` | An award moves to another endpoint when its latest action changes assistance type, so the value can lag. If the list under the named endpoint comes back empty, the prime's subgrants are under the endpoint whose detail route answers for `award_key`; `?award_key=` on `/api/assistance/subgrants/` finds them wherever the prime is. ## Default response All subgrant responses use the shaping pipeline by default. No `?shape=` parameter is required to get a shaped response. Default fields (equivalent to requesting): ```text amount_suspect,assistance_listings,award_key,awarding_office(*),fain,fsrs_details(*), funding_office(*),key,place_of_performance(*),place_of_performance_id, prime_assistance_group,prime_recipient(uei,display_name),prime_recipient_id,recipient_id, recipient_parent_id,retired_at,subgrant_details(*),subgrant_recipient(uei,display_name) ``` ## Shaping Use `?shape=` to request a custom field set. Subgrants support the following leaves and expansions. ### Leaves | Field | Description | | --- | --- | | `key` | The report UUID | | `award_key` | Prime award identifier, the same convention the financial-assistance resources use | | `fain` | Prime award FAIN | | `assistance_listings` | The prime award's assistance listings as reported, e.g. `12.300: BASIC AND APPLIED SCIENTIFIC RESEARCH`; several are `;`-separated | | `prime_assistance_group` | Which financial-assistance resource held the prime award when Tango processed the report: `grant`, `loan`, `direct_payment` or `other`; `null` when the prime was not in Tango. See [Keys](#keys) for the list each value leads to | | `prime_awardee_uei` | Prime recipient UEI | | `prime_recipient_id` | The prime recipient's entity id, the `uuid` of `/api/entities/` | | `recipient_uei` | Subgrantee UEI | | `recipient_id` | The subgrantee's entity id | | `recipient_parent_uei` | Subgrantee parent UEI | | `recipient_parent_id` | The subgrantee parent's entity id | | `place_of_performance_id` | The place-of-performance id, in the financial-assistance place dimension | | `pop_cd_original` | Place-of-performance congressional district as reported | | `pop_cd_current` | Place-of-performance congressional district under current boundaries | | `amount_suspect` | `true` when the reported amount is not plausibly a subgrant; see [the data dictionary](../data-dictionary/subgrants.md#amount_suspect) | | `retired_at` | When the report stopped being published, `null` while it is live; see [Retired reports](#retired-reports) | | `usaspending_permalink` | The prime award's page on USAspending.gov | ### Expansions | Expansion | Fields | | --- | --- | | `subgrant_details(*)` | `description`, `type` (always `sub-grant`), `number`, `amount`, `action_date`, `fiscal_year` | | `fsrs_details(*)` | `last_modified_date` (a timestamp), `id` (the report UUID, same as `key`), `year`, `month` | | `place_of_performance(*)` | `city`, `state` (the two-letter code), `zip`, `country_code`, from the assistance place record | | `highly_compensated_officers(*)` | `name`, `amount`: always five entries; one the report leaves empty has `null` for both | | `prime_recipient(uei,display_name)` | Prime recipient identity, resolved against the Entities resource | | `subgrant_recipient(uei,display_name,duns)` | Subgrantee identity, resolved against the Entities resource; a subgrantee that is not a registered entity returns its `uei` with `display_name: null`. `duns` is always `null` | | `awarding_office(*)` | `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`, from the prime award | | `funding_office(*)` | Same fields as `awarding_office` | Recipient and place details are not stored on the subgrant itself: they come from the entity and place records the ids point at. ### Examples ```bash # Default response (no shape needed) /api/assistance/subgrants/ # Minimal fields /api/assistance/subgrants/?shape=key,fain,award_key,prime_assistance_group # Subgrant details with recipient info /api/assistance/subgrants/?shape=key,fain,subgrant_details(*),subgrant_recipient(uei,display_name) # The program and the awarding office /api/assistance/subgrants/?shape=key,assistance_listings,awarding_office(office_code,agency_name) # Highly compensated officers /api/assistance/subgrants/?shape=key,highly_compensated_officers(name,amount) # Discover available fields /api/assistance/subgrants/?show_shapes=true ``` ## Filtering | Param | What it does | | --- | --- | | `key` | One or more report UUIDs, pipe-separated (`key=a|b`). A UUID that names no report matches nothing; a value that is not a UUID returns **400**. | | `award_key` | Filter by prime award key (exact). | | `fain` | Filter by the prime award's FAIN (case-insensitive exact). | | `prime_assistance_group` | Filter on `prime_assistance_group`: `grant`, `loan`, `direct_payment` or `other`, exact and lowercase, pipe-separated for several (`prime_assistance_group=grant|loan`). | | `prime_uei` | Filter by prime recipient UEI (exact). | | `sub_uei` | Filter by subgrantee UEI (exact). | | `assistance_listing` | Filter by an assistance listing (CFDA) number the prime award carries, e.g. `93.778`. It matches anywhere in `assistance_listings`, case-insensitively, so pass the full number. | | `recipient` | Search by subgrantee name (best-effort mapping to UEIs). Min 2 characters. | | `fiscal_year` | Filter by subgrant action-date fiscal year (exact). | | `fiscal_year_gte`, `fiscal_year_lte` | Fiscal year range. | | `include_retired` | `true` includes retired reports in the list; see below. | An unrecognized query parameter on these lists, the scoped ones included, returns **400** with a did-you-mean suggestion rather than being silently ignored, so a mistyped filter never returns a full, unfiltered page. `?fian=` answers `{"error": "Unknown query parameter: 'fian'. Did you mean: 'fian' -> 'fain'?"}`. ## 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. ## Ordering Subgrants support `ordering=` with a strict allowlist; prefix `-` for descending: - `last_modified_date` (the report's last modification, `fsrs_details.last_modified_date`) Any other value returns **400** naming the allowed one. Example: `GET /api/assistance/subgrants/?ordering=-last_modified_date` ## Pagination Subgrants use standard page-number pagination: - `page` (default 1) - `limit` (max 100) ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) data = client._get( "/api/assistance/subgrants/", params={"assistance_listing": "93.778", "ordering": "-last_modified_date", "limit": 10}, ) print("count:", data.get("count")) ``` === "Node (tango-node)" ```ts 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/subgrants/", { assistance_listing: "93.778", ordering: "-last_modified_date", limit: 10, }); console.log("count:", data.count); ``` --- --- description: "The request and response contract for POST /api/validate/, which checks the format of a PIID, solicitation number, or UEI." updated: 2026-08-18 --- # Identifier Validation Validate the format of federal procurement identifiers. This endpoint is useful for intake forms, data cleaning pipelines, or integrations that need to check identifiers before submission. **Endpoint**: `POST /api/validate/` ## Overview Given an identifier type and value, the endpoint returns a `result` of `"valid"`, `"not_valid"`, or `"low_confidence"`. No database lookups are performed β€” this is pure format validation. Supported identifier types: | Type | Description | Rules | | ---- | ----------- | ----- | | `piid` | Procurement Instrument Identifier | FAR 4.201: 13–17 alphanumeric chars, valid AAC + fiscal year + instrument type + serial | | `solicitation` | Solicitation number | 5–30 chars, contains both letters and digits, matches known procurement ID patterns | | `uei` | Unique Entity Identifier | Exactly 12 alphanumeric chars, must not contain letters I or O | ### Result values | Result | Meaning | | ------ | ------- | | `valid` | Matches a known format with high confidence | | `not_valid` | Does not match any recognized format | | `low_confidence` | Plausible identifier but doesn't match a named pattern (solicitations only) | The `low_confidence` result only applies to solicitation numbers. Solicitation formats vary widely across agencies β€” some pass basic structural checks (alphanumeric, right length, mixed letters and digits) but don't match any of the ~25 known patterns derived from FPDS data. PIIDs and UEIs have strict formats, so they are always `valid` or `not_valid`. **Access**: Requires Pro tier (Small+). See [Plans & Data Access](../getting-started/pricing.md) for tier definitions. **Rate limiting**: Standard API rate limits apply. ## Request ```http POST /api/validate/ Content-Type: application/json X-API-KEY: { "type": "piid", "value": "ABCDEF24C1234" } ``` ### Request body fields | Field | Type | Required | Description | | ----- | ---- | -------- | ----------- | | `type` | string | Yes | Identifier type: `"piid"`, `"solicitation"`, or `"uei"`. | | `value` | string | Yes | Identifier value to validate (must be non-blank). | ## Response ### Valid identifier (HTTP 200) ```json { "result": "valid", "type": "piid", "value": "ABCDEF24C1234" } ``` ### Invalid identifier (HTTP 200) For PIIDs, the response includes an `errors` array with specific validation failures: ```json { "result": "not_valid", "type": "piid", "value": "ABC", "errors": [ "PIID must be 13-17 characters, got 3" ] } ``` For solicitation numbers and UEIs, the response has no `errors` array: ```json { "result": "not_valid", "type": "uei", "value": "A1B2C3D4E5I6" } ``` ### Low confidence (HTTP 200, solicitations only) ```json { "result": "low_confidence", "type": "solicitation", "value": "W911NF21C000100000000000000005" } ``` ### Validation errors (HTTP 400) Missing or invalid `type`: ```json { "error": "type must be one of: piid, solicitation, uei", "code": "validation_error" } ``` Missing or blank `value`: ```json { "error": "value is required and must not be blank", "code": "validation_error" } ``` ## Examples ### Validate a PIID ```bash curl -X POST https://tango.dev/api/validate/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{"type": "piid", "value": "W58RGZ25F1234"}' ``` ### Validate a solicitation number ```bash curl -X POST https://tango.dev/api/validate/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{"type": "solicitation", "value": "SPE7A619T4321"}' ``` ### Validate a UEI ```bash curl -X POST https://tango.dev/api/validate/ \ -H "X-API-KEY: your-api-key" \ -H "Content-Type: application/json" \ -d '{"type": "uei", "value": "A1B2C3D4E5F6"}' ``` --- --- description: "Endpoints, filtering, ordering, and metrics for /api/vehicles/, Tango's solicitation-centric grouping of IDVs." tags: [vehicles, api, reference] updated: 2026-10-24 --- # Vehicles Vehicles are a solicitation-centric grouping of multiple IDVs (the "thing people usually mean" when they say "this vehicle"), exposed at `/api/vehicles/`. If you want the conceptual model first, start with [Getting Started – Vehicles](../guides/patterns/vehicles.md). For field definitions, see the [Vehicles Data Dictionary](../data-dictionary/vehicles.md). ## Endpoints - `GET /api/vehicles/` (list + filtering + search + ordering) - `GET /api/vehicles/{uuid}/` (detail; supports shaping) - `GET /api/vehicles/{uuid}/awardees/` (the underlying IDVs; supports `?search=` and shaping) - `GET /api/vehicles/{uuid}/orders/` (task orders / contracts under all IDVs in the vehicle; behaves like `/api/contracts/`) ## Filtering The list endpoint supports a rich filter set across enums, reference codes, org hierarchy, numeric ranges, and dates. Multi-value enum filters use pipe (`|`) for OR semantics, e.g. `?vehicle_type=A|B|C`. | Param | What it does | | --- | --- | | `search` | Full-text vehicle search (solicitation identifier + aggregated award terms). | | `vehicle_type` | Vehicle (IDV) type code (e.g. `A`, `B`). Multi-value via `\|`. Case-insensitive. | | `type_of_idc` | Type of IDC code. Multi-value via `\|`. | | `contract_type` | Contract type code (`J`, `M`, etc.). Multi-value via `\|`. | | `set_aside` | Set-aside type (`8A`, `8AN`, `BICiv`, etc.). Multi-value via `\|`. | | `who_can_use` | Who-can-use code. | | `naics_code` | NAICS code (exact integer). | | `psc_code` | Product / Service Code. | | `program_acronym` | Program acronym (`SEWP`, `OASIS`, `GSA Schedule`, etc.). | | `agency` | Awarding agency or department. Examples: `GSA`, `DOD`, `DHS`. Multi-value via `\|`. | | `organization_id` | Awarding organization UUID (exact match). | | `total_obligated_min` / `total_obligated_max` | Total obligated USD lower / upper bound. | | `idv_count_min` / `idv_count_max` | Number of child IDVs lower / upper bound. | | `order_count_min` / `order_count_max` | Number of task orders lower / upper bound. | | `fiscal_year` | Fiscal year (YYYY). | | `award_date_after` / `award_date_before` | Award-date range (YYYY-MM-DD). Invalid dates or inverted ranges return **400**. | | `last_date_to_order_after` / `last_date_to_order_before` | Last-date-to-order range (YYYY-MM-DD). | > Range filters are not exposed for `vehicle_obligations`, `holder_count`, `order_winner_count` or `awardee_count`. Use the corresponding `total_obligated_min/max` and `order_count_min/max` parameters instead β€” they cover the same use cases against the precomputed rollup fields. ### Vehicle awardee filtering and search `GET /api/vehicles/{uuid}/awardees/` supports `?search=` for entity-aware full-text search across the underlying IDVs (PIID, key, solicitation_identifier, NAICS, PSC, recipient name / address). Pagination is page-based. On the **detail** endpoint (`GET /api/vehicles/{uuid}/`), `?search=` does *not* search vehicles β€” it filters the expanded awardees when your `?shape=` includes `awardees(...)`. Example: ```bash GET /api/vehicles/{uuid}/?shape=uuid,solicitation_identifier,awardees(key,piid,recipient(display_name,uei))&search=deloitte ``` ## Ordering Vehicles support `?ordering=` with a strict allowlist (8 fields). Prefix with `-` for descending; combine with commas for multi-field sort. - `vehicle_obligations` β€” sum of obligations across child orders (computed at query time) - `latest_award_date` β€” most recent IDV award date in the vehicle (computed at query time) - `total_obligated` β€” direct column rollup - `award_date` β€” earliest IDV award date - `last_date_to_order` β€” latest "last date to order" across IDVs - `fiscal_year` β€” vehicle fiscal year - `idv_count` β€” precomputed count of IDVs in the vehicle - `order_count` β€” precomputed count of orders against the vehicle's IDVs Examples: - Most obligations first: `?ordering=-vehicle_obligations` - Soonest stop-orders first: `?ordering=last_date_to_order` - Combined: `?ordering=-total_obligated,-award_date` When no `?ordering=` is provided, results are returned in `solicitation_identifier, agency_id, uuid` order. ## Pagination Vehicle lists use **page-number** pagination: - `page` (default 1) - `limit` (max 100) Vehicle awardees and vehicle orders also use page-number pagination (`page`, `limit`). Vehicle orders is optimized internally for date-ordered traversal of very large vehicles, but the response contract is the same as every other paginated endpoint: page-based with `next` / `previous` URLs and a `count`. ## Response shaping Vehicles use the shaping pipeline by default. Even without `?shape=` you'll get a curated default response. **Default LIST shape**: `agency_details, award_date, awardee_count, contract_type, description, fiscal_year, holder_count, idv_count, last_date_to_order, latest_award_date, name, naics_code, order_count, order_winner_count, organization, program_acronym, psc_code, set_aside, solicitation_date, solicitation_identifier, solicitation_title, total_obligated, type_of_idc, uuid, vehicle_contracts_value, vehicle_obligations, vehicle_type, who_can_use` Of the three company counts, `holder_count` is how many companies hold the vehicle's contracts and `order_winner_count` is how many have won a task order under it; `awardee_count` is a deprecated alias of `order_winner_count`. **Default DETAIL shape** is a superset: adds `agency_details(*)` (expanded), `agency_id`, `competition_details(*)`, `metrics(*)`, `opportunity_id`, `solicitation_description`. ### Available expansions | Expansion | Description | | --- | --- | | `awardees(...)` | The underlying IDVs that make up the vehicle. Supports `?search=` filtering on detail. | | `opportunity(...)` | Linked SAM.gov Opportunity (full Opportunity shape β€” `office`, `attachments`, `meta`, etc.). | | `competition_details(*)` | Aggregated competition information (12 sub-fields including `extent_competed`, `set_aside`, `solicitation_procedures`, `number_of_offers_received`). | | `agency_details(*)` | Aggregated awarding/funding office. Returned on detail (`GET /api/vehicles/{uuid}/`); list responses return a null stub for this field. | | `metrics(*)` | 12 computed vehicle metrics (HHI, competed-rate, top-recipient share, etc.). | | `organization(*)` | Canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Both bare `?shape=organization` (leaf) and `?shape=organization(*)` (expand) work β€” both converge on the same cached lookup. | Vehicles also support `flat=true|false`, `flat_lists=true|false`, and `joiner=.` (relevant only when `flat=true`). See [Response Shaping](../guides/patterns/response-shaping.md). ### Synthetic GWAC vehicles Some GWAC vehicles lack a real solicitation number. Tango synthesizes a vehicle for them so the grouping still works; consumers can identify them via: - `is_synthetic_solicitation` (boolean) β€” true on synthetic rows - `program_acronym` β€” the GWAC's identifier (e.g. `SEWP`) - `solicitation_identifier` β€” the user-facing value, with the internal `ACRO:` storage prefix stripped ## SDK examples > **See also:** Full SDK method reference β€” [tango-python methods](../sdks/python/api-reference.md) Β· [tango-node methods](../sdks/node/api-reference.md). The Python SDK exposes first-class methods for all three vehicle endpoints. ### List vehicles (search + ordering + filters) === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_vehicles( search="SEWP", program_acronym="SEWP", ordering="-vehicle_obligations", page=1, limit=10, ) print("count:", resp.count) for v in resp.results: print(v.uuid, v.solicitation_identifier, v.vehicle_obligations) ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); // Workaround until the Node SDK ships a first-class listVehicles() const http = (client as any).http; const data = await http.get("/api/vehicles/", { search: "SEWP", program_acronym: "SEWP", ordering: "-vehicle_obligations", page: 1, limit: 10, }); console.log("count:", data.count); ``` ### Vehicle detail with metrics and organization === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) vehicle_uuid = "00000000-0000-0000-0000-000000000000" # replace v = client.get_vehicle( vehicle_uuid, shape="uuid,solicitation_identifier,vehicle_obligations,metrics(*),organization(*)", ) print(v["uuid"], v["organization"]["agency_name"]) ``` ### Vehicle awardees with search === "Python (tango-python)" ```python resp = client.list_vehicle_awardees( "00000000-0000-0000-0000-000000000000", # vehicle UUID is positional (kwarg name: uuid) search="deloitte", limit=25, ) for awd in resp.results: print(awd.piid, awd.recipient.display_name) ``` ### Vehicle orders (task orders) === "Python (tango-python)" ```python resp = client.list_vehicle_orders( "00000000-0000-0000-0000-000000000000", # vehicle UUID is positional (kwarg name: uuid) ordering="-award_date", limit=50, ) print("orders:", resp.count) ``` --- --- description: "The GET /api/version/ endpoint, which returns the deployed Tango API version and build date." updated: 2026-08-18 --- # Version Inspect the deployed Tango API version and build date. Useful for logging, support tickets, and client-side feature detection. ## Endpoint `GET /api/version/` No authentication required. ## Response | Field | Type | Description | | --- | --- | --- | | `version` | string | Semantic version string (e.g. `4.4.0`). Bumped on each release per [Keep a Changelog](https://keepachangelog.com/) conventions; see the [public Changelog](../CHANGELOG.md). | | `date` | string | RFC 2822 build / release date (e.g. `"Mon, 08 May 2026 12:17:42 GMT"`). | ```json { "version": "4.4.0", "date": "Mon, 08 May 2026 12:17:42 GMT" } ``` ## Example ```bash curl -sS https://tango.dev/api/version/ ``` ## When to use - **Bug reports**: include the live `version` value alongside the request that failed; it speeds up triage. - **Client compatibility**: an SDK can refuse to start (or warn) when the API is older than its minimum supported version. - **Cache invalidation**: a version bump is a good signal to invalidate any client-side cached schemas (e.g. response-shape help retrieved via `?show_shapes=true`). --- --- description: "Field definitions for the agency object as it appears in response-shaping expansions across other endpoints." updated: 2026-04-13 --- # Agencies Data Dictionary This document describes the fields available on the agency data structure as it appears in response shaping expands across multiple endpoints (e.g., contracts, opportunities). For filtering, ordering, and pagination on the standalone endpoint, see the [Agencies API Reference](../api-reference/agencies.md). For the unified federal hierarchy, see [Organizations](organizations.md). ## Overview Agencies are federal organizations that sit below departments in the federal hierarchy. When expanded via response shaping (e.g., `agency(code,name,abbreviation)`), agency objects use the fields below. ## Update Frequency Agency data is updated **monthly** via the organization sync process from the Federal Hierarchy (SAM.gov). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | String | FPDS 4-digit agency code (primary key for the legacy endpoint). | FPDS / USAspending | | `name` | String | Full agency name. | Federal Hierarchy (SAM.gov) | | `abbreviation` | String | Common abbreviation (e.g., "NASA"). | Federal Hierarchy (SAM.gov) | ## Expansions | Expansion | Fields | Description | | --------- | ------ | ----------- | | `department(...)` | `code`, `name`, `abbreviation`, `description`, `cgac`, `website`, `congressional_justification` | Parent department. See [Departments data dictionary](departments.md). | ## Usage Notes - **Use `code` for lookups.** The agency `code` is the FPDS 4-digit identifier used in contract and financial assistance transactions. - **Prefer Organizations for new integrations.** The agency data structure is a legacy shape. Use the [Organizations API](../api-reference/organizations.md) for the full hierarchy with richer search and obligation data. ## Data Sources - **Federal Hierarchy (SAM.gov)** β€” Authoritative source for agency names and hierarchy position. - **FPDS / USAspending** β€” Agency codes (FPDS 4-digit) as they appear in contract and financial transactions. --- --- description: "Field definitions and code values for /api/assistance/direct_payments/, Tango's endpoint for direct payments for a specified use or with unrestricted use." tags: [assistance, payments, awards, schema, reference] updated: 2026-10-27 --- # Direct payments Data Dictionary This document describes the fields on `/api/assistance/direct_payments/`. The four financial-assistance endpoints share one schema; the others are [Grant awards](assistance-grants.md) Β· [Loans](assistance-loans.md) Β· [Other assistance](assistance-other.md). For filtering, search, ordering and pagination, see the [Direct payments API Reference](../api-reference/assistance-direct-payments.md). For how the pieces fit together, see the [Financial assistance overview](../api-reference/assistance.md). ## 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. Roughly seven in ten records on this endpoint are aggregate (`1`) or PII-redacted (`3`), which have no recipient, because so many direct payments go to individual people. Aggregate records carry a `uri` instead of a `fain`. ## Identifiers - `key` (canonical): Tango's award identifier, built from USAspending's award ID. It's what the API uses for lookups: `GET /api/assistance/direct_payments/{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](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype). ## 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). | | `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](#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-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](#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`](#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](entities.md), 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](#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](#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](../api-reference/shared.md#office). ### `assistance_listing` The award's primary assistance listing from the [assistance listings catalog](assistance-listings.md): `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](#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/direct_payments/{key}/listings/`. ### `transactions` Every action on the award, latest first. Also available, paginated, at `GET /api/assistance/direct_payments/{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](#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](#assistance-types). | | `correction_delete_indicator` | `C` when the record corrects an earlier one; `null` on an original record. See [Correction indicators](#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/direct_payments/` holds: | Code | Description | | --- | --- | | `F006` | Direct Payment for Specified Use | | `F007` | Direct Payment with Unrestricted Use | Older actions carry legacy two-digit codes. These map to this endpoint's GSDM codes: | Legacy code | Description | GSDM code | | --- | --- | --- | | `06` | Direct payment for specified use | `F006` | | `10` | Direct payment with unrestricted use | `F007` | ### 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. --- --- description: "Field definitions and code values for /api/assistance/grants/, Tango's endpoint for grant and cooperative-agreement awards." tags: [assistance, grants, awards, schema, reference] updated: 2026-10-27 --- # Grant awards Data Dictionary This document describes the fields on `/api/assistance/grants/`. The four financial-assistance endpoints share one schema; the others are [Loans](assistance-loans.md) Β· [Direct payments](assistance-direct-payments.md) Β· [Other assistance](assistance-other.md). For filtering, search, ordering and pagination, see the [Grant awards API Reference](../api-reference/assistance-grants.md). For how the pieces fit together, see the [Financial assistance overview](../api-reference/assistance.md). ## 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 grant, `obligated` and `pragmatic_obligations` are the same figure: the money obligated to the recipient. `non_federal_funding_amount` is the recipient's cost share. `funding_opportunity_number` and `funding_opportunity_goals_text` link the award to its Grants.gov opportunity, when the agency reported one. ## Identifiers - `key` (canonical): Tango's award identifier, built from USAspending's award ID. It's what the API uses for lookups: `GET /api/assistance/grants/{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](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype). ## 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). | | `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](#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-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](#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`](#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](entities.md), 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](#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](#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](../api-reference/shared.md#office). ### `assistance_listing` The award's primary assistance listing from the [assistance listings catalog](assistance-listings.md): `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](#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/grants/{key}/listings/`. ### `transactions` Every action on the award, latest first. Also available, paginated, at `GET /api/assistance/grants/{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](#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](#assistance-types). | | `correction_delete_indicator` | `C` when the record corrects an earlier one; `null` on an original record. See [Correction indicators](#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/grants/` holds: | Code | Description | | --- | --- | | `F001` | Grant | | `F002` | Cooperative Agreement | Older actions carry legacy two-digit codes. These map to this endpoint's GSDM codes: | Legacy code | Description | GSDM code | | --- | --- | --- | | `02` | Block grant | `F001` | | `03` | Formula grant | `F001` | | `04` | Project grant | `F001` | | `05` | Cooperative agreement | `F002` | ### 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. --- --- description: "Field definitions for /api/assistance_listings/, the CFDA program reference endpoint." updated: 2026-05-13 --- # Assistance Listings (CFDA) Data Dictionary This document describes the fields available in the Assistance Listings API endpoints (`/api/assistance_listings/`). For filtering, ordering, and pagination, see the [Assistance Listings API Reference](../api-reference/assistance-listings.md). ## Overview Assistance listings are CFDA (Catalog of Federal Domestic Assistance) program codes used for federal grants and assistance. Each listing has a `number` (e.g., "84.027") and `title`. This is **reference data**: the catalog of programs. Financial-assistance awards carry these numbers in `cfda_number` and break their money out by listing in `listings`; see the [financial-assistance data dictionaries](index.md#financial-assistance). Data is sourced from USAspending reference files. **Note**: This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. On list requests, the default shape is `number,title`. Detail responses use the full serializer when no `?shape=` is provided. ## Update Frequency Assistance listing reference data is updated when USAspending CFDA reference data is refreshed (periodic). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `number` | String | CFDA program number (primary key; digits and dots, e.g., "84.027"). | USAspending | | `title` | String | Program title. | USAspending | | `popular_name` | String | Popular or common name, when available. | USAspending | | `objectives` | Text | Program objectives. | USAspending | | `applicant_eligibility` | Text | Applicant eligibility description. | USAspending | | `benefit_eligibility` | Text | Benefit eligibility description. | USAspending | | `published_date` | Date | Date published. | USAspending | | `archived_date` | Date | Date archived, when applicable. | USAspending | ## Data Sources - **USAspending** – CFDA reference data (e.g., cfda.csv). ## Usage Notes - **Use `number` for lookups.** Detail at `/api/assistance_listings/{number}/` (number supports digits and `.`). This endpoint is for the **reference list** only; for assistance **transactions** use the assistance/awards endpoints; see [Assistance Listings API Reference](../api-reference/assistance-listings.md). --- --- description: "Field definitions and code values for /api/assistance/loans/, Tango's endpoint for direct loans and loan guarantees." tags: [assistance, loans, awards, schema, reference] updated: 2026-10-27 --- # 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](assistance-grants.md) Β· [Direct payments](assistance-direct-payments.md) Β· [Other assistance](assistance-other.md). For filtering, search, ordering and pagination, see the [Loans API Reference](../api-reference/assistance-loans.md). For how the pieces fit together, see the [Financial assistance overview](../api-reference/assistance.md). ## 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](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype). ## 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). | | `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](#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-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](#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`](#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](entities.md), 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](#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](#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](../api-reference/shared.md#office). ### `assistance_listing` The award's primary assistance listing from the [assistance listings catalog](assistance-listings.md): `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](#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](#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](#assistance-types). | | `correction_delete_indicator` | `C` when the record corrects an earlier one; `null` on an original record. See [Correction indicators](#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. --- --- description: "Field definitions and code values for /api/assistance/other/, Tango's endpoint for insurance, asset forfeiture, sales or donations of property, and other assistance." tags: [assistance, insurance, awards, schema, reference] updated: 2026-10-27 --- # Other assistance Data Dictionary This document describes the fields on `/api/assistance/other/`. The four financial-assistance endpoints share one schema; the others are [Grant awards](assistance-grants.md) Β· [Loans](assistance-loans.md) Β· [Direct payments](assistance-direct-payments.md). For filtering, search, ordering and pagination, see the [Other assistance API Reference](../api-reference/assistance-other.md). For how the pieces fit together, see the [Financial assistance overview](../api-reference/assistance.md). ## 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. This endpoint also holds awards whose assistance type is not specified (`-1`). `insurance_coverage_amount` is reported only for FEMA's National Flood Insurance Program (`97.022`). ## Identifiers - `key` (canonical): Tango's award identifier, built from USAspending's award ID. It's what the API uses for lookups: `GET /api/assistance/other/{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](../guides/patterns/response-shaping.md#financial-assistance-apiassistancetype). ## 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). | | `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](#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-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](#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`](#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](entities.md), 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](#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](#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](../api-reference/shared.md#office). ### `assistance_listing` The award's primary assistance listing from the [assistance listings catalog](assistance-listings.md): `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](#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/other/{key}/listings/`. ### `transactions` Every action on the award, latest first. Also available, paginated, at `GET /api/assistance/other/{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](#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](#assistance-types). | | `correction_delete_indicator` | `C` when the record corrects an earlier one; `null` on an original record. See [Correction indicators](#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/other/` holds: | Code | Description | | --- | --- | | `F005` | Indemnity/Insurance | | `F008` | Asset Forfeiture/Equitable Sharing | | `F009` | Sale, Exchange, or Donation of Property and Goods | | `F010` | Other Financial Assistance | | `-1` | Not specified | Older actions carry legacy two-digit codes. These map to this endpoint's GSDM codes: | Legacy code | Description | GSDM code | | --- | --- | --- | | `09` | Insurance | `F005` | | `11` | Other reimbursable, contingent, intangible or indirect financial assistance | `F010` | ### 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. --- --- description: "Field definitions for /api/news/award_announcements/, including which fields each source fills, the value and action vocabularies, and the awardee, organization and corrections structures." updated: 2026-10-30 --- # Award announcements Data Dictionary This document describes the fields available on the award announcements API endpoint (`/api/news/award_announcements/`). For filtering, ordering, and pagination, see the [Award announcements API Reference](../api-reference/award-announcements.md). ## Overview Each row is one announcement of an award, from one of two sources, named on every row. | `source` | `source_name` | Coverage | Text | | --- | --- | --- | --- | | `official_release` | `Department of War daily contracts release` | Awards of $7.5 million or more, from March 2026 | As published by the Department of War | | `makegov_generated` | `MakeGov, generated from FPDS award data` | New civilian IDVs of $25 million or more and every new OTA and OT IDV, from June 2026 | Written by MakeGov from FPDS award data, with a language model summarizing the purpose and writing the title. Not government text. | **Authentication**: this endpoint requires authentication (API key or OAuth2). **Plans**: every field is available on every plan, including Free. **Note**: The full field set is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md). ## Update Frequency Both sources are read daily. An official row appears after its release is published, and a generated row appears after the award reaches FPDS. ## Identity The primary key and detail-lookup value is `uuid`. - **Official rows:** `uuid` is derived from the release and the paragraph's position in it, so it is stable. - **Generated rows:** `uuid` follows the announcement's earliest-seen award, so it holds when more awards join the row. When two rows merge, the older `uuid` survives. A generated row is removed when an official release comes to cover the same award, so its `uuid` then returns 404. `source_record_id` on a generated row is not stable; store `uuid` instead. ## Fields "Filled on" says which source populates a field: **Both**, **Official** or **Generated**. A field is `null` on the other source, and any field can be `null` where the source doesn't state a value. | Field | Type | Description | Filled on | | --- | --- | --- | --- | | `uuid` | UUID | Primary key. See [Identity](#identity). | Both | | `source` | String | `official_release` or `makegov_generated`. | Both | | `source_name` | String | The source's display name. | Both | | `source_url` | String | The release on war.gov. Always `null` on a generated row, which has no page to link to. | Official | | `source_record_id` | String | On an official row, the release's article id and the paragraph's position, as `article:position`. On a generated row, an opaque key that can change. | Both | | `published_date` | Date | Official: the date of the release. Generated: the date MakeGov first announced the award, which does not move when the row is updated. Rows from the initial backfill carry their award date. | Both | | `award_date` | Date | The award's date; the earliest of them when a row covers several awards. A release states dates only in its text, so this is `null` on an official row. | Generated | | `title` | String | Official: the title of the day's release, such as `Contracts for Oct. 1, 2026`, shared by every paragraph in it. Generated: a title written by a language model, which can be `null`. | Both | | `text` | String | The announcement. Official: as published, unchanged by any correction. Generated: written by MakeGov. In the list response only when named in `shape`. | Both | | `amount` | Decimal | The headline dollar figure, in US dollars, including any applied correction. Read it with `value_kind`. | Both | | `value_kind` | String | What `amount` measures β€” see [`value_kind`](#value_kind). | Both | | `obligated_at_award` | Decimal | Funds obligated at award. Official: as stated in the release, and `0` when it says none are. Generated: the FPDS figure when every award in the row has had a single action, and `null` otherwise. | Both | | `action_type` | String | What the announcement reports β€” see [`action_type`](#action_type). Always `new_award` on a generated row. | Both | | `announcement_type` | String | The kind of generated announcement β€” see [`announcement_type`](#announcement_type). | Generated | | `award_kind` | String | The kind of award linked. Official: `contract` or `idv`, or `null` until the award links. Generated: `idv`, `ota` or `otidv`. | Both | | `awardee_count` | Integer | The number of awardees named. | Both | | `piids` | Array of String | Contract numbers named, upper-cased with dashes and other punctuation removed. Official rows hold no OT agreement numbers. | Both | | `award_uuids` | Array of UUID | Tango awards the announcement links to. On an official row these fill in as FPDS catches up, which can take up to 90 days. | Both | | `civilian` | Boolean | `true` for a civilian award. Always `false` on an official row; `false` on a generated row for a DoD OTA or OT IDV. | Both | | `component` | String | The DoD component heading the paragraph in the release, such as `NAVY`, normalized to one spelling per organization. | Official | | `contracting_activity` | String | The contracting activity named in the release. | Official | | `is_modification` | Boolean | `true` when the announcement reports a modification to an existing contract. | Official | | `is_multiple_award` | Boolean | Official: the announcement names more than one awardee. Generated: a multiple-award vehicle, which can name a single awardee. | Both | | `corrections` | Array of Object | The Department of War's corrections applied to the announcement β€” see [`corrections`](#corrections). | Official | | `is_withdrawn` | Boolean | `true` when a correction says the award was not released, not awarded or rescinded. Hidden from lists and alerts unless `include_withdrawn=true`, and always retrievable by `uuid`. | Official | | `awardees` | Array of Object | The awardees named β€” see [`awardees`](#awardees). An expansion. | Both | | `organization` | Object | The awarding organization β€” see [`organization`](#organization). An expansion. | Both | ## Vocabularies ### `value_kind` | Value | Meaning | Source | | --- | --- | --- | | `face_value` | A plain award value. On a generated row, the base and all options value of an award with no real ceiling. | Both | | `ceiling` | A maximum or not-to-exceed figure. | Both | | `combined_ceiling` | One figure shared across a multiple-award pool, never attributable to one awardee. | Official | | `estimated_value` | An estimated value. | Official | | `modification_value` | The value of a modification, option exercise or extension. | Official | | `cumulative_face_value` | Only the contract's cumulative face value is stated. | Official | | `unknown` | No headline figure was found. | Both | Don't sum or rank `amount` across kinds. ### `action_type` `new_award`, `modification`, `option_exercise`, `order` or `unknown`. A generated row is always `new_award`. ### `announcement_type` | Value | Meaning | | --- | --- | | `new_vehicle` | A new multiple-award vehicle. | | `on_ramp` | IDVs added to an existing vehicle. | | `single_award` | An IDV in no multiple-award vehicle. | | `vehicle_pending` | An IDV too recent to have been placed in a vehicle. | | `ota` | A new OTA. | | `ot_idv` | A new OT IDV. | ## Structured fields ### `awardees` An array with one object per awardee: | Key | Type | Description | | --- | --- | --- | | `name` | String | The awardee's name. | | `uei` | String or null | The awardee's UEI. Official releases print no UEI, so on an official row this is set only where one was resolved. | | `location` | String or null | The awardee's location. | | `small_business` | Boolean or null | Whether the release states the awardee is a small business. Always `null` on a generated row. | ### `organization` The canonical office payload for the awarding organization, or `null` when none resolved. On an official row it comes from the component heading; on a generated row it is the first award's awarding organization. | Key | Type | Description | | --- | --- | --- | | `organization_id` | UUID | The organization's id. | | `office_code` | String | The office code. | | `office_name` | String | The office name. | | `agency_code` | String | The agency code. | | `agency_name` | String | The agency name. | | `department_code` | String | The department code. | | `department_name` | String | The department name. | ### `corrections` An array, in publish order, with one object per correction applied to the announcement. It is `null` when none applied. | Key | Type | Description | | --- | --- | --- | | `article_id` | String | The release carrying the correction. | | `position` | Integer | The correction's position in that release. | | `publish_date` | Date | The date of that release. | | `text` | String | The correction as published. | | `changes` | Array of Object | Each change, as `{field, previous, corrected}`. | `changes[].field` is one of `contract_numbers`, `piids`, `announced_value`, `is_withdrawn`, `award_date` or `completion_date`. `announced_value` is the value served as `amount`. For `award_date` and `completion_date`, `previous` is `null` and `corrected` is an ISO date. ## Default shapes - **List** returns: `uuid`, `source`, `source_name`, `source_url`, `published_date`, `award_date`, `title`, `amount`, `value_kind`, `action_type`, `announcement_type`, `awardee_count`, `piids`, `is_modification`, `is_multiple_award`, `is_withdrawn`, `awardees(*)`. - **Detail** returns the list fields plus `source_record_id`, `text`, `obligated_at_award`, `award_kind`, `award_uuids`, `civilian`, `component`, `contracting_activity`, `corrections`, `organization(*)`. ## Usage Notes - **Check `source` before you quote `text`.** A `makegov_generated` paragraph reads like the official release, but it is not government text. - **Check the date you are filtering on.** `award_date` is `null` on every official row, so use `published_date` across both sources. - **Don't read `title` as the award's name on an official row.** Every paragraph of a release shares its title; the awardees are in `awardees` and `text`. - **Exclude withdrawn rows from counts and sums.** The list does this by default. ## Data Sources - **Department of War** β€” every official row, from the daily contracts release. - **FPDS** β€” the facts on every generated row. - **MakeGov** β€” the wording of generated rows, with a language model summarizing the purpose and writing the title. - **Tango** β€” `uuid`, `award_uuids` and `organization`. --- --- description: "Field definitions for /api/budget/accounts/ and its nested actions, the beta federal-account budget resource." updated: 2026-10-09 --- # Budget Data Dictionary !!! warning "Beta β€” surface may change" The `/api/budget/...` endpoints are **beta**. Field names, defaults, and groupings may still change. See the [API reference](../api-reference/budget.md) and the [exploration guide](../guides/how-to/explore-federal-budget.md). Field-level definitions for `/api/budget/accounts/` and its nested actions. For the request/response shape and filter syntax, see the [Budget API reference](../api-reference/budget.md). ## Overview Each row in `/api/budget/accounts/` is one **(federal account Γ— fiscal year)** snapshot of the full appropriation pipeline, with FPDS contract activity joined in. A "federal account" here is the [Treasury federal account](https://fiscaldata.treasury.gov/) β€” the standard `{agency_cgac}-{account_number}` grouping (e.g. `075-0512` = HHS NIH research). ## Update frequency | Source | Cadence | | --- | --- | | Lifecycle (requested / enacted / apportioned / obligated / outlayed) | Refreshed when upstream SF-133, MAX, and Treasury sources update β€” typically monthly, faster during budget season. | | Contract / assistance breakdown | Refreshed when the upstream FPDS-to-account join recomputes β€” typically nightly. | | Appendix object-class detail | Refreshed once per Budget cycle (annual + supplementals). | | Quarterly TAS detail (`/quarters/`) | Refreshed quarterly when Treasury publishes SF-133. | ## Identity | Field | Type | Description | | --- | --- | --- | | `federal_account_symbol` | String | Canonical key. Format `{agency_cgac}-{account_number}` (e.g. `075-0512`). | | `fiscal_year` | Integer | Fiscal year of the snapshot. | | `data_through_period` | Integer (nullable) | File A fiscal period (1–12) the account-year's figures run through. The latest fiscal year is partial until it reaches `12`, and its mid-year figures for indefinite and trust-fund appropriations can run high until year-end, so check this before comparing it with closed years. `null` when the row has no File A data. Filters: exact, `__gte`, `__lte`, `__isnull`. The `X-Tango-Data-As-Of` response header gives the latest period across the publication. | | `agency_code` | String | 3-character CGAC of the owning agency. | | `agency_name` | String | Full name of the owning agency. | | `bureau_name` | String | Bureau / sub-agency name as published in the source. Free text β€” use `__icontains` for fuzzy lookup. | | `account_title` | String | Human-readable account name. | | `bea_category` | String | Budget enforcement category: `Discretionary`, `Mandatory`, or `Net interest`. Null when no source carries a value. | | `on_off_budget` | String | `On-budget` or `Off-budget`. Null when no source carries a value. | | `subfunction_code` | String | OMB budget subfunction code (e.g. `051` = national defense, `551` = health care services). | | `account_category` | String | `budgetary`, `credit_financing`, `request_only` or `proposed`. Credit financing accounts are non-budgetary: they carry apportionments but no obligations and no `enacted_ba`. `request_only` accounts are current-law accounts with a President's Budget request and no File A data (for example NIH `075-9915`); `proposed` accounts are requests for programs Congress never created (for example the EV Fund `047-0623`). Both carry `requested_ba` but have null execution figures and `enacted_ba`. Sum apportionments, obligations and enacted budget authority with `account_category=budgetary`; sum a current-law `requested_ba` with `account_category__in=budgetary,request_only`. See [Account category](../api-reference/budget.md#account-category). | ## Lifecycle dollars The standard appropriation pipeline β€” what was asked for, what was authorized, what was released, what was spent, and what was paid out. Money fields are USD. | Field | Type | Description | | --- | --- | --- | | `requested_ba` | Float | Budget authority requested by the President. | | `enacted_ba` | Float | Budget authority enacted by Congress. | | `apportioned` | Float | Amount OMB has apportioned (released to the agency to spend). | | `obligated_total` | Float | Total obligated against this account. | | `outlayed_total` | Float | Total outlayed (cash actually paid). | | `unobligated_balance` | Float | Apportioned but not yet obligated. | ## Contract / assistance / unlinked breakdown Breaks `obligated_total` and `outlayed_total` into the three flows tracked separately. | Field | Type | Description | | --- | --- | --- | | `contract_obligated` | Float | Obligations attributable to contract awards (FPDS). | | `contract_outlayed` | Float | Outlays attributable to contract awards. | | `n_contracts` | Integer | Distinct contract count under this account-year. | | `n_unique_contract_recipients` | Integer | Distinct UEIs receiving contract dollars. | | `assistance_obligated` | Float | Obligations attributable to financial assistance (grants, loans, etc.). | | `assistance_outlayed` | Float | Outlays attributable to financial assistance. | | `n_grants` | Integer | Distinct grant count under this account-year. | | `n_unique_grant_recipients` | Integer | Distinct recipient count on the assistance side. | | `unlinked_obligated` | Float | Obligations that don't match either FPDS or USAspending assistance β€” internal transfers, misclassified rows, etc. | | `contract_share_of_obligated` | Float | `contract_obligated / obligated_total`. | | `contract_share_of_obligated_capped` | Float | Same ratio, bounded for sort/filter stability. | | `contract_share_capped_flag` | Boolean | `true` when the cap was applied to this row. | | `assistance_share_of_obligated` | Float | `assistance_obligated / obligated_total`. | | `assistance_share_of_obligated_capped` | Float | Same ratio, bounded. | | `assistance_share_capped_flag` | Boolean | `true` when the cap was applied. | ## Source anomalies `source_anomalies` is an array in the default shape, `[]` when the account-year is clean. Each element names one problem found in the source data for this row. The set of codes may grow. | `code` | Condition | `action` | | --- | --- | --- | | `contract_exceeds_obligations` | USAspending File C contract obligations exceed the account's positive File A total obligations. `contract_obligated` is capped at `obligated_total`. | `capped` | | `assistance_exceeds_obligations` | File C assistance obligations exceed positive File A total obligations (`assistance_share_capped_flag` is `true`). Values are served as reported. | `flagged` | | `contract_without_obligations` | File C reports contract obligations for an account whose File A total obligations are zero or negative. Values are served as reported. | `flagged` | Each element carries: | Field | Type | Description | | --- | --- | --- | | `code` | String | The anomaly, from the table above. | | `field` | String | The field the anomaly is about: `contract_obligated` for the two contract codes, `assistance_obligated` for `assistance_exceeds_obligations`. | | `bound_field` | String | The field it was checked against. Always `obligated_total`. | | `action` | String | `capped` (the served value was changed) or `flagged` (served as reported). | | `reported_value` | Float | The value as the source reported it, rounded to cents. | | `served_value` | Float | The value the API serves in `field`, rounded to cents. Equal to `reported_value` when `action` is `flagged`. | | `likely_cause` | String | `single_row_outlier` when the largest File C row in `source.rows` is at least half the excess over `obligated_total`; otherwise `file_c_ahead_of_file_a` when File A has not reached period 12 for the fiscal year, so File C may include periods File A has not reported yet; otherwise `unexplained`. `assistance_exceeds_obligations` carries no rows, so it is never `single_row_outlier`. | | `affected_fields` | Array[String] | The served fields the anomaly affects: `field` itself and the fields derived from it. Fixed per code. | | `message` | String | Human-readable description of the anomaly. One fixed sentence per code. | | `source` | Object | `dataset` (always `usaspending_file_c`), `fiscal_year` (Integer), and, for both contract codes, `rows`. `assistance_exceeds_obligations` has no `rows` key. | | `source.rows[]` | Array[Object] | Up to three of the largest PIID-linked File C rows on the account and fiscal year, largest `transaction_obligated_amount` first; `[]` when none were found. Each row carries `fiscal_period` (Integer), `piid` (String), `parent_piid` (String), `tas` (String), `reporting_agency_id` (String), `transaction_obligated_amount` (Float, rounded to cents), and `file_c_source` (`db_dump` or `bulk_zip`). Every row field except `piid` and `file_c_source` can be `null`. | There is no filter on `source_anomalies`. `source_anomalies`, `account_category` and `data_through_period` may be empty or default (`[]`, `budgetary`, `null`) until the next budget data refresh carries them. ## Forward-look The President's next-year request vs the current enacted level. | Field | Type | Description | | --- | --- | --- | | `next_year_requested_ba` | Float | BA requested for the following fiscal year. | | `ba_growth_next_year` | Float | `next_year_requested_ba - enacted_ba` (absolute dollar change). | | `ba_growth_next_year_pct` | Float | Relative change (`(next - current) / current`). | ## Ratios (lifecycle) Each lifecycle ratio ships in three variants: `*_pct` (raw), `*_pct_capped` (bounded for sort/filter stability β€” typically at 5.0), and `*_pct_capped_flag` (boolean β€” `true` when the cap was applied). Use raw for math, capped for filtering and visualization. | Field family | Numerator / denominator | What it tells you | | --- | --- | --- | | `enacted_to_requested_pct` | `enacted_ba / requested_ba` | Did Congress give more (>1.0) or less (<1.0) than the President asked? | | `apportioned_to_enacted_pct` | `apportioned / enacted_ba` | How much of enacted has OMB released to spend? | | `obligated_to_apportioned_pct` | `obligated_total / apportioned` | How much of released funds have been committed? | | `obligated_to_enacted_pct` | `obligated_total / enacted_ba` | How much of authorized funds have been committed? | | `outlayed_to_obligated_pct` | `outlayed_total / obligated_total` | How much of committed funds have actually been paid out? | | `unobligated_pct` | `unobligated_balance / apportioned` | Reciprocal pipeline-pressure signal. | ## Trends Year-over-year and 5-year movement signals. These are an opt-in shape cluster β€” pass them in `?shape=` to include them in the response. | Field | Type | Description | | --- | --- | --- | | `enacted_ba_yoy_pct` | Float | Year-over-year change in enacted BA vs prior FY. | | `obligated_yoy_pct` | Float | Year-over-year change in total obligations. | | `contract_obligated_yoy_pct` | Float | Year-over-year change in contract-side obligations. | | `enacted_ba_5yr_cagr` | Float | 5-year compound annual growth rate of enacted BA. | | `contract_obligated_5yr_cagr` | Float | 5-year CAGR of contract obligations. | ## Request-vs-actual (contract side) How the President's requested split of contractual services compares to actual contract spending. Opt-in cluster. | Field | Type | Description | | --- | --- | --- | | `requested_contractual_services` | Float | Object-class amount requested for contractual services. | | `requested_personnel_share` | Float | Ratio of requested personnel comp to total request. | | `actual_vs_requested_contract` | Float | `contract_obligated / requested_contractual_services`. | | `actual_vs_requested_contract_capped` | Float | Same, bounded. | | `actual_vs_requested_contract_capped_flag` | Boolean | `true` when the cap was applied. | ## Provenance + narrative | Field | Type | Description | | --- | --- | --- | | `appendix_pdf_url` | String | URL to the President's Budget Appendix PDF for this account. | | `account_narrative_excerpt` | String | Short excerpt from the appendix narrative. For full text use the `narratives(*)` shape leaf. | | `top_contract_recipients` | Array[String] | Lightweight name-only list of top contract recipients. Sparse (null when no recipients resolve to names). Use the `/recipients/` drill-down for analytical work β€” it carries UEI, hydrated entity payload, PIIDs, and the full Contract records. | | `top_grant_recipients` | Array[String] | Lightweight name-only list of top grant recipients. | | `created`, `modified` | Datetime | Standard timestamps. | ## Shape leaves These are **expansion** leaves, not flat fields. Pass `appendix(*)` or `narratives(*)` inside `?shape=...` to include them. ### `appendix(*)` β€” President's Budget Appendix object-class breakdown Returns a payload with all 16 OMB object-class request buckets plus appendix metadata. Coverage: FY08–FY27. Returns `null` for accounts with no Appendix data (typically large mandatory programs like Medicaid). Object-class buckets include: personnel comp, civilian personnel benefits, military personnel benefits, travel, transportation of things, rents/communications/utilities, printing, contractual services, supplies, equipment, land/structures, investments and loans, grants and subsidies, insurance claims, interest and dividends, refunds. Metadata: `appendix_granule_id`, `appendix_pdf_url`. ### `narratives(*)` β€” Appendix narrative + appropriations text Returns a list (some accounts have 2–3 narratives per year, split by subaccount). Each item carries the narrative text and the appropriations language. Text can run a few KB per field β€” only loaded when the leaf is in the request. ## Nested action payloads These are returned by `/recipients/` and `/quarters/`, not on the account detail itself. Documented in the [API reference](../api-reference/budget.md). | Surface | Shape per row | | --- | --- | | `/recipients/` | `funding_organization_id`, `funding_office{...}`, `recipient_id` (UEI), `recipient{...}`, `contract_obligated`, `contract_outlayed`, `n_contracts`, `contracts[]` (minimal Contract per PIID) | | `/quarters/` | `tas`, `quarter`, `period`, `obligated_quarterly`, `outlayed_quarterly`, `obligated_cumulative`, `outlayed_cumulative`, `quarterly_source` | ## Data sources | Source | What we use it for | | --- | --- | | OMB MAX A-11 / President's Budget | `requested_ba`, `next_year_requested_ba`, Appendix object-class detail, narrative text, `appendix_pdf_url`. | | Treasury SF-133 | `enacted_ba`, `apportioned`, `obligated_total`, `outlayed_total`, `unobligated_balance`, and the entire `/quarters/` surface. | | FPDS (federal contract awards) | `contract_obligated`, `contract_outlayed`, `n_contracts`, `n_unique_contract_recipients`, the `/recipients/` drill-down, and the entity `/budget-flows/`. | | USAspending File C | Cross-reference for matching FPDS obligations to specific TAS / federal accounts; backs the `unlinked_obligated` calculation. | --- --- description: "Field definitions for /api/business_types/, the SAM.gov business-type code reference endpoint." updated: 2026-05-13 --- # Business Types Data Dictionary This document describes the fields available in the Business Types API endpoints (`/api/business_types/`). For filtering, ordering, and pagination, see the [Business Types API Reference](../api-reference/business-types.md). ## Overview Business types are SAM.gov codes that classify entities (e.g., small business, 8(a), HUBZone). Each type has a `code` and `name`. Data is sourced from SAM.gov. **Note**: This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. Default shape: `name,code`. ## Update Frequency Business type reference data is updated when SAM.gov reference data is refreshed (periodic). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | String | SAM code for the business type (e.g., 2-character). | SAM.gov | | `name` | String | Human-readable business type name. | SAM.gov | | `certifier` | String | Certifier for the business type (e.g., SBA). | SAM.gov | ## Value formats and common values - **`code`**: 2-character alphanumeric, typically uppercase (examples: `A6`, `JT`, `XX`, `2R`). This is what entities store in `business_types`. - **`certifier`**: Who β€œowns” / attests the classification. In practice you’ll see a small set of values: - `SBA`: SBA-certified programs (e.g., 8(a), HUBZone, WOSB variants). - `AbilityOne`: AbilityOne nonprofit agency classification. - `Government`: Government-entity classifications (federal/state/local/tribal/foreign). - `Self`: Self-reported classifications in SAM (ownership/demographic/org-type, etc.). If you need the full canonical list in one place, the `/api/business_types/` endpoint is the source of truth. ## Data Sources - **SAM.gov** – Business type codes and names. ## Usage Notes - **Use `code` for lookups.** List and detail at `/api/business_types/` and `/api/business_types/{code}/`; see [Business Types API Reference](../api-reference/business-types.md). --- --- description: "Field definitions for /api/contract_appeals/, Tango's CBCA and ASBCA contract appeal decisions, including how dockets are normalized and which fields the boards' own listings do not publish." updated: 2026-09-21 --- # Contract Appeals Data Dictionary This document describes the fields available on the Contract Appeals API endpoint (`/api/contract_appeals/`). For filtering, ordering, and pagination, see the [Contract Appeals API Reference](../api-reference/contract-appeals.md). ## Overview Contract appeals are decisions of the two boards of contract appeals β€” the **Civilian Board of Contract Appeals (CBCA)**, covering most civilian agencies from 2007 forward, and the **Armed Services Board of Contract Appeals (ASBCA)**, covering the Department of Defense, NASA and the CIA from 2010 forward. About 8,200 decisions are available across the two boards. These are Contract Disputes Act appeals: a contractor disputes a contracting officer's final decision under a contract it already holds β€” a claim, a termination, delay, or the amount owed β€” and appeals it to the board with jurisdiction. They are **not bid protests**, which challenge an award or a solicitation and live in a separate resource, [Protests](protests.md). No record appears in both. One row is one decision as the board's own listing publishes it. A decision resolving several consolidated appeals is one row carrying several dockets. **Authentication**: Contract appeal endpoints require authentication (API key or OAuth2). **Plans**: every field except `decision_text` is available on every plan, including Free β€” as is the full-text search that runs over the decision text. `decision_text` itself requires an Enterprise plan; see [The decision body](#the-decision-body) below. **Note**: Contract appeals are a flat resource with no expandable relations. The full field set is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md). ## Update Frequency Both boards' listings are read daily, and new decisions appear in the API the same day they are picked up. Decision text is extracted from the boards' own documents on its own cadence, so a decision can be queryable before its text is. ## Identity The primary key and detail-lookup value is `uuid`. It is derived from the board and the decision's identity on that board's listing, not assigned sequentially, so it is stable across rebuilds of the dataset and safe to store alongside your own records. `document_id` identifies the underlying decision document. It is usually one-to-one with `uuid`, but not always: a handful of CBCA listing rows link the same document, so a `document_id` can appear on more than one decision. ## Dockets `docket_numbers` is an **array of strings**, because a single decision can resolve several consolidated appeals. Dockets are normalized to the form the board writes minus the board's own name: `CBCA 3288-R` is stored as `3288-R`, and an ASBCA docket is stored as the bare number, `59116`. The listing's verbatim text is kept in `docket_raw`. A quantum or remand docket can name its source dockets in parentheses β€” `7092-C(6682, 6765, 6767)`. That whole string is **one** docket, commas and all; the commas are part of the value, not a separator between values. `docket_source` says where the dockets came from: | Value | Meaning | | --- | --- | | `listing` | Parsed from the board's listing table β€” the usual case. | | `text` | Recovered from the decision document itself, where the listing published none. | | `admin` | Corrected by MakeGov staff after review. | | `null` | No docket was found for this decision. | **ASBCA decisions before 2014 generally have no dockets.** That board's listing gained a docket-number column in 2014, and nothing earlier is reverse-engineered from a filename. `?docket=` therefore cannot reach most pre-2014 ASBCA decisions; `?appellant=` and `?search=` can. ## Dates `decision_date` is the decision's own date as the board's listing gives it, parsed to a real date. Both listings are typed by hand, and the parsing is conservative: - `decision_date_raw` keeps the listing's cell verbatim, always, so you can see what was published. - `decision_date` is **null** where the cell cannot be read as a date with confidence. It is not guessed from the page it sits on. - `decision_date_repaired` is `true` on the small number of rows where a transposed year was put back β€” a cell reading `April 29, 2104` on the Board's 2014 page. The repair is applied only when un-swapping the digits yields the page's own year; anything else stays null. The original cell is still in `decision_date_raw`. `first_listed_at` is **Tango's** timestamp, not a board's: when the decision was first observed on a listing. It is the right field to poll on for "everything new since my last call", and the wrong field to read as a publication date β€” `decision_date` is that. ## Listing state `listed` is `true` while the board's newest listing still carries the decision. When a board drops a decision from its listing, `listed` flips to `false` and **the row is kept**. Nothing is deleted: a `uuid` you stored last year still resolves. Filter `?listed=true` for what the boards currently publish, or `?listed=false` to see what has come off. `listing_url` and `listing_year` say which listing page the decision came from. ## The decision body `decision_text` is the extracted text of the board's decision document, and it is the one **Enterprise-only** field on this resource. Three facts about it, in order of how often they surprise people: - **Searching it is free.** `?search=` runs over the decision text on every plan including Free, and returns matching decisions with no fragment of the body. Buying the body buys the body, not better search. - **Below Enterprise, naming it in a `shape` returns 200 with the field omitted** and an entry in `meta.upgrade_hints`. It is not an error, and the rest of the response is unaffected. - **It can be null at any plan**, because text extraction runs on its own cadence and some documents yield no text. `text_status` and `text_char_count` report that on every plan, so you can tell "we hold no text" from "the text did not match" without an Enterprise plan. | `text_status` | Meaning | | --- | --- | | `completed` | Text was extracted and is held. | | `empty` | Extraction succeeded and produced no characters β€” almost always a scanned document. | | `failed` | Extraction was attempted and did not succeed. | | `null` | Extraction has not been attempted for this document yet. | ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | String (UUID) | Stable primary key and detail-lookup value. | Tango | | `board` | String | `cbca` or `asbca`. | Tango | | `docket_numbers` | Array of String | The decision's dockets, board prefix stripped. Several on a consolidated appeal; empty where the listing published none. | Board / Tango | | `docket_source` | String | Where the dockets came from: `listing`, `text`, `admin`, or null. | Tango | | `docket_raw` | String | The listing's docket cell, verbatim. | Board | | `decision_date` | Date | Date of the decision. Null where the published cell could not be read as a date. | Board | | `decision_date_raw` | String | The listing's decision-date cell, verbatim. | Board | | `decision_date_repaired` | Boolean | Whether a transposed year was repaired from the listing page's own year. | Tango | | `appellant` | String | The appealing party as the listing names it. | Board | | `judge` | String | The authoring judge as the listing names them. | Board | | `decision_type` | String | CBCA only: `Decision`, `Dismissal`, `Order`, `Full Board Order`, or the listing's own wording where it matches none of those. Null on every ASBCA decision and on CBCA decisions before 2015, when that column was added. | Board / Tango | | `decision_type_raw` | String | The listing's type cell, verbatim. Null wherever `decision_type` is. | Board | | `url` | String | The board's own link to the decision document. Available on every plan. | Board | | `document_id` | String | Identifier for the underlying decision document. Not unique: a few CBCA listing rows link the same document. | Tango | | `listing_url` | String | The board listing page the decision was read from. | Board | | `listing_year` | Integer | The year of that listing page. | Board | | `first_listed_at` | Datetime | When Tango first observed the decision on a listing. The field to poll on. | Tango | | `listed` | Boolean | Whether the board's newest listing still carries the decision. A delisted decision is kept with `false`. | Tango | | `text_status` | String | `completed`, `empty`, `failed`, or null β€” see [The decision body](#the-decision-body). | Tango | | `text_char_count` | Integer | Character count of the extracted text, whether or not this response carries the text. | Tango | | `decision_text` | String | The extracted decision body. **Enterprise plans only**; omitted with an `upgrade_hints` entry below that. Null until extraction completes. | Board / Tango | ## Default shapes - **List** returns: `uuid`, `board`, `docket_numbers`, `decision_date`, `appellant`, `judge`, `decision_type`, `url`. - **Detail** returns the list fields plus `docket_raw`, `docket_source`, `decision_date_repaired`, `decision_type_raw`, `listing_year`, `first_listed_at`, `listed`, `text_status`, `text_char_count`. `decision_date_raw`, `document_id`, `listing_url` and `decision_text` are in neither default; name them in `?shape=` to get them. ## Usage Notes - **Do not look for a bid protest here.** GAO, Court of Federal Claims and SBA OHA cases are [Protests](protests.md); the two resources share no records. - **There is no agency, no UEI, and no contract number.** The boards' listings publish the appellant, the docket, the judge, the date and the document β€” they do not publish the procuring agency, a resolved vendor identity, or the contract under appeal. Those facts are often in the decision's own text, which is why `?search=` runs over it. - **Alerts follow the record, including its delisting.** `contract_appeal` is an alertable query type; a decision appearing, being delisted, or gaining its extracted text all fire. See [Webhooks](../webhooks/index.md). ## Data Sources - **CBCA** β€” the Civilian Board of Contract Appeals' published decision listing, from 2007 forward. - **ASBCA** β€” the Armed Services Board of Contract Appeals' published decision listings, from 2010 forward. - **Tango** β€” `uuid`, docket and date normalization, `first_listed_at`, `listed`, and the extracted decision text. --- --- description: "Field definitions for /api/contracts/, Tango's definitive contract award endpoint." updated: 2026-10-16 --- # 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](../api-reference/contracts.md). ## 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](../guides/patterns/response-shaping.md) for details. ## Update Frequency Contract data is refreshed by the Tango ingest 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 sourced from FPDS / USAspending and surfaced as `{code, description}` objects in responses. ### `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](../api-reference/set-aside.md) for the complete mapping.) ### `commercial_item_acquisition_procedures` | Code | Meaning | | --- | --- | | `A` | Commercial Products/Services | | `B` | Products or services pursuant to FAR 12.102(f) | | `C` | Services pursuant to FAR 12.102(g) | | `D` | Commercial Products/Services Procedures not used | | `E` | DoD - Section 803 CSO Procedures | Filter on this code with `commercial_item_acquisition_procedures` (see [Contracts API Reference](../api-reference/contracts.md#commercial-item-acquisition-procedures)). ## 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](../api-reference/contracts.md). --- --- description: "Field definitions for the department object as it appears in response-shaping expansions across other endpoints." updated: 2026-04-13 --- # Departments Data Dictionary This document describes the fields available on the department data structure as it appears in response shaping expands across multiple endpoints (e.g., contracts, opportunities). For filtering, ordering, and pagination on the standalone endpoint, see the [Departments API Reference](../api-reference/departments.md). For the unified federal hierarchy, see [Organizations](organizations.md). ## Overview Departments are top-level federal organizations. When expanded via response shaping (e.g., `department(code,name,abbreviation)`), department objects use the fields below. ## Update Frequency Department data is updated **monthly** via the organization sync process from the Federal Hierarchy (SAM.gov). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | String | CGAC 3-character department code (primary key for the legacy endpoint). | USAspending | | `name` | String | Full department name. | Federal Hierarchy (SAM.gov) | | `abbreviation` | String | Common abbreviation (e.g., "DOD"). | Federal Hierarchy (SAM.gov) | | `description` | String | Department description/mission. | Federal Hierarchy (SAM.gov) | | `cgac` | String | CGAC code (same as `code` for departments). | USAspending | | `website` | String | Department website URL. | Various | | `congressional_justification` | String | URL to congressional budget justification. | Various | ## Expansions None. ## Usage Notes - **Use `code` for lookups.** The department `code` is the CGAC 3-character identifier used in financial transactions. - **Prefer Organizations for new integrations.** The department data structure is a legacy shape. Use the [Organizations API](../api-reference/organizations.md) for the full hierarchy with richer search and obligation data. ## Data Sources - **Federal Hierarchy (SAM.gov)** β€” Authoritative source for department names, codes, and hierarchy structure. - **USAspending** β€” Supplements with CGAC codes used in financial transactions. --- --- description: "Field definitions for the DLA DIBBS RFQ, solicitation, and award endpoints, including why award totals must not be summed across line items." updated: 2026-10-29 --- # DIBBS Data Dictionary This document describes the fields available on the DIBBS API endpoints (`/api/dibbs/rfqs/`, `/api/dibbs/rfps/`, `/api/dibbs/awards/`). For filtering, ordering, and pagination, see the [DIBBS API Reference](../api-reference/dibbs.md). ## Overview DIBBS is the DLA Internet Bid Board System β€” the Defense Logistics Agency's board for small-purchase requests for quote (RFQs), larger solicitations (RFP/IFB), and awards. Every record is scoped to a National Stock Number (NSN) or manufacturer part number. All three resources are keyed by a synthetic `uuid` and carry an `organization` relation (always DLA). **Note**: The full field set on each resource is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Open/closed is derived RFQs and solicitations expose an `is_open` boolean and an `open` filter, both derived at query time from the record's closing date (`return_by_date` for RFQs, `closes_date` for solicitations). A passed or missing date is not open. Because it is derived, a record simply reaching its closing date does not change the stored row (and does not fire a webhook alert). Awards have no open/closed lifecycle. ## Awards are line items **A DIBBS award record is one line item, not a whole award.** `total_contract_price` is the **order's** total, replicated on every line item of that order β€” never `SUM()` it across records. To total spend, count each order once (dedupe by `award_number` + `delivery_order_number`). See the [API reference warning](../api-reference/dibbs.md#the-line-item-total-price-warning). ## RFQ fields (`/api/dibbs/rfqs/`) | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | String (UUID) | Synthetic primary key; the detail lookup value. | Tango | | `solicitation` | String | DLA solicitation number, e.g. `SPE1C126Q0337`. | DIBBS | | `solicitation_formatted` | String | Formatted solicitation number (detail default only). | DIBBS | | `purchase_request` | String | Purchase request number (second half of the natural key). | DIBBS | | `nsn` | String | National Stock Number. | DIBBS | | `part_number` | String | Manufacturer part number. | DIBBS | | `nomenclature` | String | Item nomenclature / description. | DIBBS | | `quantity` | Integer | Quantity requested. | DIBBS | | `unit_of_issue` | String | Unit of issue. | DIBBS | | `set_aside` | String | Set-aside flag (`Y` / `N`; other values normalize to null). | DIBBS | | `status_code` | String | 11-character composite DIBBS status code, e.g. `DLK00L1N000`. | DIBBS | | `return_by_date` | Date | RFQ close date. Drives `is_open`. | DIBBS | | `issue_date` | Date | DIBBS archive date (newest-wins arbitration signal). | DIBBS | | `is_open` | Boolean | Computed: whether the RFQ is still accepting quotes today. | Tango | | `document_url` | String | Link to the RFQ document. | DIBBS | | `organization` | Object | Buying organization (DLA), as the canonical 7-key office payload. Detail default only. | Tango | ## Solicitation (RFP) fields (`/api/dibbs/rfps/`) | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | String (UUID) | Synthetic primary key; the detail lookup value. | Tango | | `solicitation` | String | Solicitation number (null on pending `NEW` postings). | DIBBS | | `nsn` | String | National Stock Number. | DIBBS | | `part_number` | String | Manufacturer part number. | DIBBS | | `nomenclature` | String | Item nomenclature / description. | DIBBS | | `buyer_code` | String | DLA buyer code. | DIBBS | | `issued_date` | Date | DIBBS posting date (newest-wins arbitration signal). | DIBBS | | `closes_date` | Date | Solicitation close date. Drives `is_open`. | DIBBS | | `is_open` | Boolean | Computed: whether the solicitation is still accepting offers today. | Tango | | `document_url` | String | Link to the solicitation document. | DIBBS | | `tech_docs_url` | String | DLA TDMT technical-data-package link, when present. | DIBBS | | `organization` | Object | Buying organization (DLA), as the canonical 7-key office payload. Detail default only. | Tango | ## Award fields (`/api/dibbs/awards/`) | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | String (UUID) | Synthetic primary key; the detail lookup value. | Tango | | `award_number` | String | Award or basic contract number; for a delivery order, its parent contract. Order-scoped. | DIBBS | | `delivery_order_number` | String | The delivery order's own number (null on basic awards). Order-scoped. | DIBBS | | `delivery_order_counter` | String | Delivery-order counter (null on basic awards). Order-scoped. | DIBBS | | `nsn` | String | National Stock Number (line-item-scoped; mutually exclusive with `part_number`). | DIBBS | | `part_number` | String | Manufacturer part number (line-item-scoped). | DIBBS | | `purchase_request` | String | Purchase request number (line-item-scoped). | DIBBS | | `nomenclature` | String | Item nomenclature / description. | DIBBS | | `awardee_cage` | String | Awardee CAGE code (populated on every award row). Order-scoped. | DIBBS | | `total_contract_price` | Decimal | **Order** total, replicated per line item β€” never summable across rows. Null on ~3.5% of rows. | DIBBS | | `total_contract_price_text` | String | Raw price cell verbatim (e.g. `See Award Doc`) when non-numeric. | DIBBS | | `award_date` | Date | Award date. | DIBBS | | `posted_date` | Date | DIBBS posting date (newest-wins arbitration signal). | DIBBS | | `last_mod_posting_date` | Date | Last modification posting date (detail default only). | DIBBS | | `solicitation` | String | Solicitation number (present on ~35% of awards). Order-scoped. | DIBBS | | `awardee` | Object | Resolved Tango entity (`uei`, `cage_code`, `legal_business_name`); null when the CAGE is unresolved. | Tango | | `organization` | Object | Buying organization (DLA), as the canonical 7-key office payload. Detail default only. | Tango | ## Expansions (via `shape`) - `organization(*)` (all three) β†’ `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` β€” always DLA. - `awardee(*)` (awards only) β†’ `uei`, `cage_code`, `legal_business_name` from the resolved entity. ## Data Sources - **DIBBS** β€” the DLA Internet Bid Board System (RFQ, solicitation, and award records). - **Tango** β€” `uuid`, `is_open`, the resolved `organization` and `awardee`, and arbitration/normalization. ## Usage Notes - **Detail lookup is by `uuid`** on all three resources. - **`search`** covers nomenclature, NSN, part number, and solicitation number (awards also include award number). - **Federal Supply Class** is the first four digits of `nsn`; filter on it with `?fsc=6515|6530` (exactly four digits per value, otherwise **400**). There is no separate FSC field. - **Alerts** cover RFQs and solicitations (`dibbs_rfq`, `dibbs_rfp` query types); awards are not alertable. See [Webhooks](../webhooks/index.md). --- --- description: "Field definitions for /api/ebuy/requests/, GSA eBuy requests scoped to your own Schedule contracts, including why status is frozen and how attachments and links differ." updated: 2026-11-10 --- # eBuy Data Dictionary This document describes the fields available on the eBuy API endpoint (`/api/ebuy/requests/`). For access, filtering, ordering, and pagination, see the [eBuy API Reference](../api-reference/ebuy.md). ## Overview eBuy requests are the requests for quote (RFQ), requests for proposal (RFP) and requests for information (RFI) that agencies post to GSA Schedule holders through GSA eBuy. eBuy is not public data. GSA shows a Schedule holder only the requests posted under the SINs on that holder's own contracts, and Tango keeps the same boundary: you see a request only while your account is linked to a contract it was posted under. What this resource contains is therefore specific to your account. One row is one eBuy request, identified by its eBuy request id (`rfq_id`). **Authentication**: eBuy endpoints require authentication (API key or OAuth2). **Plans**: a Medium plan or above, **and** a contract link that MakeGov sets up for your account. Free and Small plans receive HTTP 403. See [Checking your access](../api-reference/ebuy.md#checking-your-access). ## Update Frequency Tango captures eBuy on a recurring schedule. Each capture updates the requests it observes and advances their `last_seen`. ## `status` is frozen `status` is `Open` or `Cancelled`, exactly as eBuy supplied it, and it is **never recomputed**. eBuy's feed carries only currently active requests; a request that closes stops appearing rather than arriving with a closed status. An `Open` request may therefore have closed long ago. - **`last_seen`** is when Tango last observed the request in eBuy. It is the field to judge staleness by. - **`close_date`** is the buyer's stated deadline. ## Detail and list captures Most requests are captured from their eBuy detail page. A request eBuy lists but whose detail page was not reached carries only the list-level fields β€” title, dates, buyer, SIN β€” and `detail_fetched` is `false`. Its description, contracting-officer block and structured fields may be empty. `mod_version` is the amendment version eBuy's list reports, and it is the only amendment evidence on a request whose detail page was not reached. ## Attachments `attachments` is available on the detail endpoint and through the `attachments(...)` expansion. Each entry is either a **document** or a **link**: | Field | Type | Description | | --- | --- | --- | | `doc_seq_num` | Integer | eBuy's sequence number for the entry within the request. Addresses the [download endpoint](../api-reference/ebuy.md#attachments). | | `doc_name` | String | File name, or the link's label. | | `doc_type` | Integer | eBuy's numeric document-type code, as supplied. | | `doc_path` | String | For a link, the outbound URL. For a document, eBuy's own path β€” use the download endpoint instead. | | `is_link` | Boolean | `true` for an outbound link with no file behind it; `false` for a downloadable document. | | `doc_session_date` | Datetime | eBuy's timestamp for the entry, as supplied. | | `extracted_text` | String | The text extracted from a document. Returned only when named in `?shape=` β€” `attachments(*)` does not include it β€” and omitted for a link or a document with no text. See [Attachment text](../api-reference/ebuy.md#attachment-text). | `attachment_count` and `link_count` on the request count every document and link ever observed on it. After an amendment removes a document from eBuy's page, the counts can exceed what eBuy currently shows. ## Structured fields These are eBuy's own structures, returned as JSON arrays with eBuy's key names (camelCase). They are empty arrays, not null, when a request has none. ### `amendments` One object per amendment: | Key | Type | Description | | --- | --- | --- | | `version` | Integer | Amendment version number. | | `time` | String | When the amendment was made, as eBuy formats it. | | `note` | String | The buyer's note describing the amendment. | | `identifier` | String or null | An amendment identifier, where given. | ### `line_items` Product line items, present mainly on requests for products rather than services. Commonly used keys: `rfqItemId`, `productDescription`, `manufactureName`, `manufacturePartNum`, `quantity`, `unit`, `price` and `addressIndex` (an index into `addresses`). eBuy also includes quote-workflow flags (`quoted`, `selected`, `valid` and others) that reflect eBuy's own form state. ### `addresses` The request's delivery and contact addresses β€” usually one. Commonly used keys: `addressName`, `addressType`, `agencyName`, `addressLine1`, `addressLine2`, `city`, `state`, `zip`, `country`. eBuy includes further keys for its own form handling; treat anything not listed here as eBuy-internal. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `rfq_id` | String | The eBuy request id, e.g. `RFQ1835158`. Primary key and detail-lookup value. | eBuy | | `request_type` | String | `RFQ`, `RFP` or `RFI`. | eBuy | | `title` | String | Request title. | eBuy | | `description` | String | The request's full description. Long-form; in the detail default only. | eBuy | | `schedule` | String | The GSA schedule the request was posted under. | eBuy | | `sin` | String | The Special Item Number the request was posted under. | eBuy | | `status` | String | `Open` or `Cancelled` as supplied β€” **frozen**; see [`status` is frozen](#status-is-frozen). | eBuy | | `buyer_name` | String | The buying officer's name. | eBuy | | `buyer_agency` | String | The buying department's name as eBuy gives it. | eBuy | | `buyer_agency_code` | String | The buying agency's numeric code, where eBuy supplies one. | eBuy | | `buyer_email` | String | The buying officer's email. | eBuy | | `buyer_user_id` | String | The buying officer's eBuy account id β€” a stable buyer identity across requests. | eBuy | | `reference_number` | String | The buying office's own solicitation or reference number. | eBuy | | `award_method` | String | eBuy's award-method value, e.g. `lpta`, `best-value`, `trade-off`, `sole-source`, `undecided`. | eBuy | | `contract_type` | String | eBuy's contract-type value, e.g. `firm-fixed-price`, `time-materials`, `labor-hour`, `undecided`. Can hold more than one value, comma-joined. | eBuy | | `commercial_type` | String | eBuy's commercial-item indicator. | eBuy | | `follow_on` | Boolean | Whether the request is for follow-on work. | eBuy | | `source_sought` | Boolean | Whether the request is a sources-sought notice. | eBuy | | `issue_date` | Datetime | When the request was issued. | eBuy | | `close_date` | Datetime | The buyer's response deadline. | eBuy | | `cancel_date` | Datetime | When the request was cancelled, if it was. | eBuy | | `last_mod_date` | Datetime | When the request was last modified in eBuy. | eBuy | | `pop_start_date` | Datetime | Period of performance start, where given. | eBuy | | `pop_end_date` | Datetime | Period of performance end, where given. | eBuy | | `oco_name` | String | Ordering contracting officer's name. | eBuy | | `oco_title` | String | Ordering contracting officer's title. | eBuy | | `oco_agency` | String | Ordering contracting officer's agency. | eBuy | | `oco_phone` | String | Ordering contracting officer's phone. | eBuy | | `oco_aac` | String | Ordering contracting officer's activity address code. | eBuy | | `ocs_name` | String | Contract specialist's name. | eBuy | | `ocs_title` | String | Contract specialist's title. | eBuy | | `ocs_agency` | String | Contract specialist's agency. | eBuy | | `ocs_phone` | String | Contract specialist's phone. | eBuy | | `ocs_aac` | String | Contract specialist's activity address code. | eBuy | | `amendment_count` | Integer | Number of amendments. | eBuy | | `mod_version` | Integer | Amendment version as eBuy's request list reports it. | eBuy | | `qa_document_count` | Integer | Number of question-and-answer documents. | eBuy | | `attachment_count` | Integer | Documents ever observed on the request β€” see [Attachments](#attachments). | eBuy / Tango | | `link_count` | Integer | Links ever observed on the request. | eBuy / Tango | | `amendments` | Array of Object | See [`amendments`](#amendments). | eBuy | | `line_items` | Array of Object | See [`line_items`](#line_items). | eBuy | | `addresses` | Array of Object | See [`addresses`](#addresses). | eBuy | | `detail_fetched` | Boolean | Whether the request's detail page was captured β€” see [Detail and list captures](#detail-and-list-captures). | Tango | | `first_seen` | Datetime | When Tango first observed the request. | Tango | | `last_seen` | Datetime | When Tango last observed the request. The staleness signal. | Tango | | `organization` | Object | Expansion: the buying office resolved to the canonical 7-key office payload; `null` when the buyer is not a federal agency Tango can resolve. | Tango | | `attachments` | Array of Object | Expansion: see [Attachments](#attachments). | eBuy | ## Default shapes - **List** returns: `rfq_id`, `request_type`, `title`, `schedule`, `sin`, `status`, `buyer_name`, `buyer_agency`, `buyer_agency_code`, `reference_number`, `issue_date`, `close_date`, `attachment_count`, `link_count`, `last_seen`. - **Detail** returns every field, plus `organization(*)` and `attachments(*)`. ## Usage Notes - **Judge currency by `last_seen`, not `status`.** `status` never moves to closed. - **No response names the contract a request was posted under.** Use `?contract_number=` to narrow to one of your own contracts. - **Download documents through the API.** The download endpoint returns a short-lived URL; `doc_path` on a document is eBuy's internal path, not a download link. - **Alerts stay inside your contracts.** `ebuy_request` is an alertable query type, scoped to the contracts linked to the account that owns the webhook endpoint. See [Webhooks](../webhooks/index.md). ## Data Sources - **eBuy** β€” the requests, their attachments and structured fields, as GSA eBuy presents them to a Schedule holder. - **Tango** β€” `first_seen`, `last_seen`, `detail_fetched`, the attachment counts across observations, the resolved `organization`, and the extracted attachment text behind [search](../api-reference/ebuy.md#search). --- --- description: "Field definitions for /api/entities/, Tango's vendor and recipient endpoint." updated: 2026-10-27 --- # Entities Data Dictionary This document describes the fields available in the Entities API endpoints (`/api/entities/`). For filtering, ordering, and pagination, see the [Entities API Reference](../api-reference/entities.md). ## Overview Entities represent vendors and recipients in federal contracting and assistance. The canonical identifier is **UEI** (Unique Entity ID). Data is sourced from SAM.gov, with supplemental data from DSBS and Tango-calculated obligation metrics. Financial-assistance recipients without a SAM.gov registration aren't entities. Their entity-shaped recipient record is defined under `recipient` in each financial-assistance data dictionary, e.g. [Grant awards](assistance-grants.md#recipient). ## Identifiers - `uei` (canonical): Public identifier for entities and the API lookup key: `GET /api/entities/{uei}/`. - `uuid` (internal): Tango's internal UUID primary key for the entity record. This is not intended as a public lookup key; other tables typically reference entities by `uei`. **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](../guides/patterns/response-shaping.md) for details. ## Update Frequency Entity data is updated from SAM.gov on a regular sync cadence (typically within 20–60 minutes of SAM changes). Federal obligation rollups are derived from award data. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uei` | String | Unique Entity Identifier. Canonical identifier for the entity; use for API lookups and cross-referencing. | SAM.gov | | `uuid` | UUID | Internal primary key. Not intended as a public lookup key. | Tango | | `display_name` | String | Display name for the entity (e.g., legal name or DBA when useful). | Tango (derived) | | `legal_business_name` | String | Official legal business name as registered in SAM. | SAM.gov | | `dba_name` | String | "Doing business as" name, when different from legal name. | SAM.gov | | `description` | String | Entity description, when available (e.g., from DSBS). | DSBS | | `cage_code` | String | Commercial and Government Entity (CAGE) code. 5-character code used in defense and federal contracting. | SAM.gov | | `dodaac` | String | Department of Defense Activity Address Code. | SAM.gov | | `registered` | String | Whether the entity is registered in SAM (e.g., "Y"/"N"). | SAM.gov | | `registration_status` | String | Current SAM registration status (e.g., "Active"). | SAM.gov | | `purpose_of_registration_code` | String | Code indicating the primary purpose of SAM registration. | SAM.gov | | `purpose_of_registration_desc` | String | Description of the purpose of registration. | SAM.gov | | `sam_registration_date` | Date | Date the entity was registered in SAM. | SAM.gov | | `sam_expiration_date` | Date | Date the entity's SAM registration expires. | SAM.gov | | `sam_activation_date` | Date | Date the entity's SAM registration was activated. | SAM.gov | | `last_update_date` | Date | Date the entity record was last updated. | SAM.gov | | `email_address` | String | Primary email address on file. | SAM.gov | | `entity_url` | String | Entity website or profile URL, when available. | SAM.gov / DSBS | | `physical_address` | Object | Physical address. Expand with `physical_address(*)` for normalized subfields: `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `country_name`, `county`, `county_code`, `fips_code`. Keys are always snake_case regardless of data source. | SAM.gov / DSBS | | `mailing_address` | Object | Mailing address. Same normalized subfields as `physical_address`. | SAM.gov | | `congressional_district` | String | Congressional district (e.g., for physical location). | SAM.gov | | `primary_naics` | String | Primary NAICS code (6-digit). | SAM.gov | | `naics_codes` | Array of Objects | NAICS codes. Expand with `naics_codes(*)` β†’ `[{code, sba_small_business}]`. Plain string arrays from legacy data are auto-normalized. | SAM.gov | | `psc_codes` | Array of Strings | Product/Service Codes associated with the entity. | SAM.gov | | `business_types` | Array of Objects | Business type classifications. Expand with `business_types(*)` β†’ `[{code, description}]`. Dict-format data from DSBS is auto-normalized. | SAM.gov / DSBS | | `sba_business_types` | Array of Objects | SBA certifications. Expand with `sba_business_types(*)` β†’ `[{code, description, entry_date, exit_date}]`. | DSBS / SAM.gov | | `keywords` | String | Keywords or capability text, when available. | DSBS | | `capabilities` | String | Capability narrative, when available. | DSBS | | `current_principals` | String | Current principals/officers on file, when available (e.g., "Jane Smith - CEO; John Doe - VP"). | DSBS | | `naics_small_codes` | Array of Strings | NAICS codes for which the entity qualifies as a small business (e.g., `["541511", "541512"]`). | DSBS | | `special_equip_material` | String | Special equipment or materials the entity possesses, when available. | DSBS | | `capabilities_link` | String | URL to a capabilities statement document, when available. | DSBS | | `non_fed_govt_certifications` | String | Non-federal government certifications, when available (e.g., "AS9100C; FAA/EASA"). | DSBS | | `additional_website` | String | Secondary business website URL, when available. | DSBS | | `county` | String | County name for the entity's physical location, when available. | DSBS | | `federal_obligations` | Object (expand-only) | Federal contract obligations. Use `federal_obligations(*)` β†’ `{total, active}` or `federal_obligations(total)`. Each sub-object contains `awards_obligated`, `awards_count`, `idv_count`, and (for total) `subawards_obligated`, `subawards_count`. | Tango (derived) | | `highest_owner` | Object | Highest-level corporate owner. Expand with `highest_owner(*)` β†’ `{cage_code, legal_business_name, uei}`. | SAM.gov | | `immediate_owner` | Object | Immediate parent entity. Expand with `immediate_owner(*)` β†’ `{cage_code, legal_business_name, uei}`. | SAM.gov | | `relationships` | Array | Related entities β€” corporate ownership, corporate succession, and reported prime/subcontractor ties. Expand with `relationships(*)` β†’ `[{relation, type, source, uei, display_name}]`. Match on `type`; see [relationships](#relationships). | SAM.gov / Tango | | `evs_source` | String | Entity validation source (e.g., "E&Y"). | SAM.gov | | `uei_status` | String | UEI status (e.g., "Active"). | SAM.gov | | `uei_expiration_date` | Date | UEI expiration date, if applicable. | SAM.gov | | `uei_creation_date` | Date | UEI creation date, if applicable. | SAM.gov | | `public_display_flag` | String | Whether the entity record is publicly visible ("Y"/"N"). | SAM.gov | | `exclusion_status_flag` | String | Whether the entity has an active exclusion ("Y"/"N"). | SAM.gov | | `exclusion_url` | String | URL for exclusion details, if applicable. | SAM.gov | | `entity_division_name` | String | Entity division name. | SAM.gov | | `entity_division_number` | String | Entity division number. | SAM.gov | | `entity_start_date` | String | Date the entity was started/established. | SAM.gov | | `fiscal_year_end_close_date` | String | Fiscal year end close date (e.g., "12/31"). | SAM.gov | | `submission_date` | Date | Registration submission date. | SAM.gov | | `entity_structure` | Object (expand) | Entity structure. Expand with `entity_structure(*)` β†’ `{code, description}`. Description falls back to `ENTITY_STRUCTURE_MAP` when missing on the model. | SAM.gov | | `entity_type` | Object (expand) | Entity type. Expand with `entity_type(*)` β†’ `{code, description}`. | SAM.gov | | `profit_structure` | Object (expand) | Profit structure. Expand with `profit_structure(*)` β†’ `{code, description}`. | SAM.gov | | `organization_structure` | Object (expand) | Organization structure. Expand with `organization_structure(*)` β†’ `{code, description}`. | SAM.gov | | `state_of_incorporation` | Object (expand) | State of incorporation. Expand with `state_of_incorporation(*)` β†’ `{code, description}`. | SAM.gov | | `country_of_incorporation` | Object (expand) | Country of incorporation. Expand with `country_of_incorporation(*)` β†’ `{code, description}`. | SAM.gov | | `purpose_of_registration` | Object (expand) | Purpose of registration. Expand with `purpose_of_registration(*)` β†’ `{code, description}`. Description falls back to `PURPOSE_OF_REGISTRATION_MAP` when missing. | SAM.gov | ## Common code values ### `purpose_of_registration_code` (SAM.gov) SAM.gov registration-purpose codes: | Code | Meaning | | --- | --- | | `Z1` | Federal Assistance Awards | | `Z2` | All Awards | | `Z3` | IGT-Only | | `Z4` | Federal Assistance Awards & IGT | | `Z5` | All Awards & IGT | ### `sba_business_types` (DSBS / SAM.gov) These are SBA program classifications you'll commonly see (non-exhaustive). From `SBA_BUSINESS_TYPE_MAP`: | Code | Meaning | | --- | --- | | `A0` | SBA-Certified Economically Disadvantaged Women-Owned Small Business | | `A4` | SBA Certified Small Disadvantaged Business | | `A6` | SBA Certified 8A Program Participant | | `A9` | SBA Certified Woman Owned Small Business | | `JT` | SBA Certified 8A Joint Venture | | `XX` | SBA Certified Hub Zone Firm | ### `business_types` (SAM.gov) Entities store business types as **2-character codes** (e.g., `A6`, `2R`, `QF`). The canonical list (including `certifier`) is exposed at `/api/business_types/` (see [Business Types Data Dictionary](business-types.md)). ## Expansions (via `shape`) ### `physical_address` / `mailing_address` Returns the address as an object with normalized snake_case keys: - `address_line1`, `address_line2`, `city`, `state_or_province_code`, `zip_code`, `zip_code_plus4`, `country_code`, `country_name`, `county`, `county_code`, `fips_code` Address data from different sources (SAM uses snake_case, DSBS uses camelCase) is automatically normalized to the canonical snake_case format above. The `county`, `county_code`, and `fips_code` subfields are available when provided by DSBS. ### `business_types` Returns a normalized array of `{code, description}` objects. Raw data may be stored as: - `[{code, description}]` (SAM format β€” passed through) - `{"2X": true, "F": true}` (DSBS format β€” normalized with description lookups) ### `sba_business_types` Returns a normalized array of `{code, description, entry_date, exit_date}` objects. Same normalization as `business_types`. ### `naics_codes` Returns a normalized array of `{code, sba_small_business}` objects. Plain string arrays (e.g., `["541512", "541511"]`) are normalized to `[{code: "541512", sba_small_business: null}, ...]`. ### `federal_obligations` Expand-only field (not available as a leaf). Returns obligation rollups with child fields `total` and `active`. ```bash # Both total and active /api/entities/{uei}/?shape=uei,federal_obligations(*) # Only total obligations /api/entities/{uei}/?shape=uei,federal_obligations(total) ``` Each sub-object structure: - `total`: `{awards_obligated, awards_count, subawards_obligated, subawards_count, idv_count}` - `active`: `{awards_obligated, awards_count, idv_count}` ### `highest_owner` / `immediate_owner` Returns the corporate owner as `{cage_code, legal_business_name, uei}`. Supports child field selection. ### `relationships` Returns the list of related entities. Each item can include: - `relation`, `type`, `source`, `uei`, `display_name` `uei` and `display_name` identify the **partner** β€” the company on the other end of the tie, not the entity you requested. #### Match on `type`, not `relation` `type` is the stable machine-readable code. `relation` is a display label describing the partner's role, and its vocabulary can change β€” it did in API 4.20.0, when subcontracting and corporate-succession ties stopped reporting the catch-all `affiliate`. **If you have code matching the string `affiliate`, switch it to `type`.** | `type` | What the tie means | `source` | `relation` when the partner is the *object* | `relation` when the partner is the *subject* | | --- | --- | --- | --- | --- | | `prime_sub` | The two companies appeared together on at least one reported subaward, one as prime and one as sub | `subawards` | `subcontractor` | `prime` | | `parent_subsidiary` | The partner is the entity's immediate corporate parent | `sam` | `parent` | `child` | | `ultimate_parent` | The partner is the top of the entity's ownership chain | `sam` | `ultimate_parent` | `descendant` | | `predecessor` | Corporate succession β€” the partner preceded or succeeded the entity | `sam` | `predecessor` | `successor` | Two notes on reading these: - **`descendant`, not `child`.** An `ultimate_parent` tie is only recorded when the ultimate owner differs from the immediate owner, so the company on the other end is never a direct subsidiary β€” it sits at least one company further down the chain. Use `parent_subsidiary` for immediate ties. - **A `prime_sub` tie is not a partnership.** One subaward creates the edge, and it never expires β€” a single 2016 subaward is indistinguishable from an active arrangement. Subaward reporting is also a reporting-threshold sample, so a *missing* tie means "not reported," never "never worked together." It is not a joint venture; there is no joint-venture relationship type. Entries are de-duplicated after your `shape` selection is applied, so a narrower shape can return fewer entries. A company with several distinct ties to the same partner collapses to one entry under `shape=relationships(uei)` but stays separate under `shape=relationships(*)`. ### Code/description pair expands The following fields are structured `{code, description}` expands. When the model's description is missing or empty, the system falls back to a lookup map (where available). - `entity_structure(code, description)` β€” falls back to `ENTITY_STRUCTURE_MAP` - `entity_type(code, description)` β€” falls back to `BUSINESS_TYPE_MAP` - `profit_structure(code, description)` β€” falls back to `BUSINESS_TYPE_MAP` - `organization_structure(code, description)` β€” falls back to `BUSINESS_TYPE_MAP` - `state_of_incorporation(code, description)` β€” uses model description - `country_of_incorporation(code, description)` β€” falls back to the GENC standard for country names when SAM.gov doesn't provide one - `purpose_of_registration(code, description)` β€” falls back to `PURPOSE_OF_REGISTRATION_MAP` Returns `null` when the code is `null`. ```bash # Get entity structure as structured object /api/entities/{uei}/?shape=uei,entity_structure(*) # Just the code /api/entities/{uei}/?shape=uei,entity_structure(code) ``` ## Data Sources - **SAM.gov** – Registration, UEI, legal name, addresses, NAICS/PSC/business types, dates, status, corporate ownership. - **DSBS** – Capabilities, keywords, SBA business types, current principals, NAICS small codes, special equipment/materials, capabilities link, non-federal certifications, additional website, county/county code/FIPS code (when available). - **Tango** – `display_name`, `federal_obligations` (derived from award data), `relationships`. ## Usage Notes - **Use `uei` for lookups** – All entity endpoints accept UEI; it is case-insensitive. - **Use `shape` for large responses** – Request only the fields you need to reduce payload size. - **Scoped award endpoints** – Use `/api/entities/{uei}/contracts/`, `.../idvs/`, etc., for awards tied to an entity; see [Entities API Reference](../api-reference/entities.md). - **Address key normalization** – Address subfields are always returned in snake_case (`address_line1`, `state_or_province_code`, `zip_code`), regardless of how the data was originally stored. - **Business type normalization** – `business_types(*)` and `sba_business_types(*)` always return `[{code, description, ...}]` arrays, even when the source data uses dict format. --- --- description: "Field definitions for /api/exclusions/, including how currency (is_currently_excluded) is derived at query time." updated: 2026-07-19 --- # Exclusions Data Dictionary This document describes the fields available on the Exclusions API endpoint (`/api/exclusions/`). For filtering, ordering, and pagination, see the [Exclusions API Reference](../api-reference/exclusions.md). ## Overview Exclusions are SAM.gov exclusion records β€” debarments, suspensions, and other exclusions from federal awards. Data is sourced from SAM.gov and normalized in Tango. Whether a record is in force is **derived at query time** from its dates rather than stored: see `is_currently_excluded` below and the [currency rules](../api-reference/exclusions.md#currency-who-is-excluded-today) in the API reference. **Note**: Exclusions have one expandable relation, `organization(*)` β€” the resolved excluding agency, requested by name. The full field set is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Identity The primary key and detail-lookup value is `exclusion_key` β€” a 64-character SHA-256 hex digest computed from the record's normalized identity. It is stable across refreshes for the same underlying exclusion. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `exclusion_key` | String | Primary key; 64-char SHA-256 hex digest over the record's identity. | Tango | | `classification_type` | String | Classification (e.g. `Firm`, `Individual`, `Special Entity Designation`). | SAM.gov | | `exclusion_type` | String | Type of exclusion (e.g. `Ineligible (Proceedings Pending)`, `Prohibition/Restriction`). | SAM.gov | | `exclusion_program` | String | Exclusion program (e.g. `Reciprocal`, `Procurement`, `Non-Procurement`). | SAM.gov | | `excluding_agency_code` | String | Code of the agency that created the exclusion. | SAM.gov | | `excluding_agency_name` | String | Name of the excluding agency. | SAM.gov | | `organization_id` | UUID | Tango organization the excluding agency resolves to, at the most specific level SAM's code names (an office code links to that office); `null` when it doesn't resolve. Expand `organization(*)` for the office payload. | Tango | | `uei` | String | SAM.gov Unique Entity Identifier on the exclusion record. | SAM.gov | | `cage_code` | String | CAGE code on the exclusion record. | SAM.gov | | `npi` | String | National Provider Identifier. | SAM.gov | | `dnb_open_data` | String | Dun & Bradstreet open-data indicator. | SAM.gov | | `prefix` | String | Name prefix (individuals). | SAM.gov | | `first_name` | String | First name (individuals). | SAM.gov | | `middle_name` | String | Middle name (individuals). | SAM.gov | | `last_name` | String | Last name (individuals). | SAM.gov | | `suffix` | String | Name suffix (individuals). | SAM.gov | | `entity_name` | String | Legal business name (firms). | SAM.gov | | `display_name` | String | Computed display name β€” `entity_name` for firms, assembled name parts for individuals. | Tango | | `is_currently_excluded` | Boolean | Computed: whether the exclusion is in force today (from `delisted_at`, `activate_date`, `termination_date`). | Tango | | `create_date` | Date | SAM.gov record creation date. | SAM.gov | | `update_date` | Date | SAM.gov last-update date. | SAM.gov | | `activate_date` | Date | Date the exclusion took effect. | SAM.gov | | `termination_date` | Date | Date the exclusion ends; year **2227** is SAM's INDEFINITE sentinel. | SAM.gov | | `termination_type` | String | How the exclusion terminates. | SAM.gov | | `delisted_at` | Date | Date Tango observed the record drop out of the SAM catalog (exclusion lifted); null while still listed. | Tango | | `primary_address` | Object | Primary address (flattened JSON). | SAM.gov | | `secondary_address` | Object | Secondary address (flattened JSON). | SAM.gov | | `more_locations` | Object | Additional locations (JSON). | SAM.gov | | `additional_comments` | String | Free-text comments. | SAM.gov | | `ct_code` | String | Cross-reference / control code. | SAM.gov | | `evs_investigation_status` | String | EVS investigation status. | SAM.gov | | `is_fascsa_order` | Boolean | Whether the record is a FASCSA order. | SAM.gov | | `references` | Object | Related exclusion references (JSON). Maps to the underlying `exclusion_references` payload. | SAM.gov | | `entity_uei` | String | UEI of the resolved Tango entity, when the exclusion links to a registered entity (soft link, not an FK). | Tango | | `vessel_call_sign` | String | Vessel call sign (maritime exclusions). | SAM.gov | | `vessel_type` | String | Vessel type. | SAM.gov | | `vessel_tonnage` | String | Vessel tonnage. | SAM.gov | | `vessel_grt` | String | Vessel gross registered tonnage. | SAM.gov | | `vessel_flag` | String | Vessel flag. | SAM.gov | | `vessel_owner` | String | Vessel owner. | SAM.gov | ## Default shapes - **List** returns: `exclusion_key`, `classification_type`, `exclusion_type`, `excluding_agency_name`, `entity_name`, `display_name`, `activate_date`, `termination_date`, `termination_type`, `is_currently_excluded`. - **Detail** returns every field above, including the sparse vessel block, addresses, and free text. ## Expansions (via `shape`) - `organization(*)` β†’ `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`. In neither default shape; request it explicitly. ## Not exposed Provenance and index-only columns are not part of the API: `record_status`, `row_hash`, `search_vector`. Address `state` / `country` live inside the `primary_address` JSON and are not separately filterable. ## Usage Notes - **Currency is derived** β€” filter with `?active=true` for records in force today; every result also carries `is_currently_excluded`. A record simply reaching its `termination_date` does not change the stored row (and does not fire a webhook alert). - **Lifted exclusions** β€” filter with `?delisted=true`; `delisted_at` carries the date Tango observed the removal. - **Linking to entities** β€” `entity_uei` is a soft scalar link to the entities dataset, set when the exclusion's CAGE/UEI matches a registered entity. There is no `entity(*)` expansion. --- --- description: "Field definitions for /api/federal_register/, Tango's Federal Register documents from 1994 onward, including the structure of the Federal Register's own agency, CFR, docket and RIN fields." updated: 2026-09-25 --- # Federal Register Data Dictionary This document describes the fields available on the Federal Register API endpoint (`/api/federal_register/`). For filtering, ordering, and pagination, see the [Federal Register API Reference](../api-reference/federal-register.md). ## Overview Federal Register documents are every rule, proposed rule, notice and presidential document published in the Federal Register from January 1994 to the present β€” about 1.01 million documents. | Type | Documents | | --- | --- | | `Notice` | ~766,000 | | `Rule` | ~120,000 | | `Proposed Rule` | ~77,000 | | `Uncategorized Document` | ~32,600 | | `Presidential Document` | ~8,600 | | `Correction` | ~4,000 | | `Sunshine Act Document` | ~1,100 | One row is one published document. Most fields are the Federal Register's own, served as it publishes them; Tango adds the `uuid`. **Authentication**: Federal Register endpoints require authentication (API key or OAuth2). **Plans**: every field, including `full_text`, is available on every plan, including Free. **Note**: Federal Register documents are a flat resource with no expandable relations. The full field set is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md). ## Update Frequency The Federal Register is read daily, and a document appears in the API the day it is picked up after publication. The Federal Register often fills in a document's details over the few days after it is published, and those updates flow through as changes to the same row. A document published this week is more likely to change than one published last month. ## Identity A document is identified by its **`document_number` and `publication_date` together**. The document number alone is not unique: the Federal Register reused numbers across genuinely different documents, as late as 2015. The primary key and detail-lookup value is `uuid`. It is derived from the document number and publication date rather than assigned sequentially, so it is stable across rebuilds of the dataset and safe to store alongside your own records. ## Corrections A correction is published as its own document, with its own number and row. The two directions of the link are: - `correction_of` β€” on the correction, identifies the document it corrects. - `corrections` β€” on the original, an array of Federal Register API URLs for the documents that correct it. The rows are never merged, so a search for the subject of a rule can return both the rule and its corrections. ## Structured fields These fields are the Federal Register's own structures, returned as JSON exactly as published. On a few dozen documents they are `null` rather than an empty array or object. ### `agencies` An array of the agencies that issued the document, one object per agency: | Key | Type | Description | | --- | --- | --- | | `raw_name` | String | The agency name as printed on the document. Always present. | | `name` | String | The Federal Register's canonical agency name. | | `slug` | String | The Federal Register's agency slug β€” the value `?fr_agency=` matches. | | `id` | Integer | The Federal Register's agency id. | | `parent_id` | Integer or null | The parent agency's `id`; null for a top-level agency. | | `url` | String | The agency's page on federalregister.gov. | | `json_url` | String | The agency's Federal Register API record. | A small share of agency entries (under 2%) carry only `raw_name`: the Federal Register printed a name it did not match to an agency record. `?fr_agency=` cannot reach a document through such an entry. These are Federal Register agency records, not Tango [organizations](organizations.md); there is no link between the two. ```json {"raw_name": "Employee Benefits Security Administration", "name": "Employee Benefits Security Administration", "slug": "employee-benefits-security-administration", "id": 131, "parent_id": 271, "url": "https://www.federalregister.gov/agencies/employee-benefits-security-administration", "json_url": "https://www.federalregister.gov/api/v1/agencies/131"} ``` ### `cfr_references` An array of the Code of Federal Regulations parts the document amends or affects: | Key | Type | Description | | --- | --- | --- | | `title` | Integer | CFR title number. | | `part` | Integer, string, or null | CFR part number. **Mixed type:** usually a JSON number, a string on about a quarter of references, and occasionally null. Compare it as a string. | | `chapter` | String or null | CFR chapter, where given. | | `citation_url` | Null | Present on every reference; not populated. | `?cfr_title=` and `?cfr_part=` match both spellings of `part`, so the filters are unaffected by the mixed type. ```json {"title": 14, "part": "39", "chapter": null, "citation_url": null} ``` ### `dockets` An array of Regulations.gov dockets associated with the document: | Key | Type | Description | | --- | --- | --- | | `id` | String | Docket id, e.g. `FAA-2024-2669`. | | `title` | String | Docket title. | | `agency_name` | String or null | Agency that owns the docket. | | `documents` | Array | Documents in the docket, as Regulations.gov lists them. | | `supporting_documents` | Array | Supporting documents in the docket. | | `supporting_documents_count` | Integer | Count of supporting documents. | ### String arrays | Field | Contents | Example | | --- | --- | --- | | `docket_ids` | Every docket, project or amendment identifier printed on the document β€” not only Regulations.gov docket ids. | `["Docket No. FAA-2024-2669", "Amendment 39-22915", "AD 2024-26-01"]` | | `topics` | The Federal Register's subject topics. | `["Air transportation", "Aircraft", "Aviation safety"]` | | `regulation_id_numbers` | Regulation Identifier Numbers (RINs). | `["2120-AA64"]` | | `corrections` | Federal Register API URLs of the documents that correct this one. | `["https://www.federalregister.gov/api/v1/documents/C1-2024-30578"]` | ### `regulation_id_number_info` An object **keyed by RIN**, one entry per RIN in `regulation_id_numbers`. Each value is an object with `title`, `priority_category`, `issue` (the Unified Agenda edition, e.g. `202504`), `html_url` and `xml_url` β€” or `null` when the Federal Register holds no agenda entry for that RIN. ```json {"2120-AA64": {"title": "Airworthiness Directives", "issue": "202504", "html_url": "https://www.federalregister.gov/regulations/2120-AA64/airworthiness-directives", "xml_url": "http://www.reginfo.gov/public/do/eAgendaViewRule?pubId=202504&RIN=2120-AA64&operation=OPERATION_EXPORT_XML"}} ``` ### `regulations_dot_gov_info` A single object describing the document's Regulations.gov record β€” **not** keyed by RIN, despite the similar name. It is `{}` when Regulations.gov has no record for the document. Keys, each present only when Regulations.gov supplies it: `document_id`, `docket_id`, `agency_id`, `title`, `comments_url`, `comments_count`, `supporting_documents`, `supporting_documents_count`, `regulation_id_number`, `regulatory_plan` (an object with `title` and `html_url`), and `checked_regulationsdotgov_at`. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | String (UUID) | Stable primary key and detail-lookup value, derived from `document_number` and `publication_date`. | Tango | | `document_number` | String | Federal Register document number, e.g. `2016-31922`. Not unique on its own β€” see [Identity](#identity). | Federal Register | | `publication_date` | Date | Date the document was published. | Federal Register | | `citation` | String | Federal Register citation, e.g. `91 FR 188`. | Federal Register | | `title` | String | Document title. | Federal Register | | `type` | String | `Notice`, `Rule`, `Proposed Rule`, `Presidential Document`, `Correction`, `Sunshine Act Document` or `Uncategorized Document`. Nearly every `Uncategorized Document` is from 1994. | Federal Register | | `subtype` | String | Populated almost only on presidential documents: `Proclamation`, `Executive Order`, `Memorandum`, `Determination`, `Notice`, `Presidential Order` or `Other`. An empty string on every other document, not null. | Federal Register | | `abstract` | String | The document's summary. Absent on roughly a third of documents. | Federal Register | | `action` | String | The ACTION line, e.g. `Notice.` or `Final rule.` | Federal Register | | `dates` | String | The document's DATES paragraph, as free text β€” not a date. | Federal Register | | `comments_close_on` | Date | When the comment period closes. Null on documents that take no comments. | Federal Register | | `effective_on` | Date | When the document takes effect. Null on most documents, including most notices. | Federal Register | | `signing_date` | Date | Date a presidential document was signed. | Federal Register | | `start_page` | Integer | First page in the printed Federal Register. | Federal Register | | `end_page` | Integer | Last page in the printed Federal Register. | Federal Register | | `page_length` | Integer | Number of printed pages. | Federal Register | | `volume` | Integer | Federal Register volume. | Federal Register | | `significant` | Boolean | Designated significant under Executive Order 12866. Null on about 90% of documents, where no designation was made either way. | Federal Register | | `toc_doc` | String | The document's line in the daily table of contents. | Federal Register | | `toc_subject` | String | The table-of-contents subject heading it appears under. | Federal Register | | `correction_of` | String | On a correction, identifies the document it corrects. | Federal Register | | `corrections` | Array of String | Federal Register API URLs of the documents that correct this one. | Federal Register | | `disposition_notes` | String | Disposition notes on a presidential document. | Federal Register | | `executive_order_notes` | String | Notes on an executive order. | Federal Register | | `executive_order_number` | String | Executive order number, e.g. `14372`. | Federal Register | | `presidential_document_number` | String | Presidential document number. | Federal Register | | `proclamation_number` | String | Proclamation number. | Federal Register | | `not_received_for_publication` | String | Carried through from the Federal Register; rarely if ever populated. | Federal Register | | `comment_url` | String | Where to submit a comment, usually on Regulations.gov. | Federal Register | | `regulations_dot_gov_url` | String | The document's Regulations.gov page. | Federal Register | | `html_url` | String | The document's page on federalregister.gov. | Federal Register | | `body_html_url` | String | The full text as HTML on federalregister.gov. | Federal Register | | `pdf_url` | String | The printed PDF on govinfo.gov. | Federal Register | | `public_inspection_pdf_url` | String | The public inspection PDF, filed before publication. | Federal Register | | `raw_text_url` | String | The full text as plain text on federalregister.gov. | Federal Register | | `agencies` | Array of Object | Issuing agencies β€” see [`agencies`](#agencies). | Federal Register | | `cfr_references` | Array of Object | CFR parts affected β€” see [`cfr_references`](#cfr_references). | Federal Register | | `dockets` | Array of Object | Regulations.gov dockets β€” see [`dockets`](#dockets). | Federal Register | | `docket_ids` | Array of String | Docket and other identifiers printed on the document. | Federal Register | | `topics` | Array of String | Subject topics. | Federal Register | | `regulation_id_numbers` | Array of String | Regulation Identifier Numbers (RINs). | Federal Register | | `regulation_id_number_info` | Object | Unified Agenda details keyed by RIN β€” see [`regulation_id_number_info`](#regulation_id_number_info). | Federal Register | | `regulations_dot_gov_info` | Object | The Regulations.gov record β€” see [`regulations_dot_gov_info`](#regulations_dot_gov_info). | Federal Register | | `full_text` | String | The document's plain-text body. **Detail endpoint only**, and only when named in `shape`. Populated on nearly every document. | Federal Register | ## Default shapes - **List** returns: `uuid`, `document_number`, `publication_date`, `type`, `subtype`, `title`, `abstract`, `action`, `agencies`, `cfr_references`, `citation`, `significant`, `comments_close_on`, `effective_on`, `html_url`, `pdf_url`. - **Detail** returns the list fields plus `dates`, `signing_date`, `start_page`, `end_page`, `volume`, `docket_ids`, `dockets`, `regulation_id_numbers`, `topics`, `correction_of`, `corrections`, `executive_order_number`, `presidential_document_number`, `proclamation_number`, `comment_url`, `regulations_dot_gov_url`, `raw_text_url`, `body_html_url`. `page_length`, `toc_doc`, `toc_subject`, `disposition_notes`, `executive_order_notes`, `not_received_for_publication`, `public_inspection_pdf_url`, `regulation_id_number_info` and `regulations_dot_gov_info` are in neither default; name them in `?shape=` to get them. `full_text` can be named on the detail endpoint only. ## Usage Notes - **Read `publication_date` alongside `document_number`.** Before 2016 a document number can belong to more than one document. - **Agencies are the Federal Register's, not Tango's.** Match them with `?fr_agency=` and the Federal Register slug; they do not join to Tango organizations, entities or awards. - **`significant` is three-valued.** `true`, `false`, and null for the large majority of documents that were never designated either way. - **Alerts follow the record.** `federal_register` is an alertable query type; a document appearing or changing fires, but a comment period closing does not. See [Webhooks](../webhooks/index.md). ## Data Sources - **Federal Register** β€” every field except `uuid`, as published on federalregister.gov, from January 1994 forward. - **Tango** β€” `uuid`. --- --- description: "Field definitions for /api/forecasts/, including the list of agency sources Tango ingests forecasts from." updated: 2026-08-02 --- # Forecasts Data Dictionary This document describes the fields available in the Forecasts API endpoints (`/api/forecasts/`). For filtering, ordering, and pagination, see the [Forecasts API Reference](../api-reference/forecasts.md). ## Overview Forecasts are upcoming procurement opportunities from agency feeds (e.g., HHS, DHS). They represent anticipated contract actions before they appear as SAM.gov opportunities. Data is normalized from multiple source systems. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Forecasts we track Tango ingests procurement forecasts from the following agency sources. Filter by `agency` or `source_system` in the API (e.g. `?agency=HHS`). - COMMERCE - DHS - DOE - DOI - DOL - DOT - ED - GSA - HHS - NRC - NSF - TREASURY - USDA - VA ## Update Frequency Forecast data is refreshed according to each agency feed’s cadence (varies by source). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `id` | Integer | Primary key for the forecast in Tango. | Tango | | `source_system` | String | Agency or system that provided the forecast (e.g., "HHS", "DHS"). | Tango | | `external_id` | String | Identifier from the source system. | Agency feed | | `agency` | String | Agency acronym or name. | Agency feed | | `title` | String | Forecast title. | Agency feed | | `description` | String | Forecast description. | Agency feed | | `anticipated_award_date` | Date | Expected award date. | Agency feed | | `fiscal_year` | Integer | Federal fiscal year. | Agency feed / Tango | | `naics_code` | String | NAICS code. | Agency feed | | `is_active` | Boolean | Whether the forecast is active. | Tango | | `status` | String | Status (e.g., active, cancelled). | Agency feed | | `created` | DateTime | When the record was created in Tango. | Tango | | `modified` | DateTime | When the record was last updated. | Tango | | `primary_contact` | Object | Primary contact for the forecast (display-derived). | Agency feed | | `place_of_performance` | String | Place of performance (display-derived). | Agency feed | | `estimated_period` | String | Estimated period of performance (display-derived). | Agency feed | | `set_aside` | String | Set-aside designation (display-derived). | Agency feed | | `contract_vehicle` | String | Contract vehicle type (display-derived). | Agency feed | | `raw_data` | Object | Raw JSON from the source (expand for full payload). | Agency feed | ## Expansions (via `shape`) - `display` – Normalized display fields: `title`, `description`, `agency`, `anticipated_award_date`, `fiscal_year`, `naics_code`, `status`, `primary_contact`, `place_of_performance`, `estimated_period`, `set_aside`, `contract_vehicle`. These are presentation-formatted, so they substitute placeholder text where the top-level field is `null` β€” `description` renders as `"No description available"` and `status` as `"Unknown"`. Test for absence against the top-level fields, not the `display` expand. - `raw_data` – Raw source payload (wildcard fields) ## Data Sources - **Agency feeds** – See [Forecasts we track](#forecasts-we-track) for the full list of source systems (HHS, DHS, GSA, COMMERCE, DOE, ED, TREASURY, DOI, DOL, DOT, USDA, VA, NRC, NSF). - **Tango** – `id`, `source_system`, `is_active`, `created`, `modified`, normalized fields. ## Usage Notes - **Default shaping** – Forecasts now default to the shaping pipeline. All responses render through shaping even without `?shape=`. The list shape includes core identity fields; the detail shape adds `raw_data` and `display(*)`. - **Only active forecasts** are returned by default; filter by `agency`, `fiscal_year`, `naics_starts_with`, or `search` as needed; see [Forecasts API Reference](../api-reference/forecasts.md). - **Fields vary by agency.** Each source publishes its own forecast format, so a field present for one agency may be `null` for another. Two differences worth knowing: - **`description` is always `null` for `ED`.** The Department of Education publishes its forecast as a spreadsheet with no free-text requirement column, so `search` matches Education records on `title` alone. (The `display` expand still renders the `"No description available"` placeholder β€” see [Expansions](#expansions-via-shape).) - **`anticipated_award_date` is quarter-granularity for `ED`.** Education targets a **federal fiscal quarter** rather than a date, and Tango stores the first day of that quarter β€” a target of FY2026 Q1 comes back as `2025-10-01`, not a January date. --- --- description: "Field definitions for /api/grants/, Tango's Grants.gov opportunity endpoint." updated: 2026-05-13 --- # Grants Data Dictionary This document describes the fields available in the Grants API endpoints (`/api/grants/`). For filtering, ordering, and pagination, see the [Grants API Reference](../api-reference/grants.md). ## Overview Grants are grant opportunities from Grants.gov. Each record is a funding opportunity with `grant_id` as the primary identifier. Data is sourced from Grants.gov. For grant **awards** (money already obligated to recipients), see the [Grant awards Data Dictionary](assistance-grants.md). **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency Grant opportunity data is refreshed from Grants.gov on a regular sync cadence. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `grant_id` | String | Unique identifier for the grant opportunity (Grants.gov). | Grants.gov | | `opportunity_number` | String | Opportunity number. | Grants.gov | | `agency_code` | String | Funding agency code. | Grants.gov | | `status` | Object | Opportunity status. Use expansion for `code`, `description`. | Grants.gov | | `title` | String | Grant title. | Grants.gov | | `description` | String | Grant description. | Grants.gov | | `last_updated` | DateTime | Last updated timestamp. | Grants.gov | | `applicant_eligibility_description` | String | Who may apply. | Grants.gov | | `funding_activity_category_description` | String | Funding activity category. | Grants.gov | | `grantor_contact` | Object | Grantor contact info (expand for subfields). | Grants.gov | | `forecast` | Object | Forecast data associated with the grant, if any. | Grants.gov | | `synopsis` | Object | Synopsis data for the grant opportunity. | Grants.gov | | `opportunity_history` | Array | History of changes to the opportunity. | Grants.gov | ## Common code values These are the most important β€œcode β†’ meaning” mappings used in grants data. ### `status` | Code | Meaning | | --- | --- | | `P` | Posted | | `F` | Forecasted | ### `category` | Code | Meaning | | --- | --- | | `A` | Mandatory | | `B` | Continuation | | `C` | Earmark | | `D` | Discretionary | | `E` | Discretionary Cooperative Agreement | | `O` | Other | ### `funding_instruments` (examples) | Code | Meaning | | --- | --- | | `G` | Grant | | `CA` | Cooperative Agreement | | `PC` | Procurement Contract | | `L` | Loan Guarantee | | `D` | Direct Payment | | `O` | Other | `applicant_types` and `funding_categories` are also coded lists (Grants.gov standard taxonomies); the canonical enumerations are large and are best treated as reference data rather than memorized. ## Expansions (via `shape`) - `cfda_numbers` – List of CFDA numbers: `number`, `title` - `applicant_types` – `code`, `description` - `category` – `code`, `description` - `funding_categories` – `code`, `description` - `funding_instruments` – `code`, `description` - `important_dates` – `posted_date`, `response_date`, `response_date_description`, `estimated_synopsis_post_date`, `estimated_application_response_date`, `estimated_application_response_date_description`, `estimated_project_start_date` (fields vary by opportunity status) - `funding_details` – `award_ceiling`, `award_floor`, `estimated_total_funding`, `expected_number_of_awards` - `grantor_contact` – `name`, `phone`, `email` - `additional_info` – `link`, `description` - `attachments` – `mime_type`, `name`, `posted_date`, `resource_id`, `type`, `url` ## Data Sources - **Grants.gov** – Grant opportunities, CFDA linkage, contacts, attachments. ## Usage Notes - **Default shaping** – Grants now default to the shaping pipeline. All responses render through shaping even without `?shape=`. The list shape includes core fields; the detail shape adds all expanded objects. - **Use `grant_id` for lookups.** Filter by `agency`, `status`, or other params; see [Grants API Reference](../api-reference/grants.md). --- --- description: "Field definitions for /api/gsa_elibrary_contracts/, the persisted GSA eLibrary MAS contract endpoint." updated: 2026-04-13 --- # GSA eLibrary Contracts Data Dictionary This document describes the fields available in the GSA eLibrary Contracts API endpoints (`/api/gsa_elibrary_contracts/`). For filtering, ordering, and pagination, see the [GSA eLibrary Contracts API Reference](../api-reference/gsa-elibrary-contracts.md). ## Overview GSA eLibrary contracts are persisted contract records from the GSA eLibrary system, representing contracts awarded under the MAS (Multiple Award Schedule) program. Tango syncs this data to provide a queryable view of MAS schedule contracts with links to IDVs and recipients. ## Update Frequency GSA eLibrary data is updated periodically via the sync pipeline. ## Fields ### Core identity | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | UUID | Tango internal identifier for this persisted record. | Tango | | `schedule` | String | Schedule identifier, typically `MAS`. | GSA eLibrary | | `contract_number` | String | MAS contract number (join key to IDV `piid`, best-effort). | GSA eLibrary | ### Party | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `recipient` | Object \| null | Best-effort cached entity lookup by `uei` (fields: `uei`, `display_name`). | GSA eLibrary / Tango | ### Linked IDV (best-effort) | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `idv` | Object \| null | Only present when the row is linked to an IDV (fields: `key`, `award_date`). | Tango | ### Enrichment | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `sins` | List[String] | Special Item Numbers (SINs). | GSA eLibrary | | `cooperative_purchasing` | Boolean | Cooperative Purchasing program flag (best-effort). | GSA eLibrary | | `disaster_recovery_purchasing` | Boolean | Disaster Recovery Purchasing program flag (best-effort). | GSA eLibrary | | `file_urls` | List[String] | Public document URLs (T&Cs, price list, catalog), best-effort merged. | GSA eLibrary | ## Usage Notes - **Use `uuid` for API lookups.** The `uuid` is the primary key for detail requests: `GET /api/gsa_elibrary_contracts/{uuid}/`. - **These are GSA MAS schedule contracts.** Each record represents a contract awarded under the Multiple Award Schedule program. - **IDV and recipient links are best-effort.** The `idv` expansion is populated when Tango can match the `contract_number` to an IDV PIID. The `recipient` expansion is populated via UEI lookup. - **SINs connect to the MAS SINs reference table.** Use `sin` filtering to find contracts by Special Item Number; see [MAS SINs Data Dictionary](mas-sins.md). ## Data Sources - **GSA eLibrary** β€” Contract metadata from the GSA eLibrary system. --- --- description: "Field definitions for /api/idvs/, Tango's indefinite delivery vehicle award endpoint." updated: 2026-10-16 --- # IDVs Data Dictionary This document describes the fields available in the IDVs API endpoints (`/api/idvs/`). For filtering, ordering, and pagination, see the [IDVs API Reference](../api-reference/idvs.md). ## Overview IDVs (Indefinite Delivery Vehicles) are contract vehicles that can have multiple orders/task orders issued against them. IDVs 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/idvs/{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. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency IDV data is refreshed by the Tango ingest 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. | FPDS / USAspending | | `vehicle_uuid` | UUID | UUID of the Tango Vehicle this IDV is grouped under. Use to fetch vehicle detail at `GET /api/vehicles/{uuid}/`. `null` when not linked to a Vehicle. | Tango | | `award_date` | Date | Date the IDV was awarded. | FPDS / USAspending | | `naics_code` | Integer | NAICS code on the award. | FPDS / USAspending | | `psc_code` | String | Product/Service Code on the award. | FPDS / USAspending | | `total_contract_value` | Decimal | Total value (base + options). | FPDS / USAspending | | `base_and_exercised_options_value` | Decimal | Base plus exercised options. | FPDS / USAspending | | `fiscal_year` | Integer | Federal fiscal year of the award. | FPDS / USAspending | | `obligated` | Decimal | Total obligated amount. | FPDS / USAspending | | `description` | String | Contract description/title. | FPDS / USAspending | | `idv_type` | Object | IDV type (e.g., GWAC, IDIQ). Use expansion for `code`, `description`. | FPDS / USAspending | | `multiple_or_single_award_idv` | Object | Multiple or single award indicator. | FPDS / USAspending | | `type_of_idc` | Object | Type of IDC (Indefinite Delivery Contract). Use expansion for `code`, `description`. | FPDS / USAspending | | `set_aside` | Object | Set-aside type. Use expansion for `code`, `description`. | FPDS / USAspending | | `transactions` | Array | Modification/transaction records. Use expansion for `modification_number`, `transaction_date`, `obligated`, `description`, `action_type`. | FPDS / USAspending | | `subawards_summary` | Object | Summary of subawards. Use expansion for `count`, `total_amount`. | USAspending / Tango | ## Expansions (via `shape`) Same pattern as [Contracts](contracts.md): `recipient`, `place_of_performance`, `awarding_office`, `funding_office`, `parent_award`, `period_of_performance` (fields: `start_date`, `last_date_to_order`), `set_aside`, `transactions`, `competition`, `legislative_mandates`, `officers`, `naics`, `psc`, `subawards_summary`, plus: **Note**: The default (non-shaped) response includes `parent_award` as a minimal `{key, piid}` reference without a database query. Use `?shape=` with `parent_award(...)` for the full parent award object. See [Contracts](contracts.md#parent_award) for details. - `gsa_elibrary(schedule,contract_number,uei,sins,cooperative_purchasing,disaster_recovery_purchasing,file_urls,extracted_text,external_id,source_data)` – best-effort enrichment row from GSA eLibrary; returns `null` when no match is present. ## Common code values These fields use standardized code systems sourced from FPDS / USAspending and surfaced as `{code, description}` objects in responses. ### `idv_type` | Code | Meaning | | --- | --- | | `A` | GWAC | | `B` | IDC | | `C` | FSS | | `D` | BOA | | `E` | BPA | ### `type_of_idc` | Code | Meaning | | --- | --- | | `A` | Indefinite Delivery / Requirements | | `B` | Indefinite Delivery / Indefinite Quantity | | `C` | Indefinite Delivery / Definite Quantity | ### `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](../api-reference/set-aside.md) for the complete mapping.) ### `commercial_item_acquisition_procedures` | Code | Meaning | | --- | --- | | `A` | Commercial Products/Services | | `B` | Products or services pursuant to FAR 12.102(f) | | `C` | Services pursuant to FAR 12.102(g) | | `D` | Commercial Products/Services Procedures not used | | `E` | DoD - Section 803 CSO Procedures | Filter on this code with `commercial_item_acquisition_procedures` (see [IDVs API Reference](../api-reference/idvs.md#commercial-item-acquisition-procedures)). ## Data Sources - **FPDS** – IDV actions, PIID, dates, values, types, set-aside, competition, offices. - **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.** Use `piid` for FPDS/solicitation lookups. - **Child awards:** Use `/api/idvs/{key}/awards/` for contracts/orders under this IDV; see [IDVs API Reference](../api-reference/idvs.md). --- --- description: "Index of Tango's Data Dictionary, with field definitions for every resource organized by domain." tags: [schema, reference] updated: 2026-11-03 --- # Data Dictionary Tango's **Data Dictionary** documents the fields you can expect on key resources and what they mean. If you're looking for **how to query/filter/order** endpoints, see the [API Reference](../api-reference/index.md). ## Awards Definitive contracts, indefinite-delivery vehicles, other transactions, subawards, and solicitation-level groupings. - [Contracts](contracts.md) β€” Definitive contract awards (consolidated from FPDS and USAspending inputs). [Response shaping β†’](../guides/patterns/response-shaping.md#contracts-apicontracts) - [IDVs](idvs.md) β€” Indefinite delivery vehicles (GWACs, IDIQs, etc.). [Response shaping β†’](../guides/patterns/response-shaping.md#idvs-apiidvs) - [OTAs](otas.md) β€” Other Transaction Agreements from FPDS. [Response shaping β†’](../guides/patterns/response-shaping.md#otas-apiotas) - [OTIDVs](otidvs.md) β€” Other Transaction IDVs from FPDS. [Response shaping β†’](../guides/patterns/response-shaping.md#otidvs-apiotidvs) - [Subawards](subawards.md) β€” Sub-contracts and sub-grants under prime awards; sourced from USAspending/FSRS. [Response shaping β†’](../guides/patterns/response-shaping.md#subawards-apisubawards) - [Vehicles](vehicles.md) β€” Solicitation-centric grouping of IDVs. [Response shaping β†’](../guides/patterns/response-shaping.md#vehicles-apivehicles) - [GSA eLibrary contracts](gsa-elibrary-contracts.md) β€” Persisted GSA eLibrary contract metadata. ## Financial assistance Grant, loan, direct-payment and other assistance awards from USAspending share one schema: their transactions, per-program listings, officers, place of performance and recipient, plus the GSDM assistance type, record type, action type and basis codes. See the [Financial assistance overview](../api-reference/assistance.md). - [Grant awards](assistance-grants.md) β€” `/api/assistance/grants/`. [API reference β†’](../api-reference/assistance-grants.md) - [Loans](assistance-loans.md) β€” `/api/assistance/loans/`. [API reference β†’](../api-reference/assistance-loans.md) - [Direct payments](assistance-direct-payments.md) β€” `/api/assistance/direct_payments/`. [API reference β†’](../api-reference/assistance-direct-payments.md) - [Other assistance](assistance-other.md) β€” `/api/assistance/other/`. [API reference β†’](../api-reference/assistance-other.md) - [Assistance listings (CFDA)](assistance-listings.md) β€” CFDA program numbers and titles for federal grants/assistance. [Response shaping β†’](../guides/patterns/response-shaping.md#assistance-listings-apiassistance_listings) - [Subgrants](subgrants.md) β€” `/api/assistance/subgrants/`: subawards reported under federal grants and cooperative agreements, keyed by the SAM.gov report UUID. [API reference β†’](../api-reference/subgrants.md) ## Entities - [Entities](entities.md) β€” Vendors and recipients in federal contracting and assistance; UEI is the canonical identifier (from SAM.gov). [Response shaping β†’](../guides/patterns/response-shaping.md#entities-apientities) - [Exclusions](exclusions.md) β€” SAM.gov exclusion records (debarments, suspensions); currency is derived at query time. [API reference β†’](../api-reference/exclusions.md) ## DIBBS - [DIBBS](dibbs.md) β€” DLA Internet Bid Board System: RFQs, solicitations (RFP/IFB), and awards. Awards are line items β€” do not sum `total_contract_price` across rows. [API reference β†’](../api-reference/dibbs.md) ## SBIR/STTR - [SBIR/STTR](sbir.md) β€” SBIR/STTR topics and DoD DSIP solicitation cycles; topics link to the opportunity or grant that funds them. [API reference β†’](../api-reference/sbir.md) ## State & Local β€” **Beta** - [State & Local](sled.md) β€” State, local and education solicitations and forecasts; `status` is Tango-derived, and category scheme tagging is partial. [API reference β†’](../api-reference/sled.md) ## eBuy - [eBuy](ebuy.md) β€” GSA eBuy requests scoped to your own Schedule contracts; `status` is frozen as eBuy supplied it, so read `last_seen`. [API reference β†’](../api-reference/ebuy.md) ## Forecasts - [Forecasts](forecasts.md) β€” Upcoming procurement opportunities from agency feeds (e.g., HHS, DHS) before they appear as SAM.gov solicitations. [Response shaping β†’](../guides/patterns/response-shaping.md#forecasts-apiforecasts) ## Grants - [Grants](grants.md) β€” Grant opportunities from Grants.gov (funding opportunities, not awards; for awards see [Grant awards](assistance-grants.md)). [Response shaping β†’](../guides/patterns/response-shaping.md#grants-apigrants) ## Budget β€” **Beta** - [Budget](budget.md) β€” Federal-account budget data (requested / enacted / apportioned / obligated / outlayed), joined to FPDS contract activity. [API reference β†’](../api-reference/budget.md) Β· [Exploration guide β†’](../guides/how-to/explore-federal-budget.md) ## IT Dashboard - [IT Dashboard](itdashboard.md) β€” Federal IT investment records from itdashboard.gov, keyed by Unique Investment Identifier (UII). [Response shaping β†’](../guides/patterns/response-shaping.md#it-dashboard-apiitdashboard) ## Protests and appeals Two different proceedings, kept in two resources: a bid protest challenges an award or a solicitation, and a contract appeal disputes a contracting officer's final decision under a contract already awarded. - [Protests](protests.md) β€” Bid protest cases from GAO, the U.S. Court of Federal Claims, and SBA OHA, with subordinate dockets. [API reference β†’](../api-reference/protests.md) - [Contract appeals](contract-appeals.md) β€” Contract Disputes Act decisions of the CBCA (2007 onward) and the ASBCA (2010 onward); dockets are an array, and a delisted decision is kept. [API reference β†’](../api-reference/contract-appeals.md) ## Federal Register - [Federal Register](federal-register.md) β€” Federal Register documents since 1994, keyed by document number and publication date together; agencies and CFR references are served as the Federal Register publishes them. [API reference β†’](../api-reference/federal-register.md) ## News - [Award announcements](award-announcements.md) β€” Announcements from the Department of War's daily contracts release and generated by MakeGov from FPDS award data; each row names its source, and many fields are filled by only one. [API reference β†’](../api-reference/award-announcements.md) ## Opportunities SAM.gov contract opportunity and notice data. - [Opportunities](opportunities.md) β€” Contract opportunities aggregated by parent. [Response shaping β†’](../guides/patterns/response-shaping.md#opportunities-apiopportunities) - [Notices](notices.md) β€” Individual SAM.gov notice records (amendments, updates) under an opportunity. [Response shaping β†’](../guides/patterns/response-shaping.md#notices-apinotices) ## Reference data Lookup tables and codes used across awards and entities. - [Business types](business-types.md) β€” SAM.gov business type codes (e.g., small business, 8(a), HUBZone). [Response shaping β†’](../guides/patterns/response-shaping.md#business-types-apibusiness_types) - [MAS SINs](mas-sins.md) β€” MAS Special Item Numbers (SINs) reference data. [Response shaping β†’](../guides/patterns/response-shaping.md#mas-sins-apimas_sins) - [NAICS](naics.md) β€” North American Industry Classification System codes. [Response shaping β†’](../guides/patterns/response-shaping.md#naics-apinaics) - [Organizations](organizations.md) β€” Unified federal hierarchy (departments, agencies, offices in one tree). [Response shaping β†’](../guides/patterns/response-shaping.md#organizations-apiorganizations) - [PSC](psc.md) β€” Product/Service Codes for federal contracting. [Response shaping β†’](../guides/patterns/response-shaping.md#psc-apipsc) ## Shared Data structures shared across multiple endpoints via response shaping expands. - [Set-aside codes](../api-reference/set-aside.md) β€” Set-aside type codes and descriptions. - [Agencies](agencies.md) β€” Agency fields and expansions as they appear in shaped responses. [Response shaping β†’](../guides/patterns/response-shaping.md#agencies-apiagencies) - [Departments](departments.md) β€” Department fields as they appear in shaped responses. [Response shaping β†’](../guides/patterns/response-shaping.md#departments-apidepartments) - [Offices](offices.md) β€” Office fields, flat aliases, and expansions as they appear in shaped responses. [Response shaping β†’](../guides/patterns/response-shaping.md#offices-apioffices) --- --- description: "Field definitions for /api/itdashboard/, Tango's federal IT investment endpoint." updated: 2026-07-20 --- # IT Dashboard Data Dictionary This document describes the fields available in the IT Dashboard API endpoint (`/api/itdashboard/`). For filtering, ordering, and pagination, see the [IT Dashboard API Reference](../api-reference/itdashboard.md). ## Overview IT Dashboard investments are federal IT investments tracked by the Office of Management and Budget (OMB) and published on [itdashboard.gov](https://www.itdashboard.gov/). Each record represents a single investment identified by a Unique Investment Identifier (UII). Data includes investment metadata, fiscal-year funding breakdowns, CIO risk evaluations, contract details, project information, and performance metrics. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. All shape expansions below are available on every plan; only the `business_case_html` leaf field is tier-gated (see [Special fields](#special-fields)). Some *filters* are tier-gated β€” see the [IT Dashboard API Reference](../api-reference/itdashboard.md). ## Update Frequency IT Dashboard data is refreshed daily from itdashboard.gov. The scraper pulls the CSV data feeds and aggregates them with investment-level API data. ## Core fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uii` | String | Unique Investment Identifier (e.g., `021-488119819`). Primary lookup key. | IT Dashboard | | `agency_code` | Integer | Numeric agency code (e.g., 21 for Department of Transportation). | IT Dashboard | | `agency_name` | String | Full agency name. | IT Dashboard | | `bureau_code` | Integer | Numeric bureau code within the agency. | IT Dashboard | | `bureau_name` | String | Bureau name. | IT Dashboard | | `investment_title` | String | Title of the IT investment. | IT Dashboard | | `type_of_investment` | String | Classification (e.g., "Major IT Investment", "Standard IT Infrastructure"). | IT Dashboard | | `part_of_it_portfolio` | String | IT portfolio area (e.g., "Mission Delivery", "Infrastructure"). | IT Dashboard | | `updated_time` | DateTime | Last update timestamp from the source data. | IT Dashboard | | `url` | String | Canonical URL to the investment on itdashboard.gov. Computed from UII. | Derived | ## Funding expansion (`funding`) Fiscal-year internal funding and contribution amounts. | Field | Type | Description | | ----- | ---- | ----------- | | `fy2020_internal_funding` | Number | FY2020 internal funding amount. | | `fy2020_contribution` | Number | FY2020 contribution amount. | | `fy2021_internal_funding` | Number | FY2021 internal funding amount. | | `fy2021_contribution` | Number | FY2021 contribution amount. | | `fy2022_internal_funding` | Number | FY2022 internal funding amount. | | `fy2022_contribution` | Number | FY2022 contribution amount. | | `fy2023_internal_funding` | Number | FY2023 internal funding amount. | | `fy2023_contribution` | Number | FY2023 contribution amount. | | `fy2024_internal_funding` | Number | FY2024 internal funding amount. | | `fy2024_contribution` | Number | FY2024 contribution amount. | | `fy2025_internal_funding` | Number | FY2025 internal funding amount. | | `fy2025_contribution` | Number | FY2025 contribution amount. | ## Details expansion (`details`) Extended investment metadata. | Field | Type | Description | | ----- | ---- | ----------- | | `investment_description` | String | Full text description of the investment. | | `previous_uii` | String | Previous UII if the investment was re-baselined. | | `current_uii` | String | Current UII (may differ from `previous_uii`). | | `change_in_status` | String | Description of any status change. | | `shared_services_category` | String | Shared services classification. | | `shared_services_identifier` | String | Shared services identifier. | | `mission_support_investment_categories` | String | Mission support categories. | | `mission_delivery_and_management_support_area` | String | Mission delivery area. | | `national_security_system_identifier` | String | NSS identifier, if applicable. | | `it_infrastructure_and_management_type` | String | IT infrastructure type. | | `business_case_url` | String | URL to the business case on IT Dashboard. | | `public_urls` | String | Public-facing URLs for the investment. | | `last_updated` | String | Source-reported last-updated date. | ## CIO evaluation expansion (`cio_evaluation`) CIO risk ratings over time. Each entry is a rating snapshot. | Field | Type | Description | | ----- | ---- | ----------- | | `cioRating` | String | Risk rating with label (e.g., "1 - High Risk", "5 - Low Risk"). | | `comment` | String | CIO evaluation comment. | | `ratedDate` | String | Date the rating was assigned. | | `updatedTime` | String | Timestamp of the rating record update. | | `latestIndicator` | String | "Y" if this is the most recent rating. | ### CIO rating scale | Rating | Risk level | | ------ | ---------- | | 1 | High Risk | | 2 | Moderately High Risk | | 3 | Medium Risk | | 4 | Moderately Low Risk | | 5 | Low Risk | ## Contracts expansion (`contracts`) IT contracts associated with the investment. Fields vary by contract. ## Projects expansion (`projects`) Project details under the investment. Fields vary by project. ## Performance metrics expansion (`performance_metrics`) Performance measurement data. | Field | Type | Description | | ----- | ---- | ----------- | | `metricDescription` | String | Description of the performance metric. | | `metTarget` | String | Whether target was met ("MET" or "NOT MET"). | | `latestActualResult` | Number | Most recent actual measurement. | | `target2024PY` | Number | Prior-year target value. | | `target2025CY` | Number | Current-year target value. | | `unitOfMeasure` | String | Unit (e.g., "Percentage"). | | `reportingFrequency` | String | How often the metric is reported. | | `measurementCondition` | String | Target condition (e.g., "Over target"). | | `dateOfLatestActualResult` | String | Date of the latest actual result. | | `performanceMeasurementCategory` | String | Category (e.g., "Strategic and Business Results"). | | `isRetired` | Boolean | Whether the metric has been retired. | ## Other expansions | Expansion | Description | | --------- | ----------- | | `cost_pools_towers(*)` | Cost pool and cost tower breakdowns. | | `funding_sources(*)` | Detailed funding source information. | | `performance_actual(*)` | Historical performance actual results (individual data points over time). | | `operational_analysis(*)` | Operational analysis data. | ## Special fields | Field | Tier | Description | | ----- | ---- | ----------- | | `business_case_html` | Business+ (Medium plan and above) | Full HTML content of the business case page from IT Dashboard. Requested as a leaf field, not an expansion. | --- --- description: "Field definitions for the CALC labor category rate endpoints nested under IDVs and entities." updated: 2026-03-11 --- # CALC Labor Rates Data Dictionary This document describes the fields available in the CALC labor category rate endpoints (`/api/idvs/{key}/lcats/`, `/api/entities/{uei}/lcats/`). For filtering, ordering, and pagination, see the [CALC Labor Rates API Reference](../api-reference/lcats.md). ## Overview CALC (Contract Awarded Labor Category) rates are labor category pricing records sourced from the GSA CALC API. Each record represents a single labor category rate on a GSA MAS (Multiple Award Schedule) contract. The dataset contains approximately 238,000 records. **Primary identifier:** `uuid` (deterministic, derived from the external CALC record ID). ## Update Frequency CALC labor rate data is refreshed daily from the GSA CALC API. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `uuid` | UUID | Deterministic primary key (derived from external CALC ID). | CALC / Tango | | `labor_category` | String | Labor category title. | CALC | | `current_price` | Decimal | Current hourly rate. | CALC | | `education_level` | String | Required education level. | CALC | | `min_years_experience` | Integer | Minimum years of experience required. | CALC | | `experience_range` | String | Experience range description (e.g., "5-7 years"). | CALC | | `security_clearance` | String | Security clearance requirement. | CALC | | `worksite` | String | Work location type. | CALC | | `sin` | String | Special Item Number. | CALC | | `category` | String | Service category. | CALC | | `subcategory` | String | Service subcategory. | CALC | | `schedule` | String | GSA schedule name. | CALC | | `contract_start` | Date | Contract period start date. | CALC | | `contract_end` | Date | Contract period end date. | CALC | ## Expansions (via `shape`) - `idv` -- Linked IDV details: `key`, `piid`, `award_date` - `recipient` -- Entity details via IDV recipient linkage: `uei`, `display_name` - `business_size` -- Business size as structured `code`/`description` (e.g., `{"code": "S", "description": "Small Business"}`) The `idv` and `recipient` expansions require Pro tier access. The `business_size` expansion is available on all tiers. ## Data Sources - **GSA CALC** -- Contract Awarded Labor Category API. Provides labor category pricing data from GSA MAS contracts. ## Usage Notes - **Use `uuid` for unique identification.** The UUID is deterministic and stable across data refreshes for the same CALC record. - **IDV linkage is best-effort.** The `idv` expansion is populated when Tango can match the CALC contract number to an IDV PIID in the awards dataset. - **Recipient is derived from the IDV.** The `recipient` expansion comes from the linked IDV's recipient entity, not directly from CALC data. - **These are nested endpoints.** Access rates via `/api/idvs/{key}/lcats/` or `/api/entities/{uei}/lcats/` -- there is no top-level route. - **Pro tier required.** Both the endpoints and the `idv`/`recipient` expansions require Pro tier access or above. --- --- description: "Field definitions for /api/mas_sins/, the GSA MAS Special Item Number reference endpoint." updated: 2026-05-13 --- # MAS SINs Data Dictionary This document describes the fields available in the MAS SINs API endpoints (`/api/mas_sins/`). For filtering, ordering, and pagination, see the [MAS SINs API Reference](../api-reference/mas-sins.md). ## Overview MAS SINs (Special Item Numbers) are GSA schedule line items used to categorize offerings under the MAS schedule. Tango stores SINs as reference data so other datasets (e.g. GSA eLibrary enrichment) can store only SIN codes and join to this table for details. **Note**: This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. Default shape includes all 15 fields. ## Update Frequency MAS SIN data is refreshed on a regular cadence from the GSA eLibrary MAS Schedule export. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `sin` | String | Special Item Number code. Primary key. | GSA MAS SIN export | | `large_category_code` | String (1 char) | Large category code (e.g., `A`). | GSA MAS SIN export | | `large_category_name` | String | Large category name (e.g., `Office Management`). | GSA MAS SIN export | | `sub_category_code` | String | Subcategory code (e.g., `A01`). | GSA MAS SIN export | | `sub_category_name` | String | Subcategory name (e.g., `Audio Visual Products`). | GSA MAS SIN export | | `psc_code` | String \| null | PSC code from source (4 chars, may be alphanumeric). | GSA MAS SIN export | | `state_local` | Boolean | Whether SIN is eligible for state/local/cooperative purchasing. | GSA MAS SIN export | | `set_aside_code` | String (1 char) \| null | One of `Y`, `N`, `B`. | GSA MAS SIN export | | `service_comm_code` | String (1 char) \| null | One of `B`, `C`, `S`, `P`. | GSA MAS SIN export | | `expiration_date` | Date \| null | Parsed from a 7-digit `YYYYDDD` numeric format when present. | GSA MAS SIN export | | `tdr` | Boolean | TDR flag (`Y/N` in source). | GSA MAS SIN export | | `olm` | Boolean | OLM flag (`Y/N` in source). | GSA MAS SIN export | | `naics_codes` | List[Integer] | NAICS codes associated with the SIN. | GSA MAS SIN export | | `title` | String | SIN title (normalized to remove leading SIN code prefix). | GSA MAS SIN export | | `description` | String \| null | SIN description (normalized to remove leading SIN code prefix). | GSA MAS SIN export | ## Category codes and names The MAS SIN dataset includes a small, stable hierarchy: - **Large category**: `large_category_code` + `large_category_name` - **Subcategory**: `sub_category_code` + `sub_category_name` For convenience, here is the full mapping. ### Large categories | Code | Name | | --- | --- | | `A` | Office Management | | `B` | Facilities | | `C` | Furniture and Furnishings | | `D` | Human Capital | | `E` | Professional Services | | `F` | Information Technology | | `G` | Miscellaneous | | `H` | Scientific Management and Solutions | | `I` | Industrial Products and Services | | `J` | Security and Protection | | `K` | Transportation and Logistics Services | | `L` | Travel | ### Subcategories | Large category code | Subcategory code | Subcategory name | | --- | --- | --- | | `A` | `A01` | Audio Visual Products | | `A` | `A02` | Audio Visual Services | | `A` | `A03` | Document Services | | `A` | `A04` | Mail Management | | `A` | `A05` | Office Management Maintenance and Repair | | `A` | `A06` | Media Products | | `A` | `A07` | Media Services | | `A` | `A08` | Office Services | | `A` | `A09` | Office Supplies | | `A` | `A10` | Printing and Photographic Equipment | | `A` | `A11` | Records Management | | `B` | `B01` | Facilities Maintenance and Repair | | `B` | `B02` | Facilities Services | | `B` | `B03` | Facilities Solutions | | `B` | `B04` | Facilities Supplies | | `B` | `B05` | Food Service Equipment | | `B` | `B06` | Structures | | `C` | `C01` | Flooring | | `C` | `C02` | Furniture Services | | `C` | `C03` | Healthcare Furniture | | `C` | `C04` | Household Dormitory and Quarters Furniture | | `C` | `C05` | Miscellaneous Furniture | | `C` | `C06` | Office Furniture | | `C` | `C07` | Packaged Furniture | | `C` | `C08` | Signs | | `D` | `D01` | Background Investigations | | `D` | `D02` | Compensation and Benefits | | `D` | `D03` | Human Resources | | `D` | `D04` | Social Services | | `E` | `E01` | Business Administrative Services | | `E` | `E02` | Environmental Services | | `E` | `E03` | Financial Services | | `E` | `E04` | Identity Protection Services | | `E` | `E05` | Language Services | | `E` | `E06` | Legal Services | | `E` | `E07` | Logistical Services | | `E` | `E08` | Marketing and Public Relations | | `E` | `E09` | Technical and Engineering Services (non- IT) | | `E` | `E10` | Training | | `F` | `F01` | Electronic Commerce | | `F` | `F02` | IT Hardware | | `F` | `F03` | IT Services | | `F` | `F04` | IT Software | | `F` | `F05` | IT Solutions | | `F` | `F06` | IT Training | | `F` | `F07` | Telecommunications | | `G` | `G01` | Apparel | | `G` | `G02` | Awards | | `G` | `G03` | Flags | | `G` | `G04` | Musical Instruments | | `G` | `G05` | Personal Hair Care Items | | `G` | `G06` | Complementary SINs | | `H` | `H01` | Laboratory Animals | | `H` | `H02` | Laboratory Equipment | | `H` | `H03` | Medical Equipment | | `H` | `H04` | Scientific Services | | `H` | `H05` | Search and Navigation | | `H` | `H06` | Testing and Analysis | | `I` | `I01` | Cleaning Supplies | | `I` | `I02` | Fire/Rescue/Safety/Environmental Protection Equipment | | `I` | `I03` | Fuel Management | | `I` | `I04` | Hardware and Tools | | `I` | `I05` | Industrial Products | | `I` | `I06` | Industrial Products and Services Maintenance and Repair | | `I` | `I07` | Machinery and Components | | `I` | `I08` | Packaging | | `I` | `I09` | Test and Measurement Supplies | | `J` | `J01` | Marine and Harbor | | `J` | `J02` | Protective Equipment | | `J` | `J03` | Security Animals and Related Services | | `J` | `J04` | Security Services | | `J` | `J05` | Security Systems | | `J` | `J06` | Testing Equipment | | `K` | `K01` | Automotive Body Maintenance and Repair | | `K` | `K02` | Motor Vehicles (non-Combat) | | `K` | `K03` | Package Delivery | | `K` | `K04` | Packaging Services | | `K` | `K05` | Transportation of Things | | `L` | `L01` | Employee Relocation | | `L` | `L02` | Lodging | | `L` | `L03` | Travel Agent and Misc. Services | ## Data sources - GSA eLibrary MAS Schedule reference export, normalized by Tango. --- --- description: "Field definitions for /api/naics/, including its SBA size-standard and obligation-rollup expansions." updated: 2026-05-13 --- # NAICS Data Dictionary This document describes the fields available in the NAICS API endpoints (`/api/naics/`). For filtering, ordering, and pagination, see the [NAICS API Reference](../api-reference/naics.md). ## External references - [Official NAICS information (U.S. Census Bureau)](https://www.census.gov/naics/) - [NAICS Association (third-party reference)](https://www.naics.com/) ## Overview NAICS (North American Industry Classification System) codes are industry classification codes used in federal contracting. Each code has a numeric `code` (primary key) and `description`. Detail responses also include SBA size standards and obligation rollups. **Note**: This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. On list requests, the default shape is `code,description`. Detail requests and `?show_limits=1` default to `code,description,size_standards(*),federal_obligations(*)`. The legacy `?show_limits=1` parameter is still accepted but shaping is preferred. ## Update Frequency NAICS reference data is updated when size standards or code lists are refreshed (periodic). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | Integer | NAICS code (primary key). | NAICS / SBA | | `description` | String | NAICS industry description. | NAICS / SBA | | `size_standards` | Expansion | SBA size standards for this NAICS. Expand with `size_standards(employee_limit,revenue_limit)` or `size_standards(*)`. `revenue_limit` is in whole dollars. Included in detail/`show_limits` default shape. | SBA | | `federal_obligations` | Expansion | Obligation rollups for this NAICS. Expand with `federal_obligations(total,active)` or `federal_obligations(*)`. Each sub-object has `awards_obligated` (float) and `awards_count` (int). Included in detail/`show_limits` default shape. | Tango (derived from awards) | **Metrics:** Time-series obligation metrics are available at `/api/naics/{code}/metrics///`; see [Metrics](../api-reference/metrics.md). ## Data Sources - **NAICS / SBA** – Code descriptions and size standards. - **Tango** – `year`, obligation rollups (via metrics endpoint). ## Usage Notes - **NAICS codes are hierarchical** β€” 2-digit sector, 3-digit subsector, up to 6-digit national industry codes. - **Use `search` for text-based lookup; use `code` for exact match.** Filter by `search`, `revenue_limit`, `employee_limit`; see [NAICS API Reference](../api-reference/naics.md). - **Size standards and federal obligations are available as shaping expansions.** Expand with `size_standards(*)` or `federal_obligations(*)`; see [Response Shaping](../guides/patterns/response-shaping.md). - **NAICS codes are updated periodically by the Census Bureau.** Tango reflects the current revision. --- --- description: "Field definitions for /api/notices/, Tango's individual SAM.gov notice endpoint." updated: 2026-10-06 --- # Notices Data Dictionary This document describes the fields available in the Notices API endpoints (`/api/notices/`). For filtering, ordering, and pagination, see the [Notices API Reference](../api-reference/notices.md). ## Overview Notices are individual SAM.gov contract opportunity notices. Each notice has a `notice_id` (UUID). An opportunity can have multiple notices (e.g., amendments); notices are the versioned records. Data is sourced from SAM.gov. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency Notice data is refreshed from SAM.gov on a regular sync cadence (typically 20–60 minutes). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `notice_id` | UUID | Primary identifier for the notice in Tango. | Tango / SAM.gov | | `active` | Boolean | Whether the notice is active (not archived/cancelled/deleted). | Tango (derived) | | `address` | Object | Notice address. Use expansion for `city`, `state`, `zip`, `country`. | SAM.gov | | `attachments` | Array | Attachments. Use expansion for `attachment_id`, `file_size`, `mime_type`, `name`, `posted_date`, `resource_id`, `type`, `url`, plus the Pro+ sub-fields `doc_role`, `doc_role_alt` and `extracted_text` (each returned only when named explicitly). `type` is `file` or `link`; see [Attachments: files and links](opportunities.md#attachments-files-and-links). | SAM.gov | | `attachment_count` | Integer | Number of attachments of every type, links included. | Tango (derived) | | `award_amount` | String | Award amount, as SAM publishes it (a string, not a number). Award notices only. | SAM.gov | | `award_date` | Date | Award date. Award notices only. | SAM.gov | | `award_number` | String | Award number. | SAM.gov | | `awardee` | String | Awardee name. Award notices only. | SAM.gov | | `awardee_uei` | String | Awardee UEI. Award notices only. | SAM.gov | | `description` | String | Notice description. | SAM.gov | | `file_count` | Integer | Number of attachments with `type` `file`: documents attached to the notice. `null` until counted. API version 5.9.0 or later. | Tango (derived) | | `last_updated` | DateTime | Last modified. | SAM.gov | | `link_count` | Integer | Number of attachments with `type` `link`: URLs the notice lists that point somewhere else. `null` until counted. API version 5.9.0 or later. | Tango (derived) | | `meta` | Object | `parent_notice_id`, `related_notice_id`, `notice_type`, `link`. Use expansion for subfields; `notice_type` has `code`, `type`. | Tango | | `naics_code` | String | NAICS code. | SAM.gov | | `office` | Object | Contracting office. Use expansion for office/agency/department fields. | SAM.gov | | `opportunity` | Object | Parent opportunity reference. | Tango | | `opportunity_id` | UUID | The Tango `opportunity_id` of the parent opportunity (when available). | Tango | | `place_of_performance` | Object | Place of performance. Use expansion for `street_address`, `city`, `state`, `zip`, `country`. | SAM.gov | | `posted_date` | DateTime | Posted date. | SAM.gov | | `psc_code` | String | Product/Service Code (classification_code). | SAM.gov | | `response_deadline` | DateTime | Response deadline. | SAM.gov | | `sam_url` | String | Canonical SAM.gov notice URL. | Tango (derived) | | `set_aside` | String | Set-aside description. Use expansion `set_aside(code,description)` for the structured form. | SAM.gov | | `solicitation_number` | String | Solicitation number. | SAM.gov | | `title` | String | Notice title. | SAM.gov | ## Expansions (via `shape`) - `attachments`, `address`, `archive`, `place_of_performance`, `primary_contact` (fields: `title`, `full_name`, `email`, `phone`, `fax`), `secondary_contact`, `meta` (with `notice_type(code, type)`), `office`, `opportunity`, `set_aside(code,description)` ## Notice type codes Notices classify the notice β€œtype” using a short code. These values come from SAM.gov, with Tango normalizing them to the codes below: | Code | Meaning | | --- | --- | | `a` | Award Notice | | `g` | Sale of Surplus Property | | `i` | Consolidate/(Substantially) Bundle | | `j` | Justification and Approval (J&A) | | `k` | Combined Synopsis/Solicitation | | `l` | Fair Opportunity / Limited Sources Justification (deprecated) | | `m` | Modification/Amendment/Cancel | | `o` | Solicitation | | `p` | Pre solicitation | | `r` | Sources Sought | | `s` | Special Notice | | `u` | Justification (J&A) | ## Data Sources - **SAM.gov** – Notice records, offices, contacts, attachments. - **Tango** – `notice_id`, `active`, `attachment_count`, `file_count`, `link_count`, `meta`, `sam_url`, `opportunity`. ## Usage Notes - **A notice can have attachments and no documents.** `attachment_count` includes links; `file_count` greater than 0 is the test for "has documents". Files plus links need not equal the total, and `null` means not yet counted. See [Attachments: files and links](opportunities.md#attachments-files-and-links). - **Use `notice_id` for notice lookups.** For the parent opportunity use `opportunity` or the [Opportunities API Reference](../api-reference/opportunities.md); see [Opportunities Data Dictionary](opportunities.md) and [Notices API Reference](../api-reference/notices.md). --- --- description: "Field definitions for the office object as it appears in response-shaping expansions across other endpoints." updated: 2026-04-13 --- # Offices Data Dictionary This document describes the fields available on the office data structure as it appears in response shaping expands across multiple endpoints (e.g., contracts, opportunities). For filtering, ordering, and pagination on the standalone endpoint, see the [Offices API Reference](../api-reference/offices.md). For the unified federal hierarchy, see [Organizations](organizations.md). ## Overview Offices are sub-agency organizations in the federal hierarchy. When expanded via response shaping (e.g., `awarding_office(office_code,office_name,agency_name)`), office objects use the fields below. The default shape uses flat aliases for backwards compatibility. ## Update Frequency Office data is updated **monthly** via the organization sync process from the Federal Hierarchy (SAM.gov). ## Direct Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | String | Office code. | Federal Hierarchy (SAM.gov) | | `name` | String | Office name. | Federal Hierarchy (SAM.gov) | ## Flat Aliases (Legacy Default Shape) These fields are returned by default when no `?shape=` parameter is provided. They flatten the office, agency, and department into a single level. | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `office_code` | String | For awarding offices, the Activity Address Code (`aac_code`) that matches the first 6 characters of the contract PIID; falls back to `code`. For funding offices, alias for `code`. | Federal Hierarchy | | `office_name` | String | Alias for `name`. | Federal Hierarchy | | `agency_code` | String | Parent agency code (resolved from `agency.code`). | FPDS | | `agency_name` | String | Parent agency name (resolved from `agency.name`). | Federal Hierarchy | | `department_code` | String | Parent department code (resolved from `agency.department.code`). | USAspending | | `department_name` | String | Parent department name (resolved from `agency.department.name`). | Federal Hierarchy | ## Expansions | Expansion | Fields | Description | | --------- | ------ | ----------- | | `agency(...)` | `code`, `name`, `abbreviation` | Parent agency. See [Agencies data dictionary](agencies.md). | | `department(...)` | `code`, `name`, `abbreviation`, `description`, `cgac`, `website`, `congressional_justification` | Parent department. See [Departments data dictionary](departments.md). | ## Usage Notes - **Default shape uses flat aliases.** Without `?shape=`, offices return `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`. - **Use nested expansions for structured data.** Pass `?shape=code,name,agency(code,name)` for nested objects instead of flat aliases. - **Prefer Organizations for new integrations.** The office data structure is a legacy shape. Use the [Organizations API](../api-reference/organizations.md) for the full hierarchy with richer search and obligation data. ## Data Sources - **Federal Hierarchy (SAM.gov)** β€” Authoritative source for office names, codes, and parent relationships. - **FPDS** β€” Office codes as they appear in contract transactions. --- --- description: "Field definitions for /api/opportunities/, Tango's SAM.gov opportunity endpoint." updated: 2026-10-06 --- # Opportunities Data Dictionary This document describes the fields available in the Opportunities API endpoints (`/api/opportunities/`). For filtering, ordering, and pagination, see the [Opportunities API Reference](../api-reference/opportunities.md). ## Overview Opportunities represent SAM.gov contract opportunity notices aggregated by parent opportunity (one opportunity can have multiple notices over time). Each opportunity has an `opportunity_id`. Data is sourced from SAM.gov. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency Opportunity data is refreshed from SAM.gov on a regular sync cadence (typically 20–60 minutes). ## Fields | Field | Type | Description | Source | | --- | --- | --- | --- | | `opportunity_id` | UUID | Primary identifier for the opportunity in Tango (parent notice). | Tango / SAM.gov | | `latest_notice_id` | UUID | The Tango `notice_id` of the latest notice associated with this opportunity (when available). | Tango | | `active` | Boolean | Whether the opportunity is active. | Tango (derived) | | `archive_date` | DateTime | Archive date for the opportunity (derived from SAM.gov notice archive metadata when present). | Tango / SAM.gov | | `agency_id` | String | Agency code associated with the opportunity (when available). | Tango / SAM.gov | | `award_amount` | String | Award amount from the opportunity's own award notice, as SAM publishes it (a string, not a number). `null` unless SAM posted an award notice. | SAM.gov | | `award_count` | Integer | On a solicitation, the total number of award opportunities linked back to it (not capped). `null` when none are linked. | Tango (derived) | | `award_date` | Date | Award date from the opportunity's own award notice. | SAM.gov | | `award_number` | String | Award number when awarded. | SAM.gov | | `awarded` | Boolean | `true` when the opportunity carries an award number or has award notices linked back to it. Never `null`. Independent of `active`. | Tango (derived) | | `awardee` | String | Awardee name from the opportunity's own award notice. | SAM.gov | | `awardee_uei` | String | Awardee UEI from the opportunity's own award notice. | SAM.gov | | `awards` | Array | On a solicitation, up to ten of the most recent linked awards. Use expansion for subfields; see below. | Tango (derived) | | `department_id` | String | Department code associated with the opportunity (when available). | Tango / SAM.gov | | `description` | String | Opportunity description (from latest notice). | SAM.gov | | `first_notice_date` | DateTime | First notice date. | SAM.gov | | `last_notice_date` | DateTime | Last notice date. | SAM.gov | | `meta` | Object | Metadata: `notices_count`, `attachments_count`, `files_count`, `links_count`, `notice_type`. Use expansion for subfields. The three attachment counts are explained in [Attachments: files and links](#attachments-files-and-links). | Tango | | `naics_code` | String | NAICS code. | SAM.gov | | `office` | Object | Contracting office. Use expansion for `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`. | SAM.gov | | `office_id` | String | Office code associated with the opportunity (when available). | Tango / SAM.gov | | `place_of_performance` | Object | Place of performance. Use expansion for `street_address`, `city`, `state`, `zip`, `country`. | SAM.gov | | `primary_contact` | Object | Primary contact (expand for subfields). | SAM.gov | | `secondary_contact` | Object | Secondary contact. | SAM.gov | | `psc_code` | String | Product/Service Code. | SAM.gov | | `response_deadline` | DateTime | Response deadline. | SAM.gov | | `sam_url` | String | Canonical SAM.gov opportunity URL. | Tango (derived) | | `set_aside` | String | Set-aside code. Use expansion `set_aside(code,description)` for the structured form. | SAM.gov | | `snippet` | String | Present only on `/api/opportunities/?search=` rows when an attached document yields a matching excerpt: about 15–35 words with matched terms wrapped in HTML `` tags. Added after shaping, and only when the shape includes `opportunity_id`; listing it in `shape` has no effect. | Tango (derived from attachment text) | | `solicitation_number` | String | Solicitation number. | SAM.gov | | `solicitation_opportunity_id` | UUID | On an award, the `opportunity_id` of the solicitation it was made under. `null` when the award notice does not reference its solicitation. | Tango (derived) | | `title` | String | Opportunity title (from latest notice). | SAM.gov | ## Expansions (via `shape`) - `attachments` – `attachment_id`, `file_size`, `mime_type`, `name`, `posted_date`, `resource_id`, `type`, `url`, plus the Pro+ sub-fields `doc_role`, `doc_role_alt` and `extracted_text` (each returned only when named explicitly β€” none ride `attachments(*)`). `type` is `file` or `link`; see [Attachments: files and links](#attachments-files-and-links). - `awards` – `opportunity_id`, `notice_id`, `award_number`, `award_date`, `award_amount`, `awardee`, `awardee_uei` for up to ten of the most recent linked awards (`award_count` is the total) - `office` – office and agency fields - `agency` – `code`, `name`, `abbreviation` - `department` – `code`, `name`, `abbreviation`, `description`, `cgac`, `website`, `congressional_justification` - `latest_notice` – `notice_id`, `link` - `place_of_performance` – address fields - `meta` – `notices_count`, `attachments_count`, `files_count`, `links_count`, `notice_type` (with nested `notice_type(code, type)`) ## Attachments: files and links An opportunity's or notice's `attachments` list holds two different kinds of thing, and each row's `type` says which one it is. Everything in this section applies to both `/api/opportunities/` and `/api/notices/`. | `type` | What it is | What you get | | --- | --- | --- | | `file` | A document attached to the notice. | `name`, `mime_type`, `file_size` and `url`. Files are the only attachments with extracted text (`extracted_text`) and a document role (`doc_role`), both Pro+ sub-fields. | | `link` | A URL the notice lists, pointing somewhere else: another procurement system's page for the same solicitation, a portal landing page, or standard reference material. | A `url`, usually no `name`, and a `file_size` of 0. A link never has extracted text. | About a third of attachments are links (34% on notices posted in 2026), and almost all links have no `name` (98%). So a notice can report several attachments and have no documents at all. ### Counting files and links `files_count` / `file_count` and `links_count` / `link_count` need API version 5.9.0 or later; `GET /api/version` reports what you are calling. | Resource | Total | Files | Links | | --- | --- | --- | --- | | Opportunities | `meta.attachments_count` | `meta.files_count` | `meta.links_count` | | Notices | `attachment_count` | `file_count` | `link_count` | - **The total counts every attachment, links included.** It is unchanged by the two newer fields. - **`files_count` / `file_count`** is the number of attachments with `type` `file`. It counts files attached, not files whose text was successfully extracted. - **`links_count` / `link_count`** is the number with `type` `link`. - **Files plus links need not equal the total.** An attachment whose `type` is missing or is anything other than `file` or `link` counts only in the total. - **`null` means not yet counted, not zero.** The file and link counts are integers that are filled in as records are processed, so treat `null` as unknown. On opportunities the two fields are part of `meta(*)`, so they arrive in both default shapes. On notices `file_count` and `link_count` are top-level fields in the default list and detail shapes. ### Does this have documents? Read the file count: `meta.files_count` on an opportunity, `file_count` on a notice. It means the same thing on both: | File count | Meaning | | --- | --- | | Greater than 0 | Has documents. | | 0 | No documents: the `attachments` list holds no `file` rows. | | `null` | Not yet counted. Request `attachments` and look for a row with `type` `file`. | Do not use the total for this: it includes links. A record that has not been counted yet reads `null`, so handle that case rather than treating it as 0. #### Checking the `attachments` list (every API version) These requests name only fields that exist on every API version: ```bash # An opportunity /api/opportunities/{opportunity_id}/?shape=opportunity_id,meta(attachments_count),attachments(type,name,file_size,url) # A notice /api/notices/{notice_id}/?shape=notice_id,attachment_count,attachments(type,name,file_size,url) ``` The responses in this section are illustrative. A notice with links only, where every attachment points somewhere else and there is nothing to read: ```json { "notice_id": "0a1b2c3d-1111-4222-8333-444455556666", "attachment_count": 3, "attachments": [ {"type": "link", "name": null, "file_size": 0, "url": "https://piee.eb.mil/sol/xhtml/unauth/search/oppMgmtLink.xhtml?solNo=W912DY26R0001"}, {"type": "link", "name": null, "file_size": 0, "url": "https://pieetraining.eb.mil/wbt/xhtml/wbt/sol/index.xhtml"}, {"type": "link", "name": null, "file_size": 0, "url": "https://piee.eb.mil/xhtml/unauth/web/homepage/vendorGettingStartedHelp.xhtml"} ] } ``` A notice with files and links: ```json { "notice_id": "7e8f9a0b-1111-4222-8333-444455556666", "attachment_count": 3, "attachments": [ {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"}, {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"}, {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"} ] } ``` #### With the counts (API version 5.9.0 or later) Name the count fields only on API version 5.9.0 or later. On an earlier version they do not exist, and a `shape` that names an unknown field returns a 400; see [Validation & limits](../guides/patterns/response-shaping.md#validation-limits). ```bash /api/notices/{notice_id}/?shape=notice_id,attachment_count,file_count,link_count,attachments(type,name,file_size,url) ``` The files-and-links notice above then reports its counts alongside the list: ```json { "notice_id": "7e8f9a0b-1111-4222-8333-444455556666", "attachment_count": 3, "file_count": 2, "link_count": 1, "attachments": [ {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"}, {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"}, {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"} ] } ``` The same request on an opportunity: ```bash /api/opportunities/{opportunity_id}/?shape=opportunity_id,meta(attachments_count,files_count,links_count),attachments(type,name,file_size,url) ``` The counts arrive under `meta`: ```json { "opportunity_id": "3c4d5e6f-1111-4222-8333-444455556666", "meta": {"attachments_count": 3, "files_count": 2, "links_count": 1}, "attachments": [ {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"}, {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"}, {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"} ] } ``` ### Documents hosted on PIEE Department of Defense notices whose documents are hosted on PIEE (the Procurement Integrated Enterprise Environment) are the most common links-only case. They typically list a link to the PIEE notice page plus standard reference links, such as vendor training and access instructions, as in the first example above. Where Tango has retrieved the documents from PIEE, they appear as ordinary `file` rows. For those rows `url` is the PIEE notice page, not a direct download, because PIEE offers no per-file download address. State, local and education records count attachments under their own rules; see the [SLED data dictionary](sled.md). ## Notice type codes Opportunities and notices classify the notice β€œtype” using a short code. These values come from SAM.gov, with Tango normalizing them to the codes below: | Code | Meaning | | --- | --- | | `a` | Award Notice | | `g` | Sale of Surplus Property | | `i` | Consolidate/(Substantially) Bundle | | `j` | Justification and Approval (J&A) | | `k` | Combined Synopsis/Solicitation | | `l` | Fair Opportunity / Limited Sources Justification (deprecated) | | `m` | Modification/Amendment/Cancel | | `o` | Solicitation | | `p` | Pre solicitation | | `r` | Sources Sought | | `s` | Special Notice | | `u` | Justification (J&A) | ## Data Sources - **SAM.gov** – Contract opportunity notices, offices, contacts, attachments. - **Tango** – `opportunity_id`, aggregation, `sam_url`, `active`, `awarded`, and the award-to-solicitation linkage (`solicitation_opportunity_id`, `award_count`, `awards`). ## Award fields SAM.gov posts a contract award as a separate award notice, which appears in Tango as its own opportunity. `award_date`, `award_amount`, `awardee` and `awardee_uei` are filled only where SAM has posted an award notice, and all four come from the same notice. An award is linked to its solicitation only when SAM's award notice references it. A linked award carries `solicitation_opportunity_id`, and the solicitation counts it in `award_count` and lists it in `awards`. An award notice posted without that reference stays unlinked. `awarded` does not change the meaning of `active`: an award can be posted on a solicitation that is still open (multiple-award vehicles are the common case), so an opportunity can be both `active` and `awarded`. ## Usage Notes - **Use `opportunity_id` for API references.** Use `sam_url` for linking to SAM.gov. - **Notices:** For individual notice-level data, use `/api/notices/`; see [Notices API Reference](../api-reference/notices.md) and [Notices Data Dictionary](notices.md). --- --- description: "Field definitions for /api/organizations/, Tango's unified federal hierarchy endpoint." updated: 2026-05-13 --- # Organizations Data Dictionary This document describes the fields available in the Organizations API endpoint (`/api/organizations/`). For filtering, ordering, and pagination, see the [Organizations API Reference](../api-reference/organizations.md). ## Overview The Organizations resource provides a unified view of federal government organizations, consolidating data from multiple authoritative sources into a single hierarchical structure. Organizations include departments, agencies, sub-agencies, and offices. **Note**: The full set of fields is available via the `shape` query parameter. Without a `?shape=` parameter, a [default shape](#default-shape) is applied. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency All organization data is refreshed **monthly** by the Tango ingest pipeline. ## Default Shape All responses go through the shaping pipeline. When no `?shape=` parameter is provided, the following fields are returned: `key, fh_key, name, short_name, type, level, is_active, code, fpds_code, cgac, canonical_code, parent_fh_key, full_parent_path_name` ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `key` | UUID | Tango's internal UUID primary key for the organization record. Returned in shaped responses, but the Organizations API uses `fh_key` for lookups. | Tango | | `fh_key` | String | Zero-padded 9-character string representation of the Federal Hierarchy `orgKey` (e.g., `"000000001"`). Used for detail lookups: `GET /api/organizations/{fh_key}/`. Accepts both zero-padded and plain integer forms in URLs. Practically unique for "current" org lookups, but **not guaranteed to be globally unique across all historical snapshots** (Tango stores historical org versions separately). | Federal Hierarchy (SAM.gov) | | `name` | String | The full official name of the organization (e.g., "Federal Emergency Management Agency"). | Federal Hierarchy (SAM.gov) | | `short_name` | String | The abbreviated or common name of the organization (e.g., "FEMA", "DHS"). | Federal Hierarchy (SAM.gov) | | `type` | String | The organizational type within the federal hierarchy (e.g., "DEPARTMENT", "AGENCY", "OFFICE"). | Federal Hierarchy (SAM.gov) | | `level` | Integer | The depth level in the organizational hierarchy. Level 1 represents top-level departments, with higher numbers indicating deeper nesting. | Federal Hierarchy (SAM.gov) | | `cgac` | String | Common Government-wide Accounting Classification code. A 3-character code used for financial reporting (e.g., "069" for Department of Transportation). | USAspending | | `fpds_code` | String | Federal Procurement Data System code. A 4-digit agency identifier used in contract transactions. | USAspending | | `code` | String | Office or agency code. Used to identify specific offices within agencies, particularly in contract and financial assistance transactions. | Federal Hierarchy / USAspending | | `canonical_code` | String | Level-prefixed canonical code combining hierarchy level and the appropriate code type (e.g., `"L1:097"` for a department, `"L2:5700"` for an agency). | Calculated | | `fpds_org_id` | String | The FPDS organization identifier, when available. | FPDS | | `aac_code` | String | Activity Address Code, used in some procurement and financial transactions. | Federal Hierarchy (SAM.gov) | | `is_active` | Boolean | Indicates whether the organization is currently active. Derived from the `mod_status` field in Federal Hierarchy. | Federal Hierarchy (SAM.gov) | | `parent_fh_key` | String | Zero-padded 9-character `fh_key` of this organization's parent. Null for top-level departments. | Federal Hierarchy (SAM.gov) | | `full_parent_path_name` | String | A human-readable path showing the full hierarchy from the top-level department to this organization, separated by " > " (e.g., "Department of Homeland Security > Federal Emergency Management Agency"). | Federal Hierarchy (SAM.gov) | | `l1_fh_key` .. `l8_fh_key` | String | Zero-padded 9-character `fh_key` of the ancestor at each hierarchy level (L1 through L8). Null when no ancestor exists at that level. | Federal Hierarchy (SAM.gov) | | `start_date` | Date | The date the organization became active in the Federal Hierarchy. | Federal Hierarchy (SAM.gov) | | `end_date` | Date | The date the organization was deactivated, if applicable. | Federal Hierarchy (SAM.gov) | | `logo` | String | URL to the organization's logo, when available. | Various | | `summary` | String | Short description or mission summary for the organization. | Federal Hierarchy (SAM.gov) | | `mod_status` | String | The modification status of the organization in the Federal Hierarchy (e.g., "ACTIVE", "INACTIVE"). | Federal Hierarchy (SAM.gov) | | `description` | String | A description of the organization's mission or purpose, when available. | Federal Hierarchy (SAM.gov) | | `obligations` | Float | Total federal contract and financial assistance obligations associated with this organization and all its descendants (rolled up from the entire subtree). Alias for `tree_obligations`. Expressed in US dollars. | USAspending | | `total_obligations` | Float | Direct obligations for this specific organization (not rolled up from descendants). Expressed in US dollars. | USAspending | | `tree_obligations` | Float | Total obligations for this organization's entire subtree (the organization plus all descendants). Expressed in US dollars. | USAspending | | `obligation_rank` | Integer | A percentile ranking (1-100) of this organization's obligations relative to other organizations. Higher values indicate larger obligation amounts. | Calculated | ## Usage Notes - The Organizations API lookup key is `fh_key` (Federal Hierarchy `orgKey`), returned as a zero-padded 9-character string. - The `fh_key` is intended for "current" lookups, but it is not a stable globally-unique identifier across all historical snapshots/versions. - If you need to track historical versions, use the internal `key` (UUID) plus timestamps/versions (Tango stores org history separately). ## Organization Types Organization types define the position of an organization within the federal hierarchy. Each type corresponds to a specific hierarchy level: | Type | Level | Description | | ---- | ----- | ----------- | | `DEPARTMENT` | 1 | Top-level federal departments (e.g., Department of Defense, Department of Health and Human Services) | | `AGENCY` | 2 | Major sub-components of departments (e.g., Department of the Army, Food and Drug Administration) | | `SUBTIER AGENCY` | 2 | Alternative designation for level-2 agencies in USAspending data | | `MAJOR COMMAND` | 2 | Military major command (e.g., Army Materiel Command) | | `SUB COMMAND` | 3 | Military sub-command within a major command | | `OFFICE` | 3+ | Sub-agencies, bureaus, and offices at various depths within the hierarchy | ## Expansions The following expansions are available via the `shape` query parameter to include related data: ### `parent` Returns the immediate parent organization with the following fields: - `key` - `fh_key` (zero-padded) - `name` - `short_name` - `type` - `level` - `is_active` - `code` - `cgac` ### `ancestors` Returns a list of all ancestor organizations from the top-level department down to the immediate parent. Each ancestor includes: - `fh_key` (zero-padded) - `name` - `short_name` - `level` ### `children` Returns a list of immediate child organizations (prefetched for performance). Each child includes: - `key` - `fh_key` (zero-padded) - `name` - `short_name` - `type` - `level` - `is_active` - `code` - `cgac` ### `department` Returns the L1 (department-level) ancestor formatted as a legacy-compatible department object. Returns `null` for level 1 organizations (a department doesn't have a department β€” it is one). - `code` β€” the department's CGAC code - `name` β€” the department's full name - `abbreviation` β€” the department's short name / abbreviation ### `agency` Returns the L2 (agency-level) ancestor formatted as a legacy-compatible agency object. Returns `null` for level 1 and 2 organizations (no agency above them). - `code` β€” the agency's FPDS code - `name` β€” the agency's full name - `abbreviation` β€” the agency's short name (resolved via cached lookup) ## Data Sources Organization data is consolidated from multiple authoritative sources with a priority-based system: 1. **Federal Hierarchy (SAM.gov)** - The authoritative source for federal organization structure. Provides the canonical hierarchy, names, and parent-child relationships. 2. **USAspending** - Supplements Federal Hierarchy with operational codes (CGAC, FPDS codes) and obligation data that appear in financial transactions. 3. **Legacy FPDS** - Historical organization data from the Federal Procurement Data System, used to backfill organizations that appear in contract transactions but are missing from current reference sources. Higher-priority sources are never overwritten by lower-priority ones, ensuring that Federal Hierarchy's authoritative structure is preserved while other sources fill in the gaps. ## Example Response The following example shows a default response (no `?shape=` parameter): ```json { "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "fh_key": "100012345", "name": "Federal Emergency Management Agency", "short_name": "FEMA", "type": "AGENCY", "level": 2, "is_active": true, "code": "7022", "fpds_code": "7022", "cgac": "070", "canonical_code": "L2:7022", "parent_fh_key": "100000123", "full_parent_path_name": "Department of Homeland Security > Federal Emergency Management Agency" } ``` The following example shows a shaped response with legacy-compatible expands: ```plaintext /api/organizations/?shape=fh_key,name,type,department(code,name),agency(code,name,abbreviation)&level=3 ``` ```json { "fh_key": "047020017", "name": "FA8219 AFLCMC EGLIN", "type": "OFFICE", "department": { "code": "097", "name": "DEPT OF DEFENSE" }, "agency": { "code": "5700", "name": "DEPT OF THE AIR FORCE", "abbreviation": "USAF" } } ``` ## Usage Notes - **Use `fh_key` for API lookups** β€” The Organizations API uses `fh_key` in the detail URL: `GET /api/organizations/{fh_key}/`. The `fh_key` is returned as a zero-padded 9-character string (e.g., `"000000001"`). - **Use `key` as an internal identifier** β€” `key` is Tango's internal UUID primary key and may be useful for internal joins/debugging. - **Use code lookups for transaction matching** β€” When matching contract or financial assistance transactions, use the specific code type (`cgac`, `fpds_code`, `code`) that appears in your source data. - **Use the `search` parameter for discovery** β€” The `/api/organizations/?search=` endpoint handles abbreviations, acronyms, typos, and contextual queries (e.g., "Treasury OIG"). - **Level behavior for `department`/`agency` expands** β€” The `department` expand is defined for level 2+ orgs; the `agency` expand is defined for level 3+ orgs. When these expands are requested on orgs below the applicable level, the corresponding field is included in the response as `null` (no error is raised). Filter by `level` if you want to avoid `null` values in list responses. --- --- description: "Field definitions for /api/otas/, Tango's Other Transaction Agreement endpoint." updated: 2026-05-13 --- # OTAs Data Dictionary This document describes the fields available in the OTAs API endpoints (`/api/otas/`). For filtering, ordering, and pagination, see the [OTAs API Reference](../api-reference/otas.md). ## Overview OTAs (Other Transaction Agreements) are non-standard procurement instruments. OTAs are sourced from **FPDS only**. ## Identifiers - `key` (canonical): The canonical award identifier derived from FPDS award keys. This is what the API uses for lookups: `GET /api/otas/{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. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency OTA data is refreshed from FPDS **twice daily** by the Tango ingest pipeline. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `key` | String | Canonical award identifier (FPDS). Used for detail lookups and cross-referencing. | FPDS | | `piid` | String | Procurement Instrument Identifier. | FPDS | | `award_date` | Date | Date the OTA was awarded. | FPDS | | `psc_code` | String | Product/Service Code on the award. | FPDS | | `total_contract_value` | Decimal | Total value. | FPDS | | `base_and_exercised_options_value` | Decimal | Base plus exercised options. | FPDS | | `fiscal_year` | Integer | Federal fiscal year. | FPDS | | `obligated` | Decimal | Total obligated amount. | FPDS | | `description` | String | OTA description/title. | FPDS | | `award_type` | String | Award type code. Expandable to `{code, description}` via `?shape=`. | FPDS | | `type_of_ot_agreement` | String | Type of OT agreement code. Expandable to `{code, description}` via `?shape=`. | FPDS | | `extent_competed` | String | Extent competed code. Expandable to `{code, description}` via `?shape=`. | FPDS | | `consortia` | String | Consortia indicator. | FPDS | | `consortia_uei` | String | Consortia UEI. | FPDS | | `dod_acquisition_program` | String | DoD acquisition program identifier. | FPDS | | `non_governmental_dollars` | Decimal | Non-governmental dollars. | FPDS | | `non_traditional_government_contractor_participation` | String | Non-traditional government contractor participation indicator. | FPDS | | `parent_award_modification_number` | String | Parent award modification number. | FPDS | | `transactions` | Array | Modification/transaction records. Use expansion for same fields as contracts. | FPDS | ## Expansions (via `shape`) `recipient`, `place_of_performance`, `parent_award`, `awarding_office`, `funding_office`, `period_of_performance`, `award_type`, `type_of_ot_agreement`, `extent_competed`, `transactions`, `psc`. ## Data Sources - **FPDS** – OTA actions, PIID, dates, values, types. - **Tango** – Internal deterministic `uuid` and award materialization. ## Usage Notes - **Use `key` for API references.** Use `piid` for FPDS lookups. --- --- description: "Field definitions for /api/otidvs/, Tango's Other Transaction IDV endpoint." updated: 2026-05-13 --- # OTIDVs Data Dictionary This document describes the fields available in the OTIDVs API endpoints (`/api/otidvs/`). For filtering, ordering, and pagination, see the [OTIDVs API Reference](../api-reference/otidvs.md). ## Overview OTIDVs (Other Transaction IDVs) are indefinite-delivery Other Transaction vehicles. OTIDVs are sourced from **FPDS only**. ## Identifiers - `key` (canonical): The canonical award identifier derived from FPDS award keys. This is what the API uses for lookups: `GET /api/otidvs/{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. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency OTIDV data is refreshed from FPDS **twice daily** by the Tango ingest pipeline. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `key` | String | Canonical award identifier (FPDS). Used for detail lookups and cross-referencing. | FPDS | | `piid` | String | Procurement Instrument Identifier. | FPDS | | `award_date` | Date | Date the OTIDV was awarded. | FPDS | | `psc_code` | String | Product/Service Code on the award. | FPDS | | `total_contract_value` | Decimal | Total value. | FPDS | | `base_and_exercised_options_value` | Decimal | Base plus exercised options. | FPDS | | `fiscal_year` | Integer | Federal fiscal year. | FPDS | | `obligated` | Decimal | Total obligated amount. | FPDS | | `description` | String | OTIDV description/title. | FPDS | | `idv_type` | Object | IDV type. | FPDS | | `consortia` | String | Consortia indicator. | FPDS | | `consortia_uei` | String | Consortia UEI. | FPDS | | `dod_acquisition_program` | String | DoD acquisition program identifier. | FPDS | | `non_governmental_dollars` | Decimal | Non-governmental dollars. | FPDS | | `non_traditional_government_contractor_participation` | String | Non-traditional government contractor participation indicator. | FPDS | | `type_of_ot_agreement` | String | Type of OT agreement code. Expandable to `{code, description}` via `?shape=`. | FPDS | | `extent_competed` | String | Extent competed code. Expandable to `{code, description}` via `?shape=`. | FPDS | | `transactions` | Array | Modification/transaction records. Use expansion for same fields as contracts. | FPDS | ## Expansions (via `shape`) `recipient`, `place_of_performance`, `awarding_office`, `funding_office`, `period_of_performance`, `type_of_ot_agreement`, `extent_competed`, `transactions`, `psc`. ## Data Sources - **FPDS** – OTIDV actions, PIID, dates, values, types. - **Tango** – Internal deterministic `uuid` and award materialization. ## Usage Notes - **Use `key` for API references.** Use `piid` for FPDS lookups. - **Child awards:** Use `/api/otidvs/{key}/awards/` for orders under this OTIDV; see [OTIDVs API Reference](../api-reference/otidvs.md). --- --- description: "Field definitions for /api/protests/, Tango's GAO, COFC and SBA OHA bid protest endpoint." updated: 2026-09-29 --- # Protests Data Dictionary This document describes the fields available in the Protests API endpoints (`/api/protests/`). For filtering, ordering, and pagination, see the [Protests API Reference](../api-reference/protests.md). ## Overview Protests are bid protest records from GAO, the U.S. Court of Federal Claims (COFC), and SBA OHA (the Small Business Administration's Office of Hearings and Appeals). The API exposes a narrow set of client-facing fields. Source ingest payload details and internal fields (e.g. `external_id`, `data_quality`) are not exposed. Filter by `source_system` (`gao`, `cofc`, or `sba_oha`) to scope results to a single venue. Contract Disputes Act appeals β€” disputes under a contract already awarded, heard by the CBCA and the ASBCA β€” are a separate resource: [Contract appeals](contract-appeals.md). No record appears in both. SBA OHA decisions are size and status appeals β€” a challenge to whether a firm qualifies as small, or as a service-disabled veteran-owned, women-owned, or HUBZone concern β€” rather than challenges to an award. They therefore populate a different set of fields: most name the challenged firm and the NAICS code at issue, and most carry no procuring agency at all. COFC records come from the court's CM/ECF system, which publishes dockets and opinions rather than structured procurement metadata. They carry the case, the plaintiff, the dates and links to the court's own documents. `agency` and `outcome` are read from the court's opinion, so a case the court has not yet issued an opinion in carries an empty `agency` and no `outcome`; `solicitation_number`, `naics_code`, `size_standard`, `outcome_reason`, `challenged_party` and `judge` are not available from this source. A case arrives as a filing or as an opinion depending on which part of the court's system published it, so about 60% carry `filed_date` and `docket_url` and about 45% carry `decision_date` and `decision_url`. **Authentication**: Protests endpoints require authentication (API key or OAuth2). **Coverage**: The API covers protest decisions from **2015 onward** for GAO and SBA OHA β€” the effective floor for the `filed_date` and `decision_date` filters alike. Pre-2015 records exist in the database but are not available through the API. COFC coverage starts in 2026 and moves forward: the court publishes a rolling twelve months of opinions, so earlier material is outside what this source offers. **Note**: Both **list** and **detail** endpoints return case-level objects. Each case is identified by `case_id` (a deterministic UUID from `source_system` + `base_case_number`). Detail lookup uses `case_id` in the URL path: `GET /api/protests/{case_id}/`. Use `?shape=...,dockets(...)` to expand nested docket records. The default (unshaped) response does not include dockets. ## Update Frequency GAO and SBA OHA protest data is refreshed by loader schedule and available source files. SBA OHA decisions arrive daily. COFC filings and opinions are collected daily. ## Fields (API response) Only the following fields are returned in list and detail responses (and are available via `shape`): | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `case_id` | UUID | Deterministic case UUID derived from `source_system` + `base_case_number`. Use for detail lookup: `GET /api/protests/{case_id}/`. | Tango | | `source_system` | String | Source venue identifier: `gao`, `cofc`, or `sba_oha`. | Tango | | `case_number` | String | Base case for grouping sub-dockets (for example `b-424214` from `B-424214.1`). Model field: `base_case_number`. Use with `decision_date` for decision-level counting. | Derived | | `docket_number` | String | Source docket identifier (for example `b-424214.1`, `b-424214.2`). Model field: `case_number`. Only available inside the `dockets(...)` expansion. Use to distinguish sub-dockets under the same `case_number`. | Source | | `title` | String | Protest title. | Source | | `protester` | String | Protester name. | Source | | `agency` | String | Protested agency, as `Department : Sub-unit` when the sub-unit is known (for example `Department of the Navy : Naval Sea Systems Command`). COFC and SBA OHA read it from the opinion or decision text; empty when the text names none. | Source | | `solicitation_number` | String | Solicitation number when provided. Not available on COFC. | Source | | `case_type` | String | Protest case type. GAO uses values like `Bid Protest`; COFC is always `Bid Protest`; SBA OHA uses `SIZE`, `NAICS`, `VSBC`, `CVE`, `BDPE`, `SDVOSB`, `BDPT`, `WOSB`, and `HUBZONE`. | Source | | `outcome` | String | Protest outcome, when available. GAO returns `Denied`, `Dismissed`, `Withdrawn`, or `Sustained`; SBA OHA additionally returns `Granted`, `Remanded`, `Reversed`, or `Vacated`. COFC returns `Sustained`, `Denied`, or `Dismissed` once the court issues an opinion. | Source | | `filed_date` | Date | Date the protest was filed. | Source | | `posted_date` | Date | Date the protest was posted. | Source | | `decision_date` | Date | Decision date, when available. | Source | | `due_date` | Date | Protest due date, when available. | Source | | `docket_url` | String | Source docket URL. On COFC, the court's CM/ECF docket report, on cases that arrived as a filing. | Source | | `decision_url` | String | Source decision URL, when available. | Source | **Opt-in via shape only:** `digest` β€” when requested with `?shape=...,digest`, the value from `raw_data.digest` (e.g. decision summary text) is returned. Not included in the default list/detail response. **Opt-in via shape only, SBA OHA:** the five fields below are populated on SBA OHA decisions and are null on GAO and COFC records. Because they are null for most of the table, they are excluded from the default response β€” request them explicitly, for example `?shape=case_id,case_number,challenged_party,naics_code`. They are available on every plan. | Field | Type | Description | | ----- | ---- | ----------- | | `challenged_party` | String | The firm whose size or socioeconomic status was challenged. | | `naics_code` | String | The NAICS code at issue in the appeal. Also available as a filter: `?naics_code=541512`. | | `size_standard` | String | The applicable size standard as written, for example `$33.5 million` or `1,000 employees`. | | `outcome_reason` | String | Why a case was dismissed: `untimely`, `moot`, `withdrawn`, `lack of jurisdiction`, `lack of standing`, or `insufficient specificity`. | | `judge` | String | The authoring administrative judge. | ## Resolution Fields (shape expansions) Protests support entity and organization resolution via the Bayesian resolver. These fields are available as shape expansions and return `null` when no confident match exists. ### `resolved_protester(...)` β€” Entity Resolution | Field | Type | Description | | ----- | ---- | ----------- | | `uei` | String | Unique Entity Identifier of the matched entity. | | `name` | String | Display name of the matched entity. | | `match_confidence` | String | `"confident"` (high confidence, auto-linkable) or `"review"` (medium confidence, needs human review). | | `rationale` | String | Human-readable explanation (e.g. `"Exact name match"`, `"Similar name match; multiple entities share this name"`). | ### `resolved_agency(...)` β€” Organization Resolution | Field | Type | Description | | ----- | ---- | ----------- | | `key` | String (UUID) | UUID primary key of the matched organization in Tango. | | `name` | String | Display name of the matched organization. | | `match_confidence` | String | `"confident"` or `"review"`. | | `rationale` | String | Human-readable explanation (e.g. `"Exact name match; parent agency confirmed"`). | **Confidence mapping**: Internal resolution tiers map to public labels as follows: `high` β†’ `"confident"`, `medium` β†’ `"review"`. Low-confidence and no-match results are excluded (return `null`). The following are **not** exposed in the API: `external_id`, `data_quality`, `source_last_updated`, `created`, `modified`, `raw_data`, `field_provenance`. ## Data Quality (internal) Every protest record has an internal `data_quality` tier (not exposed in the API response). Records with `quarantined` or `unknown` quality are **always excluded from API responses**. Quality is recomputed on each ingestion cycle. ## Shaping Both list and detail return case-level objects. `shape` lets you request a subset of fields. Use the `dockets(...)` expansion to include nested docket records. Allowed shape fields (case-level): - `case_id`, `source_system`, `case_number`, `title`, `protester`, `agency` - `solicitation_number`, `case_type`, `outcome` - `filed_date`, `posted_date`, `decision_date`, `due_date` - `docket_url`, `decision_url` - `digest` (from `raw_data.digest`; opt-in only) - `dockets` (expand with docket fields, e.g. `dockets(case_number,docket_number,filed_date)`) - `resolved_protester` (expand: `uei`, `name`, `match_confidence`, `rationale`) - `resolved_agency` (expand: `key`, `name`, `match_confidence`, `rationale`) Inside `dockets(...)`, these additional fields are available: - `docket_number` (specific sub-docket identifier, e.g. `b-424214.1`) Examples: ```bash # List: case-level and nested dockets GET /api/protests/?shape=case_id,case_number,title,dockets(docket_number,filed_date,outcome) # List: case-level only GET /api/protests/?shape=case_id,title,outcome,decision_date # Detail with nested dockets GET /api/protests/{case_id}/?shape=case_id,title,dockets(docket_number,filed_date) ``` `raw_data` and field-level provenance metadata are internal-only and not exposed in API responses. ## Data Sources - **GAO** – primary source for protest records. - **SBA OHA** – size and status appeal decisions from the Small Business Administration's Office of Hearings and Appeals. - **Tango** – `case_id` (deterministic case UUID) and normalized API behavior. --- --- description: "Field definitions for /api/psc/, the Product and Service Code reference endpoint." updated: 2026-05-13 --- # Product and Service Code (PSC) Data Dictionary This document describes the fields available in the Product and Service Code (PSC) API endpoints (`/api/psc/`). For filtering, ordering, and pagination, see the [PSC API Reference](../api-reference/psc.md). ## External references - [Product and Service Code Manual](https://www.acquisition.gov/psc-manual) ## Overview Product and Service Codes (PSC) classify products and services in federal contracting. Each code has a `code` (string) and a current description; historical descriptions are available when requesting a β€œcomplete” representation. **Note**: This endpoint supports [response shaping](../guides/patterns/response-shaping.md) via the `shape` query parameter. Expansions include `current(...)` for the active description and `historical(...)` for all descriptions. ## Update Frequency PSC reference data is updated when the PSC Manual or Tango loaders are refreshed (periodic). ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `code` | String | PSC code (primary key). | PSC Manual | | `current` | Object | Full current description record (`name`, `description`, dates, includes/excludes). Present on list/detail responses. | PSC Manual | | `historical` | Array | Historical descriptions. Present only when `?complete=true`. | PSC Manual | | `parent` | String | Parent PSC code in hierarchy. | PSC Manual | | `category` | String | Category (e.g., `S` Service, `P` Product). | PSC Manual | | `level_1_category` | String | Level 1 category name. | PSC Manual | | `level_1_category_code` | Integer | Level 1 category code. | PSC Manual | | `level_2_category` | String | Level 2 category name. | PSC Manual | | `level_2_category_code` | String | Level 2 category code. | PSC Manual | **Metrics:** Time-series obligation metrics are available at `/api/psc/{code}/metrics///`; see [Metrics](../api-reference/metrics.md). ## Data Sources - **PSC Manual (acquisition.gov)** – Code definitions, descriptions, hierarchy. - **Tango** – Obligation rollups (via metrics endpoint). ## Usage Notes - **Use `code` for lookups.** Filter by `has_awards` to restrict to PSCs that appear in award data; see [PSC API Reference](../api-reference/psc.md). --- --- description: "Field definitions for the SBIR/STTR topics and DoD DSIP solicitation endpoints." updated: 2026-08-01 --- # SBIR/STTR Data Dictionary This document describes the fields available on the SBIR/STTR API endpoints (`/api/sbir/topics/`, `/api/sbir/solicitations/`). For filtering, ordering, and pagination, see the [SBIR API Reference](../api-reference/sbir.md). ## Overview The SBIR/STTR endpoints cover Small Business Innovation Research and Small Business Technology Transfer **topics** across every participating agency (DoD, NIH, NSF, NASA, DOE, DOT and more), and the DoD DSIP **solicitation** cycles those topics belong to. Topics link to the parent that funds them β€” a DSIP cycle, a SAM.gov notice, or a Grants.gov announcement. Solicitations are DoD (DSIP) only. **Note**: The full field set is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Lifecycle: `activity` Both resources expose a derived `activity` field. On topics it is `open`, `closed`, or `unknown` (no usable date roster). On solicitations it is `open` or `closed`, derived from the cycle `end_date`. `activity` is computed at query time; `solicitation_status` is the source's own raw status string and is exposed separately. ## Topic fields (`/api/sbir/topics/`) Detail lookup is by `topic_id`. | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `topic_id` | String | Primary key; natural key minted by Tango (`sbir-topic-`). | Tango | | `topic_node_id` | String | Source node id (e.g. Drupal `12835`). | sbir.gov | | `topic_url` | String | Link to the topic on the source site. | sbir.gov | | `title` | String | Topic title. | sbir.gov | | `agency` | String | Raw agency text as the feed carries it, department-level (`DOD`, `NSF`, `DOE`, `NASA`, `HHS`, `DHS`, `DOT`, `EPA`, `DOC`, `USDA`, `ED`). Component agencies are not values β€” NIH topics carry `HHS`. The resolved organization is the `organization` expand. | sbir.gov | | `year` | Integer | Solicitation year. | sbir.gov | | `topic_number` | String | Topic number. | sbir.gov | | `solicitation_number` | String | Parent BAA number; with `cycle_name`, joins to the parent solicitation. | sbir.gov | | `cycle_name` | String | DoD DSIP cycle name (e.g. `DOD_SBIR_2026_P1_CBZ`); links a DSIP-fed topic to its parent cycle. Empty string for topics not fed from DSIP. | DSIP | | `official_solicitation_url` | String | Link to the official solicitation. | sbir.gov | | `doc_source` | String | Document source: `grants_gov`, `dsip`, `sam_gov`, `other`, `none`. | Tango | | `description` | String | Topic description (detail default). | sbir.gov | | `release_date` | Date | Topic release date. | sbir.gov | | `open_date` | Date | Topic open date. | sbir.gov | | `close_date` | Date | Topic close date β€” reflects the topic's own schedule and outranks the parent BAA window. | sbir.gov | | `due_dates_text` | String | Raw `Due Date(s)` cell; may list several (detail default). | sbir.gov | | `solicitation_status` | String | sbir.gov's own Open/Closed string (source data, not derived). | sbir.gov | | `listed_open` | Boolean | On sbir.gov's open listing at the last complete crawl? False = withdrawn; null = no usable roster (detail default). | Tango | | `source_last_updated` | DateTime | Feed scrape timestamp (detail default). | Tango | | `activity` | String | Computed lifecycle: `open`, `closed`, or `unknown`. | Tango | | `solicitation` | Object | Parent DoD DSIP cycle (expand). | Tango | | `opportunity` | Object | Parent SAM.gov notice (expand). | Tango | | `grant` | Object | Parent Grants.gov announcement (expand). | Tango | | `organization` | Object | Organization resolved from `agency` (expand); `null` when it resolves to none. | Tango | ### Topic expansions (via `shape`) - `solicitation(*)` β†’ `solicitation_id`, `solicitation_number`, `title`, `program`, `cycle_name`, `year`, `start_date`, `end_date`, `out_of_cycle`, `solicitation_status` - `opportunity(*)` β†’ `opportunity_id`, `title`, `solicitation_number`, `response_deadline` - `grant(*)` β†’ `grant_id`, `opportunity_number`, `title`, `response_date` - `organization(*)` β†’ `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` A topic links to at most one parent, resolved in priority order (solicitation β†’ opportunity β†’ grant). A DSIP parent is matched on `cycle_name` first, then `solicitation_number`. A non-DoD topic with no DSIP parent returns `solicitation: null`. ## Solicitation fields (`/api/sbir/solicitations/`) Detail lookup is by `solicitation_id`. DoD (DSIP) only. | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `solicitation_id` | String | Primary key; natural key minted by Tango (`dsip-solicitation-`). | Tango | | `solicitation_number` | String | Solicitation number. | DSIP | | `title` | String | Solicitation title. | DSIP | | `program` | String | Program: `SBIR` or `STTR`. | DSIP | | `cycle` | String | Cycle identifier (detail default). | DSIP | | `cycle_name` | String | Cycle directory name; joins the PDF inventory to this cycle. | DSIP | | `solicitation_cycle_id` | Integer | Source cycle id (detail default). | DSIP | | `out_of_cycle` | Boolean | Whether the solicitation is out of cycle. | DSIP | | `year` | Integer | Solicitation year. | DSIP | | `start_date` | Date | Cycle start date. | DSIP | | `end_date` | Date | Cycle end date. Drives `activity`. | DSIP | | `solicitation_status` | String | Raw feed status token (`active`, etc.). | DSIP | | `sol_download_url` | String | Link to download the solicitation. | DSIP | | `source_last_updated` | DateTime | Feed scrape timestamp (detail default). | Tango | | `activity` | String | Computed lifecycle: `open` or `closed`. | Tango | | `topics` | Object[] | Topics on this cycle (expand). | Tango | | `documents` | Object[] | BAA PDF inventory (expand). | Tango | | `organization` | Object | Organization (expand); always the Department of Defense. | Tango | ### Solicitation expansions (via `shape`) - `documents(*)` β†’ `document_id`, `filename`, `cycle_name`, `s3_key`, `file_size`, `extraction_status`, `n_pages`, `n_chars` - `topics(*)` β†’ `topic_id`, `title`, `agency`, `topic_number`, `close_date`, `topic_url` (a reduced view; the full topic shape lives at `/api/sbir/topics/`) - `organization(*)` β†’ `organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` ## Data Sources - **sbir.gov** β€” topic listings across participating agencies. - **DSIP** β€” DoD's Defense SBIR/STTR Innovation Portal solicitation cycles and BAA PDFs. - **Tango** β€” natural keys, the derived `activity`, the resolved parent links (`solicitation`, `opportunity`, `grant`), and the resolved `organization`. ## Not exposed Producer-internal columns are not part of the API: `row_hash`, `search_vector`, the raw `solicitation_cycle_json` blob, and downstream document-extraction text. Document `extraction_status` / `n_pages` / `n_chars` are surfaced, but extracted `text` is not. ## Usage Notes - **Follow a topic to its funding** β€” expand `solicitation(*)`, `opportunity(*)`, or `grant(*)` to reach the DSIP cycle, SAM.gov notice, or Grants.gov announcement behind it. - **Program lives on the solicitation** β€” there is no `program` field or filter on topics; query `/api/sbir/solicitations/?program=STTR` or expand `solicitation(program)`. - **BAA PDFs** β€” expand `documents(*)` on a solicitation for the BAA document inventory. --- --- description: "Field definitions for the state, local and education (SLED) solicitation and forecast endpoints, including why status is Tango's own column and why category scheme tagging is partial." updated: 2026-09-17 --- # State & Local Data Dictionary This document describes the fields available on the SLED API endpoints (`/api/sled/opportunities/`, `/api/sled/forecasts/`, and the nested revisions route). For filtering, ordering, and pagination, see the [State & Local API Reference](../api-reference/sled.md). ## Overview SLED is state, local and education procurement β€” solicitations that never appear on SAM.gov because they were never federal. There is no national feed; every jurisdiction publishes on its own portal, and Tango reads them one at a time. One row is one advertised solicitation, arbitrated across every scrape that observed it and keyed by a Tango-minted `opportunity_id`. **Beta.** Coverage is partial and grows by jurisdiction; field availability varies by state. Call [`/api/sled/opportunities/coverage/`](../api-reference/sled.md#coverage) before treating a per-state count as market size. **Note**: The full field set is available via the `shape` query parameter, and `show_shapes=true` reports the tree your plan can reach. See [Response Shaping](../guides/patterns/response-shaping.md). ## This data does not join to the federal data There is no UEI, no PIID, no agency-hierarchy key and no NAICS/PSC crosswalk. `organization` here is three strings β€” state, level, agency text β€” not the federal 7-key office payload, and state agencies have no entry in Tango's organization tree. `incumbent_name` on a forecast is published text, not a resolved Tango entity. ## `status` is Tango's, and the portal's word is separate `status` is Tango-owned liveness, derived from the portal's own word, the response deadline and the clock, and refreshed every fifteen minutes whether or not the feed moved. It is **not** the feed's status: portals drop a closed solicitation rather than restating it, so most of what the feeds still call open already has a deadline in the past. The feed's word is served separately as `source_status`, and its full raw vocabulary sits behind the plan-gated `raw`. **A list request with no `status` or `active` filter returns open solicitations only.** A detail request returns the solicitation whatever its status. ## Observation timestamps are not publication timestamps Every timestamp whose name contains `seen` is ours, not the agency's. A state portal restates one page in place and publishes no amendment date, so `last_change_seen_at` is the scrape that caught the diff and its resolution is that state's crawl cadence. `first_seen_at` is when we first observed the record, which is the right field to poll on and the wrong field to read as a posting date β€” `posted_date` is that, where the portal publishes one. ## Category scheme tagging is partial `category_codes` is an array of `{scheme, code}` objects over `nigp`, `unspsc`, `naics`, `text` and `unknown`. Scheme tagging is mid-migration: roughly half of all entries corpus-wide are still bare pre-migration strings with no scheme, which read as `unknown`. Consequence: **`?naics=` matches only the small share of entries tagged as NAICS.** Use `?category_code=` to match a code under any scheme including the untagged strings. See [Category codes](../api-reference/sled.md#category-codes). ## Solicitation fields (`/api/sled/opportunities/`) | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `opportunity_id` | String (UUID) | Tango-minted stable primary key; the detail lookup value. | Tango | | `solicitation_number` | String | The number a human would quote. Null on roughly a third of the corpus, where the portal publishes none. | Portal | | `solicitation_type` | String | `rfp`, `ifb`, `rfq`, `rfi`, `itb`, `sole_source`, `grant` or `other`. Null means the portal states no type β€” a distinct answer from `other`. | Portal / Tango | | `solicitation_type_source` | String | Where the type came from: `portal`, `title`, `description` or `none`. About half of type fill is inferred rather than published. Detail default. | Tango | | `title` | String | Solicitation title. | Portal | | `description` | String | Free-text description. **Detail default only** β€” median around 550 characters, tail past 120,000. Null on about a quarter of open rows and on every row in several states. Reach it on a list with `?verbose=true` or by naming it. | Portal | | `state` | String (2) | Two-letter state or territory code. The primary partition. | Portal | | `jurisdiction` | String | Level of government: `state`, `local` or `education`. Null on aggregator portals that cannot distinguish state from local (filter with `jurisdiction=unknown`). | Portal / Tango | | `agency` | String | The buying body as raw published text. No code resolution β€” some states emit bare agency numbers. | Portal | | `status` | String | Tango-derived liveness: `open`, `closed`, `awarded`, `cancelled`, `unknown`. | Tango | | `status_reason` | String | Which input decided `status`: `deadline_future`, `deadline_past`, `no_deadline`, `source_terminal`, `delisted`. | Tango | | `delisted_at` | Datetime | When a complete crawl of the portal first found the solicitation gone, stamped only if that was before its deadline. Null when never delisted or listed again since. Non-null means `status=closed`, `status_reason=delisted` unless the portal declared a terminal status. API 4.25.3+. | Tango | | `status_computed_at` | Datetime | When Tango last recomputed `status`. Detail default. | Tango | | `source_status` | String | The portal's own status word, frozen at last capture. **Not liveness** β€” see above. | Portal | | `source_url` | String | Link to the solicitation on its own portal. | Portal | | `posted_date` | Datetime | When the portal published it, where it publishes a date. Null on roughly a sixth of the corpus. | Portal | | `response_deadline` | Datetime | Current response deadline. Drives `status`. | Portal | | `response_deadline_original` | Datetime | The first deadline ever observed, which is what makes a moved deadline legible. Detail default. | Tango (provenance) | | `bid_opening_date` | Datetime | Parsed bid-opening date. Populated only where the portal encodes it machine-readably (a small minority of rows) β€” the human spellings are too ambiguous to parse safely. Detail default. | Portal | | `bid_opening_raw` | String | The portal's own bid-opening string, verbatim. Detail default. | Portal | | `category_codes` | Array of objects | `{scheme, code}` entries over `nigp`, `unspsc`, `naics`, `text`, `unknown`. Scheme tagging is partial β€” see above. | Portal / Tango | | `has_documents` | Boolean | Whether the solicitation advertises at least one document. Excludes auto-generated cover sheets. | Portal / Tango | | `first_seen_at` | Datetime | When Tango first observed the solicitation. The polling primitive. | Tango | | `last_seen_at` | Datetime | The most recent scrape that observed it at all. | Tango | | `last_change_seen_at` | Datetime | When Tango **observed** the newest substantive change. A scrape date, not an amendment date. | Tango | | `modified` | Datetime | When the Tango row last changed. | Tango | | `snippet` | String | The passage that matched, injected only under `?search=` and only on rows that matched on their description. Absent on a title-or-agency match. | Tango | | `organization` | Object | The buyer β€” see below. | Portal / Tango | | `contact` | Object | Buyer contact β€” see below. Detail default. | Portal | | `meta` | Object | Denormalized counts β€” see below. | Tango | | `attachments` | Array of objects | Advertised documents β€” see below. Detail default. | Portal / Tango | | `revisions` | Array of objects | Observed amendment history β€” see below. Detail default. | Tango | | `raw` | Object | The platform's unparsed payload. **Small plan or above**, and explicitly unstable: its shape varies by portal platform and is not a contract at any plan. Signed URLs are stripped. | Portal | `platform`, `native_id` and `external_id` are accepted as support filters for reproducing a specific record with us. They are deliberately **not** in any response shape, and their values are not a contract β€” an earlier draft rendered three competing spellings of one solicitation number on a single row. ### `organization` object | Field | Type | Description | | ----- | ---- | ----------- | | `state` | String (2) | Two-letter state or territory code. | | `level` | String | `state`, `local` or `education`; null where the portal cannot distinguish. | | `agency` | String | The buying body as raw published text. | Three strings, not the federal office payload. There is no `organization_id` to join on. ### `contact` object | Field | Type | Description | | ----- | ---- | ----------- | | `name` | String | Buyer contact name, as published. | | `email` | String | Buyer contact email, as published. | | `phone` | String | Buyer contact phone, as published. | ### `meta` object | Field | Type | Description | | ----- | ---- | ----------- | | `attachment_count` | Integer | Documents the record holds, **excluding auto-generated cover sheets**. Can be lower than the length of `attachments` β€” see below. | | `revision_count` | Integer | Substantive revisions, excluding `enrichment`. | | `last_revision_kind` | String | Kind of the newest substantive revision. Never `enrichment`. | | `last_change_source_declared` | Boolean | Whether the portal's own amendment marker moved at the emission behind `last_change_seen_at`. `false` means Tango inferred the change by diffing consecutive scrapes, which is the common case. | ### `attachments` array | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `name` | String | File name as advertised. | Portal | | `extension` | String | File extension. | Portal | | `mime_type` | String | Guessed from the extension; the extraction pass sniffs the bytes regardless. | Tango | | `checksum` | String | Content checksum. Null while a download is in flight. | Tango | | `size_bytes` | Integer | The stored object's size. **Null means no blob is stored** β€” never 0, which would read as an empty file. | Tango | | `char_count` | Integer | Characters extracted. Only meaningful paired with `size_bytes`. | Tango | | `word_count` | Integer | Words extracted. | Tango | | `pages` | Integer | Page count, where the format has pages. | Tango | | `extraction_status` | String | `completed`, `empty` or `failed`. `empty` is extraction succeeding with zero characters β€” almost always a scan awaiting OCR, a different problem from one that threw. | Tango | | `download_status` | String | Whether the document was retrieved. | Tango | | `is_contested` | Boolean | The stored object's checksum disagrees with what this record advertised β€” another solicitation's bytes under the same key. Served as a name and an existence, never as content. | Tango | | `is_generated_summary` | Boolean | An auto-generated portal cover sheet rather than a document the agency wrote. Still listed and still searchable, but excluded from `meta.attachment_count` and `has_documents`. | Tango | | `first_seen_at` | Datetime | When Tango first observed this document on the record. | Tango | | `extracted_text` | String | The document's extracted body. **Small plan or above**, API 4.25.1+, and **not included by `attachments(*)`** β€” ask for it by name. The key is absent (never null) when it is not being served to you. Never returned for a contested document, at any plan. | Tango | **`size_bytes` and `char_count` only mean something together.** Three megabytes that yielded no characters is a scanned image; three megabytes that yielded 40,000 characters is a specification. Neither number says that alone. **No `url`, and the body is paid.** There is no download URL on this endpoint. The document body is served as `extracted_text` on the **Small plan and above** β€” opt-in only, so `attachments(*)` does not carry it β€” and is one of three plan-gated fields on this resource alongside `raw` and `revisions.changes`. **Searching that text is a different thing, and it is ungated.** `?search=` matches inside document text on every plan including Free, and returns the parent solicitation's id with no fragment of the document. So *did a document match* is free; *what does it say* is Small and above. Buying the body does not change search. A document flagged `is_contested` never returns `extracted_text`, at any plan: the file we retrieved for it does not match what the solicitation listed, so we cannot vouch that its text belongs to this record. **Why `meta.attachment_count` can be lower than `len(attachments)`.** A generated cover sheet is a file, not a document the agency wrote, so it is excluded from the count while still being listed and flagged. The count answers "does this record hold its solicitation package"; the array answers "what files exist". A record whose only file is a generated sheet holds no package. ### `revisions` array | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `observed_at` | Datetime | The scrape that saw this change. Not when the agency made it. | Tango | | `sequence` | Integer | 1-based within the record; what to page the history by. | Tango | | `kind` | String | `deadline_change`, `status_change`, `documents_added`, `documents_removed`, `documents_replaced`, `title_change`, `content_change` β€” plus `enrichment` on the nested route only. | Tango | | `changed_fields` | Array of strings | Which fields moved. Available on every plan. | Tango | | `changes` | Object | The per-field before and after. **Small plan or above**; the key is absent below it. | Tango | | `source_declared` | Boolean | `true` only where a portal's own amendment marker changed at this emission β€” about 5% of revisions. Everything else is Tango inferring the change from the diff. | Portal / Tango | The `revisions` expansion excludes `enrichment` rows; the [nested revisions route](../api-reference/sled.md#revisions) serves them. An enrichment is Tango filling in coverage it did not have rather than the agency amending anything, which is also why it is excluded from `revision_count`. **History starts when Tango started reading that jurisdiction**, not when the solicitation was posted. For recently added sources that is days, not months. ## Forecast fields (`/api/sled/forecasts/`) A forecast is a state's own advance notice of something it intends to buy. **Maryland is the only state publishing one today.** Forecasts carry no `status`, no deadline and no liveness filter β€” currency is your call from the advertisement quarter. | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `forecast_id` | String (UUID) | Tango-minted stable primary key; the detail lookup value. | Tango | | `state` | String (2) | Two-letter state code. | Portal | | `agency` | String | The buying body as raw published text. | Portal | | `title` | String | Forecast title. | Portal | | `description` | String | Free-text description. | Portal | | `estimated_advertisement_date` | Datetime | **The start of the published quarter, not a posting date.** A large share of rows publish no quarter at all. | Tango (normalized) | | `estimated_advertisement_raw` | String | The portal's own words, verbatim β€” e.g. `"Q3 (Jan.-March 2027)"`. | Portal | | `procurement_category` | String | The portal's own category word, passed through verbatim. | Portal | | `procurement_method` | String | The portal's own method word, passed through verbatim. | Portal | | `contract_term` | String | Expected term as published. | Portal | | `contract_number` | String | The number the state expects to award under, where it publishes one in advance. | Portal | | `incumbent_name` | String | Incumbent vendor name as published. **Not resolved to a Tango entity.** | Portal | | `mbe_dbe_goal` | String | Published MBE/DBE participation goal. | Portal | | `delivery_location` | String | Delivery or performance location as published. Detail default. | Portal | | `source_url` | String | Link to the forecast on its own portal. | Portal | | `source_status` | String | The portal's own status word, where it publishes one. Not liveness. | Portal | | `has_documents` | Boolean | Whether the forecast advertises at least one document. Detail default. | Portal / Tango | | `first_seen_at` | Datetime | When Tango first observed the forecast. | Tango | | `last_seen_at` | Datetime | The most recent scrape that observed it. | Tango | | `modified` | Datetime | When the Tango row last changed. | Tango | | `organization` | Object | `state`, `level`, `agency` β€” narrower than a solicitation's, since the forecast feed carries no sub-state jurisdiction. | Portal | | `contact` | Object | `name`, `email`, `phone`, as published. Detail default. | Portal | | `estimated_value` | Object | `min`, `max`, `raw` β€” see below. | Tango (parsed) | | `raw` | Object | The platform's unparsed payload. **Small plan or above**, and unstable. | Portal | ### `estimated_value` object | Field | Type | Description | | ----- | ---- | ----------- | | `min` | Number | Low end of the published award band. | | `max` | Number | High end. **Null when the band names only one number** β€” that is a floor, not an unbounded ceiling. | | `raw` | String | The portal's free-text award band, preserved verbatim. | The band is free text from a state spreadsheet, parsed at serve time. `raw` is always there to check the parse against. ## Data sources Solicitations and forecasts are collected from individual state, local and education procurement portals β€” there is no aggregated upstream feed. The set of portals grows over time; `/api/sled/opportunities/coverage/` reports which jurisdictions are represented, how many records each holds, and when a record in that jurisdiction last changed. **Update frequency**: per-portal crawl cadence, which differs by jurisdiction. `status` is recomputed every fifteen minutes independently of the crawl, so a deadline passing is reflected promptly even when the portal has not been read since. --- --- description: "Field definitions for /api/subawards/, Tango's subaward endpoint built from SAM subcontract reports and USAspending." updated: 2026-10-30 --- # Subawards Data Dictionary This document describes the fields available in the Subawards API endpoints (`/api/subawards/`). For filtering, ordering, and pagination, see the [Subawards API Reference](../api-reference/subawards.md). ## Overview A subaward is a subcontract a prime contractor reports under a federal contract or IDV. Each row is **one subaward report**, keyed by the report's own UUID, and carries the report's facts plus the ids that link it to the prime award, the recipients and the place of performance. Recipient and place details live on those records rather than on the subaward. ## Sources Two feeds carry the same reports under two spellings of the same report UUID, and Tango reads both: - **SAM.gov subcontract reporting** β€” the system the prime files the report in, and the authoritative spelling of every field it publishes. - **USAspending** β€” republishes the reports, with the place of performance, the officers and the fiscal-year framing SAM.gov does not publish. Where both publish a field, SAM.gov's value wins; USAspending fills the rest. Amounts are served exactly as published, with `amount_suspect` flagging the implausible ones. ## Identifiers - `key` (subaward): the report UUID, SAM.gov's `subAwardReportNumber` and USAspending's `subaward_sam_report_id`, lowercase. `GET /api/subawards/{key}/`. Keys from before API 5.15.0 were integers and redirect until 2027-04-30; see [Keys](../api-reference/subawards.md#keys). - `award_key` (prime award): the canonical identifier of the prime contract or IDV, the same award-key convention as `/api/contracts/{key}/` and `/api/idvs/{key}/`. - `prime_recipient_id`, `recipient_id`, `recipient_parent_id`: the entity ids (the `uuid` of `/api/entities/`) minted from the prime, subawardee and subawardee-parent UEIs; `null` when the report carries no UEI. - `place_of_performance_id`: the place record the subaward's place of performance resolves to, the same place dimension the award resources use. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency Subaward reports are refreshed **daily** from the SAM.gov subcontract feed and USAspending's daily files, and reconciled against USAspending's full-year archives on each new pull. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `key` | UUID | The report UUID. | SAM.gov / USAspending | | `award_key` | String | Canonical identifier of the prime award. | USAspending / Tango | | `piid` | String | Prime award PIID. | SAM.gov / USAspending | | `prime_awardee_uei` | String | Prime awardee UEI. | SAM.gov / USAspending | | `prime_recipient_id` | UUID | The prime awardee's entity id. | Tango (derived) | | `recipient_uei` | String | Subawardee UEI. | SAM.gov / USAspending | | `recipient_id` | UUID | The subawardee's entity id. | Tango (derived) | | `recipient_parent_uei` | String | Subawardee parent UEI. | SAM.gov / USAspending | | `recipient_parent_id` | UUID | The subawardee parent's entity id. | Tango (derived) | | `place_of_performance_id` | UUID | The place-of-performance record. | Tango (derived) | | `pop_cd_original` | String | Place-of-performance congressional district as reported. | USAspending | | `pop_cd_current` | String | Place-of-performance congressional district under current boundaries. | USAspending | | `amount_suspect` | Boolean | The reported amount is not plausibly a subcontract; see below. | Tango (derived) | | `retired_at` | Timestamp | When the report stopped being published; `null` while live. | Tango (derived) | | `usaspending_permalink` | String | Link to the subaward on USAspending. | USAspending | ### `amount_suspect` `true` when either the amount is at or above one billion dollars, or the amount's digit string is itself written twice (`25092509` for `2509`), a known serialization defect in the reporting system. The amount is served as published either way; this flag says whether to trust it. ### `retired_at` Set when USAspending published the report and its newest full-year archive no longer does, with no re-filing on SAM.gov since; or when a later archive pull no longer carries the report at all. The timestamp is when Tango first saw the report gone, and it stays put; a report that reappears has it cleared. A report only SAM.gov holds is never retired. Lists omit retired reports unless `include_retired=true`. ## Expansions (via `shape`) - `subaward_details` – `description`, `type`, `number`, `amount`, `action_date`, `fiscal_year` - `fsrs_details` – `last_modified_date` (timestamp of the report's last modification), `id` (the report UUID), `year`, `month` - `place_of_performance` – `city`, `state` (two-letter code), `zip`, `country_code`, from the place record - `highly_compensated_officers` – `name`, `amount`, up to five - `prime_recipient` – `uei`, `display_name`, from the entity record - `subaward_recipient` – `uei`, `display_name`, `duns`, from the entity record; an unregistered subawardee returns its `uei` with `display_name: null`, and `duns` is always `null` - `awarding_office` / `funding_office` – office fields, from the prime award ## Data Sources - **SAM.gov** – Subcontract reports: the report, the prime, the subawardee and its parent, the officers. - **USAspending** – The same reports with the place of performance, the officers, the fiscal year and the permalink. - **Tango** – `award_key`, the entity and place ids, `amount_suspect`, `retired_at`, and the arbitration between the two feeds. ## Usage Notes - **Use `key` for subaward lookups.** Use `award_key` to link to the prime contract or IDV. - **Scoped lists:** `/api/contracts/{key}/subawards/` lists subawards under a contract; `/api/entities/{uei}/subawards/` lists those where the entity is the subawardee. - **Several reports can describe one subcontract.** A prime re-files a report when it amends or re-reports a subcontract, so the same prime award, subaward number and subawardee can appear under several keys with different action dates and amounts; summing `amount` across them overstates. --- --- description: "Field definitions for /api/assistance/subgrants/, Tango's subgrant endpoint built from SAM.gov assistance subaward reports and USAspending." updated: 2026-11-03 --- # Subgrants Data Dictionary This document describes the fields available in the Subgrants API endpoints (`/api/assistance/subgrants/`). For filtering, ordering, and pagination, see the [Subgrants API Reference](../api-reference/subgrants.md). ## Overview A subgrant is a subaward a prime recipient reports under a federal grant or cooperative agreement (2 CFR 170). Each row is **one subaward report**, keyed by the report's own UUID, and carries the report's facts plus the ids that link it to the prime assistance award, the recipients and the place of performance. Recipient and place details live on those records rather than on the subgrant. The contract-side reports are [Subawards](subawards.md). ## Sources Two feeds carry the same reports under two spellings of the same report UUID, and Tango reads both: - **SAM.gov assistance subaward reporting** β€” the system the prime files the report in, and the authoritative spelling of every field it publishes. - **USAspending** β€” republishes the reports, with the place of performance, the officers and the fiscal-year framing SAM.gov does not publish. Where both publish a field, SAM.gov's value wins; USAspending fills the rest. Amounts are served exactly as published, with `amount_suspect` flagging the implausible ones. ## Identifiers - `key` (subgrant): the report UUID, SAM.gov's `subawardReportNumber` and USAspending's `subaward_sam_report_id`, lowercase. `GET /api/assistance/subgrants/{key}/`. - `award_key` (prime award): the canonical identifier of the prime assistance award, the same `assistance_award_unique_key` the [financial-assistance resources](../api-reference/assistance.md) take; `fain` is the prime's FAIN, and `prime_assistance_group` records which of the four resources held the prime when Tango processed the report (see [Keys](../api-reference/subgrants.md#keys)). - `prime_recipient_id`, `recipient_id`, `recipient_parent_id`: the entity ids (the `uuid` of `/api/entities/`) minted from the prime, subgrantee and subgrantee-parent UEIs; `null` when the report carries no UEI. - `place_of_performance_id`: the place record the subgrant's place of performance resolves to, in the financial-assistance place dimension. **Note**: The full set of fields is available via the `shape` query parameter. See [Response Shaping](../guides/patterns/response-shaping.md) for details. ## Update Frequency Subgrant reports are refreshed **daily** from USAspending's daily files and the SAM.gov assistance subaward feed, and reconciled against USAspending's full-year archives on each new pull. ## Fields | Field | Type | Description | Source | | ----- | ---- | ----------- | ------ | | `key` | UUID | The report UUID. | SAM.gov / USAspending | | `award_key` | String | Canonical identifier of the prime assistance award. | USAspending / Tango | | `fain` | String | Prime award FAIN. | SAM.gov / USAspending | | `assistance_listings` | String | The prime award's assistance listings (CFDA number and title) as reported; several are `;`-separated. | USAspending / SAM.gov | | `prime_assistance_group` | String | Which financial-assistance resource held the prime award when Tango processed the report: `grant`, `loan`, `direct_payment` or `other`; `null` when the prime was not in Tango. It can lag an award that has since changed assistance type. | Tango (derived) | | `prime_awardee_uei` | String | Prime recipient UEI. | SAM.gov / USAspending | | `prime_recipient_id` | UUID | The prime recipient's entity id. | Tango (derived) | | `recipient_uei` | String | Subgrantee UEI. | SAM.gov / USAspending | | `recipient_id` | UUID | The subgrantee's entity id. | Tango (derived) | | `recipient_parent_uei` | String | Subgrantee parent UEI. | SAM.gov / USAspending | | `recipient_parent_id` | UUID | The subgrantee parent's entity id. | Tango (derived) | | `place_of_performance_id` | UUID | The place-of-performance record. | Tango (derived) | | `pop_cd_original` | String | Place-of-performance congressional district as reported. | USAspending | | `pop_cd_current` | String | Place-of-performance congressional district under current boundaries. | USAspending | | `amount_suspect` | Boolean | The reported amount is not plausibly a subgrant; see below. | Tango (derived) | | `retired_at` | Timestamp | When the report stopped being published; `null` while live. | Tango (derived) | | `usaspending_permalink` | String | The prime award's page on USAspending. | USAspending | ### `amount_suspect` `true` when either the amount is at or above one billion dollars, or the amount's digit string, six digits or longer, is one string written twice (`25092509` for `2509`), a known serialization defect in the reporting system. The amount is served as published either way; this flag says whether to trust it. ### `retired_at` Set when USAspending published the report and its newest full-year archive no longer does, with no re-filing on SAM.gov since; or when a later archive pull no longer carries the report at all. The timestamp is when Tango first saw the report gone, and it stays put; a report that reappears has it cleared. A report only SAM.gov holds is never retired. Lists omit retired reports unless `include_retired=true`. ## Expansions (via `shape`) - `subgrant_details` – `description`, `type` (always `sub-grant`), `number`, `amount`, `action_date`, `fiscal_year` - `fsrs_details` – `last_modified_date` (timestamp of the report's last modification), `id` (the report UUID), `year`, `month` - `place_of_performance` – `city`, `state` (two-letter code), `zip`, `country_code`, from the place record - `highly_compensated_officers` – `name`, `amount`, always five entries; one the report leaves empty has `null` for both - `prime_recipient` – `uei`, `display_name`, from the entity record - `subgrant_recipient` – `uei`, `display_name`, `duns`, from the entity record; an unregistered subgrantee returns its `uei` with `display_name: null`, and `duns` is always `null` - `awarding_office` / `funding_office` – office fields, from the prime award ## Data Sources - **SAM.gov** – Assistance subaward reports: the report, the prime, the subgrantee and its parent, the officers. - **USAspending** – The same reports with the place of performance, the officers, the fiscal year, the prime's assistance listings and the permalink. - **Tango** – `award_key`, the entity and place ids, `amount_suspect`, `retired_at`, and the arbitration between the two feeds. ## Usage Notes - **Use `key` for subgrant lookups.** Use `award_key` or `fain` to link to the prime award; `prime_assistance_group` names its endpoint, and nearly all subgrants sit under grant awards. - **Scoped lists:** `/api/assistance/{grants,loans,direct_payments,other}/{key}/subgrants/` lists subgrants under a prime award on that endpoint (a retired key works; another endpoint's key returns an empty list); `/api/entities/{uei}/subgrants/` lists those where the entity is the subgrantee. - **Several reports can describe one subgrant.** A prime re-files a report when it amends or re-reports a subaward, so the same prime award, subaward number and subgrantee can appear under several keys with different action dates and amounts; summing `amount` across them overstates. --- --- description: "Field definitions for /api/vehicles/, Tango's solicitation-centric grouping of IDVs." updated: 2026-10-24 --- # Vehicles Data Dictionary This document describes the fields available in the Vehicles API endpoints (`/api/vehicles/`). For filtering, ordering, and pagination, see the [Vehicles API Reference](../api-reference/vehicles.md). ## Overview Vehicles provide a solicitation-centric grouping of multiple IDVs. Each vehicle represents a unique \(`solicitation_identifier`, agency identifier\) pair and can expand into the underlying IDVs via response shaping. >In federal data, *each IDV award is a vehicle*. >In practice, people often think of a "vehicle" as the *solicitation that produced many IDV awards* (one per awardee). We model that higher-level grouping explicitly. **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](../guides/patterns/response-shaping.md) for details. ## Update Frequency Vehicle data is refreshed periodically by the Tango ingest pipeline. ## Fields | Field | Type | Description | Source | | ------- | ------ | ------------- | -------- | | `uuid` | UUID | Stable identifier for the vehicle in Tango. Deterministic from `solicitation_identifier` + agency identifier derived from the IDV `key`. | Tango | | `solicitation_identifier` | String | Solicitation identifier shared by the underlying IDVs. | FPDS (via awards) | | `is_synthetic_solicitation` | Boolean | `true` for GWAC-orphan vehicles whose solicitation identifier was recovered via the `ACRO:` prefix convention. | Tango | | `agency_id` | String | Agency identifier derived from the IDV award `key` suffix (award-key convention). | Tango | | `program_acronym` | String | Program acronym (e.g., `ALLIANT`, `OASIS`) when present. | Tango | | `organization_id` | UUID | Best-effort mapping to a canonical Tango Organization, for consistent agency joins/filtering. | Tango (derived) | | `organization` | Object | Live awarding-org snapshot: `{organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name}`. Resolved at request time via the office cache. Select as a leaf token (`shape=...,organization`); not currently sub-selectable. | Tango | | `vehicle_type` | Object | Aggregated IDV type for the vehicle, derived from underlying IDVs. Returned as `{code, description}` (e.g., `{code: "A", description: "GWAC"}`). | FPDS (via awards) | | `who_can_use` | Object | Choice indicating which agencies may order against the vehicle. Returned as `{code, description}`. | FPDS (via awards) | | `type_of_idc` | Object | Aggregated IDC type for the vehicle. Returned as `{code, description}` (e.g., `{code: "A", description: "Indefinite Delivery / Requirements"}`). | FPDS (via awards) | | `contract_type` | Object | Aggregated contract type for the vehicle. Returned as `{code, description}` (e.g., `{code: "J", description: "Firm Fixed Price"}`). | FPDS (via awards) | | `description` | String | Longest common substring across the vehicle's IDV descriptions. | FPDS (via awards) | | `descriptions` | Array[String] | Set of distinct descriptions found across the underlying IDVs. | FPDS (via awards) | | `fiscal_year` | Integer | Representative fiscal year for the vehicle (derived from the underlying IDVs). | FPDS (via awards) | | `award_date` | Date | Earliest IDV award date associated with the vehicle. | FPDS (via awards) | | `latest_award_date` | Date | Most recent IDV award date associated with the vehicle. | Tango | | `last_date_to_order` | Date | Latest order-by date across the vehicle's IDVs. | FPDS (via awards) | | `idv_count` | Integer | Number of IDV awards in the vehicle (precomputed rollup). | Tango | | `holder_count` | Integer | Number of distinct companies holding at least one of the vehicle's contracts (IDVs). A company with several of the vehicle's contracts counts once, so this can be lower than `idv_count`. Added in API 5.8.0. | Tango | | `order_winner_count` | Integer | Number of distinct companies that have won at least one task order under the vehicle. Compare it with `holder_count` to see how many holders have won work so far. Added in API 5.8.0. | Tango | | `awardee_count` | Integer | **Deprecated** β€” same value as `order_winner_count`, kept for existing clients and removed in the next major API version. It counts task-order winners, not contract holders; use `holder_count` for those. | Tango | | `order_count` | Integer | Total number of child awards/orders under the vehicle's IDVs (precomputed rollup). | Tango | | `total_obligated` | Decimal | Sum of obligations across child awards/orders (precomputed rollup). | Tango | | `vehicle_obligations` | Decimal | Sum of obligations across child awards/orders under the vehicle's IDVs (computed at query time). | Tango | | `vehicle_contracts_value` | Decimal | Sum of total contract value across child awards/orders under the vehicle's IDVs (computed at query time). | Tango | | `solicitation_title` | String | Title of the solicitation from the latest SAM.gov notice (via linked Opportunity). | SAM.gov (via opportunities) | | `solicitation_description` | String | Description of the solicitation from the latest SAM.gov notice (via linked Opportunity). | SAM.gov (via opportunities) | | `solicitation_date` | Date | First notice date from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) | | `opportunity_id` | UUID | Foreign key to the linked SAM.gov Opportunity (if any). | Tango | | `naics_code` | Integer | NAICS code from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) | | `psc_code` | String | Product/Service Code from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) | | `set_aside` | String | Set-aside type from the linked SAM.gov Opportunity. | SAM.gov (via opportunities) | ### Legacy fields The following fields are kept on the API for backward compatibility β€” recomputed from the underlying IDVs at request time. They are **not** formally deprecated today (no `Deprecation` response header, no sunset date) because there are no first-class replacements yet for `agency_details.funding_office` or for the unique `competition_details` keys (`extent_competed`, `set_aside`, `solicitation_procedures`, `number_of_offers_received`). Where a replacement exists, it's listed below. | Field | Type | Notes / partial replacement | | ----- | ---- | --------------------------- | | `agency_details` | Object | Awarding side is covered by the live `organization` object. Funding side (`agency_details.funding_office`) has no replacement at the vehicle grain β€” aggregate from `/api/vehicles//orders/` (each order carries `funding_organization_id`) for funding analysis. | | `competition_details` | Object | Competition fields are also surfaced under the underlying IDVs (see `awardees(...)`). | | `opportunity` (expansion) | Object | Top-level `solicitation_*` fields and `opportunity_id` cover the common cases without a join. The full `opportunity(...)` expansion remains supported with the complete Opportunity field/expand surface (restored to pre-cutover parity). | ## Expansions (via `shape`) ### `awardees` Expands to the underlying IDVs that make up the vehicle. Each IDV in the response carries vehicle-specific rollups: `order_count`, `idv_obligations`, `idv_contracts_value`. Supports nested `orders(...)` to expand each IDV's task orders. ### `metrics` Bundles 12 computed metrics under a single nested object. Available fields: | Field | Type | Description | | ----- | ---- | ----------- | | `avg_offers_received` | Float | Average number of offers received across the vehicle's IDVs. | | `award_concentration_hhi` | Float | Herfindahl-Hirschman Index for award concentration across awardees. | | `order_concentration_hhi` | Float | HHI for task-order concentration across recipients. | | `competed_rate` | Float | Fraction of obligations that were competed. | | `using_agency_count` | Integer | Number of distinct agencies that have ordered against the vehicle. | | `avg_order_value` | Float | Average task-order obligated amount. | | `max_order_value` | Float | Largest single task-order obligated amount. | | `top_recipient_share` | Float | Share of obligations going to the largest single recipient. | | `recent_obligations_24mo` | Float | Sum of obligations in the trailing 24 months. | | `recent_orders_24mo` | Integer | Count of task orders in the trailing 24 months. | | `days_since_last_order` | Integer | Days since the most recent task order. | | `obligation_to_ceiling_ratio` | Float | Obligated-to-ceiling ratio (when ceiling is known). | Use `?shape=...,metrics(*)` to include all of them, or pick a subset (e.g. `metrics(competed_rate,top_recipient_share)`). ### `organization` The canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Both forms work and return the same payload: - `?shape=...,organization` β€” bare leaf - `?shape=...,organization(*)` β€” expand (also supports field selection, e.g. `organization(agency_name,office_name)`) Example: ```bash /api/vehicles//?shape=uuid,solicitation_identifier,organization(*),metrics(*),awardees(key,uuid,piid,recipient(display_name,uei)) ``` ## Sub-endpoints ### `/api/vehicles//awardees/` Returns the IDV awardees for the vehicle, with vehicle-specific rollups (`order_count`, `idv_obligations`, `idv_contracts_value`) appended. Supports the `awardees`/IDV shaping vocabulary. ### `/api/vehicles//orders/` Returns task orders (child contracts) under the vehicle's IDVs. Optimized for fast pagination over very large vehicles. Supports `?ordering=...` with `award_date` (default), `obligated`, or `total_contract_value`. Prefix with `-` for descending. ## Search - **Vehicle list search**: `GET /api/vehicles/?search=...` searches across vehicle metadata and aggregated award search terms via full-text search. - **Awardee-within-vehicle filtering**: `GET /api/vehicles//?shape=...,awardees(...)&search=...` filters the expanded awardees (the vehicle itself is not filtered on detail). ## Ordering The list endpoint accepts `?ordering=` with one of `vehicle_obligations`, `latest_award_date`, `total_obligated`, `award_date`, `last_date_to_order`, `fiscal_year`, `idv_count`, or `order_count`. `awardee_count` and `vehicle_contracts_value` are not orderable and return a 400. Prefix with `-` for descending; combine with commas for multi-field sort. See [Vehicles API Reference β€” Ordering](../api-reference/vehicles.md#ordering) for usage notes. --- --- description: "How to authenticate Tango API requests with an API key or OAuth2, and how to read the rate-limit and error responses that follow." tags: [auth, api, guide] updated: 2026-09-21 --- # Authentication The Tango API supports multiple authentication methods to suit different use cases and security requirements. ## Authentication Methods ### 1. API Keys (Recommended) API keys are the simplest and most secure method for server-to-server integration. #### Getting an API Key 1. Visit [Tango Web Interface](https://tango.dev) 2. Sign up for an account or log in 3. Navigate to your [account profile](https://tango.makegov.com/accounts/profile/) 4. Under **Create a new API key**, give the key a name (e.g., "Laptop") and create it 5. Copy the key and store it securely β€” new accounts start with no keys until you create one #### Using API Keys Include your API key in the `X-API-KEY` header with every request: ```bash curl -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/contracts/" ``` ```python import httpx headers = {'X-API-KEY': 'your-api-key-here'} response = httpx.get( 'https://tango.dev/api/contracts/', headers=headers ) ``` The Python example requires `httpx`: `python -m pip install httpx`. ```javascript const response = await fetch('https://tango.dev/api/contracts/', { headers: { 'X-API-KEY': 'your-api-key-here' } }); ``` ### 2. OAuth2 OAuth2 is recommended for web applications and user-specific integrations. #### OAuth2 Flow 1. **Register your application** in the [Tango web interface](https://tango.makegov.com/o/applications/) 2. **Get client credentials** (client ID and secret) 3. **Implement OAuth2 flow** in your application 4. **Use access tokens** for API requests #### Example OAuth2 Implementation Install the example's dependency first: `python -m pip install requests-oauthlib`. ```python import requests from requests_oauthlib import OAuth2Session # OAuth2 configuration client_id = 'your-client-id' client_secret = 'your-client-secret' authorization_base_url = 'https://tango.makegov.com/o/authorize/' token_url = 'https://tango.makegov.com/o/token/' # Create OAuth2 session oauth = OAuth2Session(client_id) # Get authorization URL authorization_url, state = oauth.authorization_url(authorization_base_url) # Redirect user to authorization_url print(f"Please go to {authorization_url} and authorize access") # After authorization, get the authorization response URL authorization_response = input('Enter the full callback URL: ') # Fetch the access token token = oauth.fetch_token( token_url, authorization_response=authorization_response, client_secret=client_secret ) # Use the token for API requests response = oauth.get('https://tango.dev/api/contracts/') ``` #### OAuth2 Endpoints | Endpoint | Path | Purpose | |----------|------|---------| | Authorization | `https://tango.makegov.com/o/authorize/` | Authorization Code flow start | | Token | `https://tango.makegov.com/o/token/` | Exchange code for access token; client credentials | | Refresh | `https://tango.makegov.com/o/token/` | Refresh an access token (same path; use `grant_type=refresh_token`) | Supported grant types: `authorization_code`, `client_credentials`, `refresh_token`. #### OAuth2 Scopes Available scopes for OAuth2 applications: - `read` - Read access to all data ## Monitoring Usage ### Response Headers Check these headers to monitor your API usage: ```bash curl -I -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/contracts/" ``` Response headers: ```plaintext X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 45 X-Execution-Time: 0.045s ``` ### Rate Limit Headers - `X-RateLimit-Limit`: Total requests allowed for the most restrictive window - `X-RateLimit-Remaining`: Requests remaining in the most restrictive window - `X-RateLimit-Reset`: **Seconds until reset** for the most restrictive window - `X-Execution-Time`: Request execution time Some endpoints carry their own premium query budget in place of these limits, with its own headers (`X-RateLimit-Premium-Limit`, `X-RateLimit-Premium-Remaining`, `X-RateLimit-Premium-Reset`). Premium headers appear only on responses from endpoints with a premium budget. For the full list of per-window headers (daily/burst), premium headers, and practical retry guidance, see the [Rate limits guide](../guides/patterns/rate-limits.md). ## Error Handling ### Authentication Errors #### 401 Unauthorized ```json { "detail": "Authentication credentials were not provided." } ``` **Causes:** - Missing API key - Invalid API key - Expired API key - Inactive API key **Solutions:** - Check that you're including the `X-API-KEY` header - Verify your API key is correct - Ensure your API key is active - Generate a new API key if needed #### 403 Forbidden Tier-gated endpoints return a structured `tier_required` error: ```json { "error": "This endpoint requires Small tier or above. Your current tier is Free.", "code": "tier_required", "required_tier": "Small", "current_tier": "Free", "upgrade_url": "https://docs.makegov.com/getting-started/pricing/" } ``` **Causes:** - The endpoint or filter requires a higher subscription plan than your current one **Solutions:** - Use `required_tier`, `current_tier`, and `upgrade_url` to surface an upgrade prompt programmatically - See [Plans & pricing](pricing.md) for what each plan includes, or upgrade from the [pricing page](https://tango.dev/subscriptions/pricing/) ### Rate Limit Errors #### 429 Too Many Requests ```json { "detail": "Rate limit exceeded for burst. Please try again in 45 seconds.", "wait_in_seconds": 45 } ``` **Solutions:** - Wait for the rate limit window to reset - Implement exponential backoff in your application - Consider upgrading your account for higher limits - Optimize your requests to reduce frequency See the [Rate limits guide](../guides/patterns/rate-limits.md) for header semantics, examples (curl/Python/JS), and recommended client behavior. --- --- description: "What each Tango plan includes, which fields and endpoints are gated by tier, and how rate limits and webhook subscription caps scale by plan." tags: [billing, api, reference] updated: 2026-11-10 --- # Plans & Data Access All Tango API plans include full access to raw federal procurement data from FPDS, SAM.gov, USAspending, Grants.gov, and agency feeds. Paid plans unlock Tango-computed enrichments and higher rate limits. For current pricing, see the [pricing page](https://tango.dev/subscriptions/pricing/). !!! note "Tier shorthand" Plans available to new customers are named **Free, Small, Medium, Large, and Enterprise**. Where these docs (and API error messages) say **Pro+**, that means Small and above β€” and the retired Micro plan, which still counts as Pro for the accounts still on it. **Business+** means Medium and above. ## What's included in every plan Every plan -- including Free -- provides complete access to: - **Contracts, IDVs, OTAs, OTIDVs** -- all FPDS award data with full transaction history - **Vehicles** -- solicitation-centric groupings of IDVs, with metrics, awardees, and task orders - **Subawards** -- USAspending/FSRS subcontract data - **Entities** -- SAM.gov vendor/recipient records (UEI, addresses, business types, NAICS codes, ownership) - **Opportunities & Notices** -- SAM.gov solicitations with attachments, contacts, and history - **Grants** -- Grants.gov opportunities - **Financial assistance** -- Grant, loan, direct-payment and other assistance awards from USAspending, with full transaction history - **Forecasts** -- Agency procurement forecasts - **Protests** -- GAO and SBA OHA bid protest cases with dockets and decisions - **Contract appeals** -- CBCA and ASBCA Contract Disputes Act decisions, including full-text search over the decision text. Only the `decision_text` field itself is gated. - **Federal Register** -- Rules, proposed rules, notices and presidential documents since 1994, including each document's full text - **Award announcements** -- The Department of War's daily contracts release and MakeGov-generated announcements of new civilian IDVs and OTAs - **IT Dashboard** -- Federal IT investment data from itdashboard.gov, including all expansion data (CIO evaluations, contracts, projects, performance metrics, funding sources). Only the full `business_case_html` blob is gated. - **Agencies, Departments, Offices, Organizations** -- Full government organization hierarchy - **Response shaping** -- Request only the fields you need via `?shape=` - **Full-text search** -- Rich filtering across most endpoints (some advanced search filters require a paid plan) ## What paid plans add Paid plans (Small and above) unlock **Tango-computed enrichments** -- fields that Tango derives, resolves, or extracts from raw data. These are not available from the underlying public data sources directly. ### Enriched data fields (Small and above) | Resource | Gated fields | What they provide | |----------|-------------|-------------------| | **Entities** | `past_performance(*)` | Award history aggregated from FPDS -- total contracts, dollar values, agency breakdown | | **Entities** | `relationships(*)` | Corporate ownership and succession resolved from the SAM.gov entity graph, plus prime/subcontractor ties derived from reported subaward data | | **Opportunities** | `attachments(extracted_text)` | Full text extracted (OCR) from solicitation attachments | | **Notices** | `attachments(extracted_text)` | Full text extracted (OCR) from notice attachments | | **Protests** | `resolved_protester(*)` | Protester name resolved to a SAM.gov entity via Bayesian matching | | **Protests** | `resolved_agency(*)` | Agency name resolved to a Tango organization record via Bayesian matching | | **IT Dashboard** | `business_case_html` | Full HTML of the investment's business case page (Business+ plans only β€” Medium and above) | ### Contract appeal decision text (Enterprise) `decision_text` on [`/api/contract_appeals/`](../api-reference/contract-appeals.md) -- the extracted body of a CBCA or ASBCA decision -- requires an Enterprise plan. Everything else about the resource, including the full-text search that runs over that text, is available on every plan including Free: a search response returns matching decisions and no fragment of the body, so there is nothing to gate. Requesting `decision_text` on a lower plan returns 200 with the field omitted and a `meta.upgrade_hints` entry, exactly as described below. ### GSA eBuy requests (Medium and above, by arrangement) [`/api/ebuy/requests/`](../api-reference/ebuy.md) serves the GSA eBuy requests posted under your own Schedule contracts. It requires a **Medium plan or above**, **and** a contract link that MakeGov sets up for your account β€” [reach out](mailto:hello@makegov.com) to get started. Free and Small plans receive HTTP 403 with `"code": "tier_required"`; see [Checking your access](../api-reference/ebuy.md#checking-your-access). ### CALC labor rates (Small and above) The `/api/lcats/` endpoint provides GSA CALC labor category rate data. This entire endpoint requires a paid plan. ### Identifier validation (Small and above) The [`POST /api/validate/`](../api-reference/validate.md) endpoint validates the format of a PIID, solicitation number, or UEI. Available on Pro+ plans (Small and above); Free-tier callers receive HTTP 403. ### How field gating works When you request a gated field on a Free plan, the API: 1. Returns a `200 OK` response (not an error) 2. Omits the gated field from the response 3. Includes a `meta.upgrade_hints` object listing which fields were omitted ```json { "results": [ { "uei": "ABC123", "display_name": "Example Corp" } ], "meta": { "upgrade_hints": { "message": "Some requested fields were omitted because they require a higher tier subscription.", "fields": [ {"field": "past_performance", "required_tier": "Small"} ], "upgrade_url": "https://docs.makegov.com/getting-started/pricing/" } } } ``` You can always check which fields are available by inspecting the `meta.upgrade_hints` in your response. ## Rate limits by plan Each plan has both a **daily** quota (resets at UTC midnight) and a **burst** rate (per-minute). The most-restrictive window is what limits a given burst of activity. Headers (`X-RateLimit-Daily-*`, `X-RateLimit-Burst-*`) and retry guidance are documented in [Rate limits](../guides/patterns/rate-limits.md). | Plan | Daily | Burst | |------|------:|------:| | **Free** | 100 / day | 25 / min | | **Small** | 1,500 / day | 100 / min | | **Medium** | 7,500 / day | 100 / min | | **Large** | 25,000 / day | 100 / min | | **Enterprise** | custom | custom | For Enterprise limits, [contact sales](mailto:sales@makegov.com). ### Premium query budgets Some endpoint families carry their own premium query budget. On those endpoints it replaces your account-wide daily and burst limits rather than adding to them, and your own figures are on your account profile. See the [Rate limits guide](../guides/patterns/rate-limits.md) for details and the [CALC labor rates API reference](../api-reference/lcats.md) for an example of a premium-limited endpoint family. ## Webhook subscriptions by plan | Plan | Webhook subscriptions | Custom cron | |------|-------------------|-------------| | **Free** | 1 | -- | | **Small** | 5 | Yes | | **Medium** | 10 | Yes | | **Large** | 25 | Yes | | **Enterprise** | custom | Yes | Webhook subscriptions monitor resources by query filters (agency, NAICS, search terms, etc.) and POST `alerts.*.match` events to your endpoint. See the [Webhooks guide](../webhooks/index.md) for details. ## Teams (Medium and above) On a Medium plan or above, you can create a team: colleagues working under your plan, sharing its daily, burst, and premium query limits and its alert limit. A team has no member limit, so adding people divides those limits. Each member keeps their own API keys. See [Teams](teams.md). ## Upgrading your plan You can upgrade or downgrade at any time from the [pricing page](https://tango.dev/subscriptions/pricing/). Changes take effect immediately with prorated billing. Annual plans save 20%. For Enterprise plans, [contact sales](mailto:sales@makegov.com). --- --- description: "A five-minute walkthrough of the first authenticated Tango API call and response, in cURL, Python, and JavaScript." tags: [api, guide] updated: 2026-09-21 --- # Quick Start Guide Get up and running with the Tango API in 5 minutes or less. ## Prerequisites - Basic knowledge of HTTP and JSON - A web browser or API client (like Postman, Insomnia, or curl) - Optional for the Python examples: Python 3.9 or later and `requests` (`python -m pip install requests`) - Optional for the JavaScript examples: Node.js 18 or later, which includes `fetch` ## Step 1: Get Your API Key 1. Visit the [Tango web interface](https://tango.dev) and sign up or log in. 2. Open your [account profile](https://tango.makegov.com/accounts/profile/). 3. Under **Create a new API key**, enter a name and create the key. 4. Copy the key and store it securely; the full value is shown only when you create it. > **Note**: The API requires authentication for all access. Anonymous access is not supported. You'll need an API key for any usage. ## Step 2: Make Your First API Call Pull the five most recently awarded federal contracts: === "curl" ```bash curl -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/contracts/?limit=5&ordering=-award_date" ``` === "Python" ```python import requests headers = {"X-API-KEY": "your-api-key-here"} response = requests.get( "https://tango.dev/api/contracts/", params={"limit": 5, "ordering": "-award_date"}, headers=headers, ) data = response.json() for contract in data["results"]: print(contract["piid"], contract["recipient"]["display_name"], contract["obligated"]) ``` === "Node" ```javascript const params = new URLSearchParams({ limit: "5", ordering: "-award_date" }); const response = await fetch(`https://tango.dev/api/contracts/?${params}`, { headers: { "X-API-KEY": "your-api-key-here" }, }); const data = await response.json(); for (const contract of data.results) { console.log(contract.piid, contract.recipient.display_name, contract.obligated); } ``` ## Step 3: Explore the Response You'll get a paginated response shaped like this: ```json { "count": 9824315, "next": "https://tango.dev/api/contracts/?limit=5&ordering=-award_date&cursor=cD0yMDI2LTA1LTEx", "previous": null, "results": [ { "key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-", "piid": "47QSWA24P0BWF", "recipient": { "display_name": "ACME Corporation", "uei": "ZMXAHH8M8VL8" }, "award_date": "2026-05-11", "obligated": 1500000.00, "description": "IT Services Contract" } ] } ``` ## Step 4: Try a More Complex Query Now let's find active opportunities in a specific industry and agency: === "curl" ```bash curl -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/opportunities/?naics=541512&active=true&agency=DOD&ordering=response_deadline&limit=5" ``` === "Python" ```python import requests headers = {"X-API-KEY": "your-api-key-here"} response = requests.get( "https://tango.dev/api/opportunities/", params={ "naics": "541512", "active": "true", "agency": "DOD", "ordering": "response_deadline", "limit": 5, }, headers=headers, ) for opp in response.json()["results"]: print(opp["response_deadline"], opp["opportunity_id"], opp["title"]) ``` === "Node" ```javascript const params = new URLSearchParams({ naics: "541512", active: "true", agency: "DOD", ordering: "response_deadline", limit: "5", }); const response = await fetch(`https://tango.dev/api/opportunities/?${params}`, { headers: { "X-API-KEY": "your-api-key-here" }, }); for (const opp of (await response.json()).results) { console.log(opp.response_deadline, opp.opportunity_id, opp.title); } ``` This query: - Filters by NAICS `541512` (Computer Systems Design Services) - Restricts to DOD opportunities - Returns only currently-biddable opportunities (`active=true`) - Orders by response deadline (soonest first) - Limits to 5 results For more on multi-value filters, agency resolution, and webhook subscriptions for new opportunities, see the [Search opportunities by NAICS](../guides/how-to/search-opportunities-naics.md) guide. ## Step 5: Understand the Response Format Most list endpoints return paginated responses. The `count` may be exact or approximate depending on the endpoint (see [Result counts](../guides/patterns/result-counts.md)) β€” check the `X-Results-CountType` response header to know which: ```json { "count": 1250, "next": "https://tango.dev/api/opportunities/?...&page=2", "previous": null, "results": [ { "opportunity_id": "75D30126R00012", "title": "Cyber Workforce Development Services", "naics_code": 541512, "psc_code": "D316", "set_aside": "SBA", "response_deadline": "2026-06-14T17:00:00Z", "first_notice_date": "2026-05-08T15:32:11Z", "active": true, "sam_url": "https://sam.gov/opp/75D30126R00012/view", "office": { "office_code": "FA7014", "office_name": "FA7014 AFDW PK", "agency_code": "5700", "agency_name": "Department of the Air Force" }, "meta": { "notices_count": 5, "notice_type": {"code": "o", "type": "Solicitation"} } } ] } ``` ## Step 6: Use Response Shaping to Customize Your Data Response shaping lets you request only the specific fields you need, reducing data transfer and speeding up your application. ### Basic Shaping Example Instead of receiving all fields, request just what you need using the `shape` parameter: ```bash curl -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/contracts/?shape=key,piid,award_date,recipient(display_name,uei)&limit=5" ``` This request returns only: - Contract key - PIID (contract identifier) - Award date - Recipient name and UEI (nested) ### Why Use Response Shaping? - **Faster responses**: Less data to transfer means quicker API calls - **Reduced bandwidth**: Only get the fields you actually need - **Cleaner code**: Shape the response to match your application's data model - **Flexible expansions**: Include related data (offices, transactions, recipients) without separate API calls ### Response Example ```json { "count": 1250, "results": [ { "key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-", "piid": "47QSWA24P0BWF", "award_date": "2024-01-15", "recipient": { "display_name": "ACME Corporation", "uei": "ZMXAHH8M8VL8" } } ] } ``` Learn more about advanced features like flattening, aliasing, and multiple expansions in the [Response Shaping Guide](../guides/patterns/response-shaping.md). ## Common Issues ### Rate Limit Exceeded If you see a `429 Too Many Requests` error, you've hit a rate limit. Check `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds until reset), and follow the retry guidance in the [Rate limits guide](../guides/patterns/rate-limits.md). ### Authentication Error If you get a `401 Unauthorized` error, check that: - Your API key is correct - You're including the `X-API-KEY` header - Your API key is active ### Invalid Request If you get a `400 Bad Request` error, check that: - Your URL parameters are properly formatted - Required parameters are included - Date formats are YYYY-MM-DD ## What to do next You are done with the quick start when the contract request returns HTTP 200 and a `results` array. - Use the [API reference](../api-reference/index.md) when you know which resource you need and want its filters, ordering, and shapes. - Choose the [Python](../sdks/python/index.md) or [Node](../sdks/node/index.md) SDK when you want typed methods and pagination helpers. - Read [Plans & Data Access](pricing.md) before depending on an enrichment or a high request volume. - Use a [task-oriented guide](../guides/index.md) for opportunity search, agency resolution, migration, webhooks, and other end-to-end jobs. --- --- description: "How a Tango team shares one plan and its limits across colleagues: who can create one, roles, invitations, billing, alerts, and leaving." tags: [billing, guide] updated: 2026-11-13 --- # Teams A team is a group of colleagues working under one Tango plan. Everyone on the team gets the team's plan, and the team's daily, burst, and premium query limits are **pooled**: one shared allowance that every member draws from. Each person keeps their own account, API keys, and usage. !!! note "Availability" Creating a team takes a **Medium plan or above** on your own account. There's no limit on how many people a team can have. Some teams run on a plan MakeGov sets by agreement, such as an invoiced Enterprise plan. MakeGov sets those teams up and manages their plan; email [support@makegov.com](mailto:support@makegov.com) to start one. You manage your team from the **Team** page in your account: [tango.makegov.com/account/team/](https://tango.makegov.com/account/team/). ## What a team shares | Shared across the team | Kept per person | | --- | --- | | The plan: its limits, features, and tier-gated fields | Your account and sign-in | | Daily and burst (per-minute) [rate limits](../guides/patterns/rate-limits.md) | Your API keys | | [Premium query budgets](../guides/patterns/rate-limits.md#premium-query-limits-select-endpoints) | Your usage, which owners and admins can see | | The [alert](../webhooks/index.md) limit | Your alerts and webhook endpoints | | eBuy [contract links](../api-reference/ebuy.md#what-you-can-see) made to the team | eBuy contract links made to you | While you're on a team, **the team's plan is your plan**. It replaces your own plan rather than adding to it. **Your company is the team's name.** While you're on a team, your profile shows the team's name as your company, and the Company field can't be edited. Your own company comes back when you leave. ## How limits count on a team - **Adding people divides the limits.** A team has no member limit, but its plan's limits stay the same however many people share them, so each new member draws from the same pool. - **One pool.** Every request a member makes, with any of their API keys or OAuth2 tokens, counts against the team's daily and burst limits. A request to an endpoint with a [premium query budget](../guides/patterns/rate-limits.md#premium-query-limits-select-endpoints) counts against the team's budget for that endpoint family instead. - **Headers report the pool.** The `X-RateLimit-*` headers on your responses show the team's remaining allowance, not yours alone, so a teammate's traffic lowers what you see. - **A 429 says it's shared.** When a pooled limit runs out, the 429's `detail` ends with "This limit is shared by everyone on your team;" followed by a link to your Team page, which shows who to contact. - **Alerts count team-wide.** The team's [alert limit](pricing.md#webhook-subscriptions-by-plan) counts every member's alerts together, paused ones included. Alerts and webhook endpoints still belong to the person who created them. - **Owners and admins see usage per person.** The Team page shows each member's requests for today and the last 30 days. ## Creating a team 1. Make sure your own account is on Medium or above, and that you're not already on a team. 2. Open the [Team page](https://tango.makegov.com/account/team/) and create a team. Team names are unique across Tango, ignoring case, and can be up to 200 characters. 3. Invite your colleagues. You become the team's **owner** and its **billing owner**: the team's plan follows yours. See [Billing](#billing). ## Roles and permissions A team has three roles: **owner**, **admin**, and **member**. | Action | Owner | Admin | Member | | --- | :---: | :---: | :---: | | Use the team's plan and limits | βœ“ | βœ“ | βœ“ | | Invite members | βœ“ | βœ“ | β€” | | Invite admins | βœ“ | β€” | β€” | | Resend or withdraw any pending invitation | βœ“ | βœ“ | β€” | | Remove a member | βœ“ | βœ“ | β€” | | Remove an admin or an owner | βœ“ | β€” | β€” | | Promote a member to admin | βœ“ | βœ“ | β€” | | Make someone an owner, or change an admin's or owner's role | βœ“ | β€” | β€” | | Rename the team | βœ“ | β€” | β€” | | See each member's usage | βœ“ | βœ“ | β€” | | Leave the team | βœ“ | βœ“ | βœ“ | - **Nobody is invited as an owner.** Invite them as an admin or member, then make them an owner once they've joined. - **Handing over billing** is the billing owner's alone. See [Billing](#billing). - **A team always keeps an owner and a billing owner.** The billing owner can't leave, be removed, or stop being an owner until they hand billing to another owner. The last owner can't leave or be demoted until they make someone else an owner. ## Inviting people Owners and admins invite people by email address from the Team page. - **An invitation expires 7 days after it was last sent.** - **Resend** sends a fresh link, which replaces the old one, and restarts the 7 days. You can resend once every 10 minutes, and an invitation can go out 4 times in all. - **Withdraw** an invitation to make its link stop working. - **Limits:** a team can have 20 pending invitations at once, and can send 50 invitation emails in 24 hours; one person can send 100 in 24 hours. ### Accepting an invitation To accept, you need a Tango account where the **invited email address is verified**. - **No account yet?** The invitation link offers to create one. Sign up with the invited address. - **Signed in with a different address?** Sign out and continue with the invited address, or ask the person who invited you to invite the address you use. - **Address on your account but not verified?** Sign out, then sign in with a code sent to the invited address. That verifies it, and you can accept from there. Pending invitations also appear on your account pages once the invited address is verified on your account, so you can accept without the link. You can **decline** from the invitation link, signed in or not. The person who invited you is emailed; if they no longer run the team, its owners are. ### One team per person You can be on one team at a time. If you're already on a team, leave it before you accept another invitation; the invitation stays open until it expires. Joining or creating a team withdraws any other invitations open to you. ## Billing **A self-serve team's plan follows its billing owner's own plan.** If the billing owner is on Medium, the team is on Medium, and when they change plans, the team follows. Members other than the billing owner aren't charged for the team: their Billing page says the team covers them and names who manages the plan. **Handing over billing.** The billing owner can hand billing to another owner, whose own account must be active and on Medium or above. The team's plan then follows the new billing owner's plan. **If the billing owner drops below Medium**, including when a payment fails and their subscription goes past due, or their account is deactivated, the team is **paused** right away: - Every member is back on their own plan and limits, and nothing is pooled. - The team can't send invitations or add anyone. - Every member is emailed, with who to contact. The team resumes on its own once the billing owner is back on Medium or above, or once billing passes to an owner who is. **Teams on a plan MakeGov sets** don't follow anyone's plan. To change the plan or who's billed, email [support@makegov.com](mailto:support@makegov.com). ### Who to contact | About | Contact | | --- | --- | | The team's plan | The billing owner, or [support@makegov.com](mailto:support@makegov.com) for a plan MakeGov sets | | Anything else about the team | An owner | | Closing the team | [support@makegov.com](mailto:support@makegov.com) | The Team page shows each member's role and who the billing owner is. ## Leaving a team Leave from the Team page. If you're the billing owner or the last owner, hand those over first (see [Roles and permissions](#roles-and-permissions)). When you leave, or an owner or admin removes you: - Your own plan and limits apply to you again, starting immediately. - Your API keys keep working, on your own limits. - Your alerts and webhook endpoints stay yours. - Your profile shows your own company again. Someone who's removed gets an email saying so. ## What isn't self-serve yet - **Closing a team.** Email [support@makegov.com](mailto:support@makegov.com). If you're the only one left on the team, that's the only way out. - **Being on more than one team** at a time. --- --- description: "A guided tour of the beta Budget API β€” federal account lifecycle data, recipient and quarterly drill-downs, and organization-level rollups." tags: [budget, api, guide] updated: 2026-10-09 --- # Explore federal budget data !!! warning "Beta β€” surface may change" The `/api/budget/...` endpoints and the budget-related shape leaves on `/api/organizations/` and `/api/entities/` are **beta**. The data is real and refreshed on the normal cadence, but field names, shape leaves, default fields, filter names, and URL paths may still change based on early-consumer feedback. Pin a specific request shape (`?shape=...`) in production code so a default-shape change can't move under you, and watch the [changelog](../../CHANGELOG.md) for the move-to-stable announcement. If you build something on this and a change would hurt, [open an issue](https://github.com/makegov/tango-public/issues) β€” we'd rather learn about it before locking the shape down. The `/api/budget/...` surface exposes federal-account budget data β€” what Congress requested, what it enacted, what got apportioned to spend, what's been obligated, and what's actually been paid out. This guide walks you through the questions consumers actually ask of this data, with copy-paste requests for each. If you've worked with USAspending's File A (account-level) or OMB's MAX feeds before, this is the same kind of data β€” pre-joined to FPDS contract activity, with pre-computed ratios and trends so you don't have to derive them yourself. ## What's in here | Resource | What it answers | | --- | --- | | `GET /api/budget/accounts/` | One row per (federal account Γ— fiscal year). The full lifecycle (requested β†’ enacted β†’ apportioned β†’ obligated β†’ outlayed), contract vs assistance split, year-over-year + 5-year trends, next-year request signal. | | `GET /api/budget/accounts/{pk}/recipients/` | Who actually got paid out of a given account β€” funding office Γ— recipient Γ— PIIDs, hydrated with the matching contract records. | | `GET /api/budget/accounts/{pk}/quarters/` | Treasury Account Symbol (TAS)-grain quarterly flow β€” SF-133 obligations and outlays per quarter. FY21+. | | `?shape=*,appendix(*)` on account detail | President's Budget Appendix object-class breakdown β€” what kinds of spending Congress was asked to authorize (personnel, contractual services, grants, etc.). | | `?shape=*,narratives(*)` on account detail | Appendix narrative + appropriations text for the account. | | `?shape=budget_appropriation(*),budget_spending(*)` on `/api/organizations/{key}/` | Rolls up budget data to an org. Departments get their appropriation; offices get their funding-office spending across the org's subtree. | | `GET /api/entities/{uei}/budget-flows/` | Which federal accounts paid a given vendor β€” the inverse of the recipients drill-down. | Coverage windows differ across these surfaces (and across years for individual fields) because the underlying source documents do β€” Appendix runs FY08–FY27, the lifecycle rollup runs FY17–FY26, and SF-133 quarters begin in FY21. Each surface returns an empty list or `null` for FYs it can't cover. ## Quick start All requests need an `X-API-KEY` header. Set it once: === "curl" ```bash export TANGO_API_KEY="your-api-key-here" ``` === "Python" ```python import os import requests HEADERS = {"X-API-KEY": os.environ["TANGO_API_KEY"]} BASE = "https://tango.dev/api" ``` The 20 biggest accounts of the most recent fiscal year, by enacted budget authority: === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/budget/accounts/?limit=20" ``` === "Python" ```python resp = requests.get(f"{BASE}/budget/accounts/", params={"limit": 20}, headers=HEADERS) for a in resp.json()["results"]: print(a["federal_account_symbol"], a["account_title"], a["enacted_ba"]) ``` The default sort is `-fiscal_year, -enacted_ba`, so without filters or ordering you land on the largest accounts of the current year. Pass any of the filters in the next section to narrow. ## Find accounts ### By identity `federal_account_symbol` is the canonical key (`{agency_cgac}-{account_number}` β€” e.g. `075-0512` for HHS's NIH research account). It's exact-match by default; `__in` accepts a comma-separated list. ```text ?federal_account_symbol=075-0512&fiscal_year=2024 ?federal_account_symbol__in=075-0512,075-0540&fiscal_year=2024 ``` ### By agency ```text ?agency_code=075 # HHS, all years ?agency_code=075&fiscal_year__gte=2022 # HHS, recent years ?bureau_name__icontains=indian # any bureau with "indian" in the name ``` `agency_code` is the 3-character CGAC. `bureau_name` is free-text from the source β€” use `icontains` for fuzzy matches. ### By taxonomy ```text ?bea_category=Discretionary ?on_off_budget=On-budget ?subfunction_code=051 ?account_category=budgetary ``` `bea_category` is the budget enforcement category (`Discretionary`, `Mandatory`, or `Net interest`), and `on_off_budget` is `On-budget` or `Off-budget`. Both are exact, case-sensitive matches. `subfunction_code` is the OMB budget subfunction (e.g. `051` = national defense, `551` = health care services). `account_category` is `budgetary`, `credit_financing`, `request_only` or `proposed`; see [Summing accounts](#summing-accounts) for why it matters. ### Full-text search ```text ?search=acquisition+services+fund ?search=cybersecurity ``` Searches across `account_title`, `agency_name`, and `bureau_name`. ### By dollar threshold Every dollar field supports `__gte` / `__lte`: ```text ?enacted_ba__gte=1000000000&fiscal_year=2024 # accounts β‰₯ $1B enacted in FY24 ?contract_obligated__gte=500000000 # β‰₯ $500M in contract obligations ``` ## Spot pipeline anomalies Three ratio-based questions surface anomalies in the appropriation pipeline. ### Where did Congress give more than the President requested? ```text ?shape=federal_account_symbol,account_title,requested_ba,enacted_ba,enacted_to_requested_pct_capped&fiscal_year=2025&enacted_ba__gte=1000000000 ``` `enacted_to_requested_pct` is the ratio of enacted BA to the President's request. Values above 1.0 mean Congress added money beyond the ask; values below mean it cut. It is not a query filter (an unknown filter returns `400`), so request it in the shape and filter the results on your side, for example keeping rows at 1.1 or above. The `_capped` variants cap extreme values (typically at 5.0) to keep them sortable and chart-friendly, and a matching `_capped_flag` boolean tells you whether the cap was applied to that row. ### Where's apportionment lagging vs enacted? ```text ?apportioned_to_enacted_pct_capped__lte=0.5&fiscal_year=2024 ``` A low apportioned-to-enacted ratio mid-year usually means OMB has been slow to release funds β€” a strong leading indicator for spending pushes later in the year. ### Where's the obligation pipeline backed up? ```text ?obligated_to_apportioned_pct_capped__lte=0.4&fiscal_year=2024&ba_growth_next_year_pct__gte=0.0 ``` Apportioned money that hasn't been obligated mid-year is contract-pipeline pressure. Combine with `ba_growth_next_year_pct__gte=0.0` to find accounts whose next-year request is *also* trending up β€” those are the ones the agency is likely re-justifying. ## Forward-look: next year's request Every account row carries `next_year_requested_ba`, `ba_growth_next_year`, and `ba_growth_next_year_pct` β€” derived from the President's most recent Budget submission against the current enacted level. ```text ?ba_growth_next_year_pct__gte=0.5&contract_share_of_obligated_capped__gte=0.5 ``` Accounts whose next-year request is β‰₯ 50% higher than current enacted, *and* whose obligations historically run β‰₯ 50% through contracts. Useful for finding "contract-heavy growth accounts" β€” the accounts most likely to drive new contract opportunities in the coming year. ## Look up trends The `BUDGET_ACCOUNT_TRENDS_FIELDS` cluster is opt-in β€” pass it explicitly in `?shape=` to get year-over-year and 5-year trend signal: ```text ?shape=federal_account_symbol,account_title,enacted_ba,enacted_ba_yoy_pct,enacted_ba_5yr_cagr,contract_obligated_5yr_cagr&agency_code=097&fiscal_year=2024 ``` | Field | What it means | | --- | --- | | `enacted_ba_yoy_pct` | Year-over-year change in enacted BA, vs the prior FY. | | `obligated_yoy_pct` | Year-over-year change in total obligations. | | `contract_obligated_yoy_pct` | Year-over-year change in *contract-side* obligations. | | `enacted_ba_5yr_cagr` | 5-year compound annual growth rate of enacted BA. | | `contract_obligated_5yr_cagr` | 5-year CAGR of contract obligations. | ## Pull the account detail ```text GET /api/budget/accounts/{pk}/ ``` Returns a single account row with the default shape. To pull everything, pass `?shape=*`: ```text GET /api/budget/accounts/{pk}/?shape=* ``` ### Add the Appendix breakdown ```text GET /api/budget/accounts/{pk}/?shape=*,appendix(*) ``` The `appendix` leaf returns the President's Budget Appendix object-class breakdown β€” the 16 OMB request buckets (personnel comp, travel, contractual services, grants, etc.) plus the appendix granule ID and PDF URL. `appendix` is `null` for accounts with no object-class detail in the Appendix β€” typically large mandatory programs (e.g. Medicaid) whose breakdown isn't published. ### Add the narrative text ```text GET /api/budget/accounts/{pk}/?shape=*,narratives(*) ``` `narratives` is a list (some accounts have multiple narrative entries per year, split by subaccount) containing the Appendix narrative and appropriations language. Text fields can be a few KB each β€” they're a separate leaf from `appendix(*)` so they only load when asked for. ## Drill down to recipients ```text GET /api/budget/accounts/{pk}/recipients/ GET /api/budget/accounts/{pk}/recipients/?funding_organization_id={org_uuid} ``` One row per (funding office Γ— recipient Γ— account-year) on the contract side. Each row is hydrated with: - `funding_office` β€” full Department / Agency / Office hierarchy for the funding org. - `recipient` β€” UEI, legal name, DBA name. Resolvable via `/api/entities/{uei}/`. - `contracts` β€” minimal Contract shape (`key`, `piid`, `naics`, `psc`, `obligated`, `award_date`) for every contract under this (account, funding office, recipient) tuple. Use the `key` to follow back to the full Contract record. Sorted by `contract_obligated` desc β€” the largest recipients first. Standard `count / next / previous / results` pagination. ## Pull quarterly cash flow ```text GET /api/budget/accounts/{pk}/quarters/ GET /api/budget/accounts/{pk}/quarters/?tas=075-2024-2024-0512 ``` One row per (Treasury Account Symbol Γ— quarter Γ— period type) for this account-year. A federal account typically rolls up several TAS (different appropriation-year vintages), so the response is a list. | Field | Meaning | | --- | --- | | `tas` | Treasury Account Symbol β€” full TAS code including appropriation year. | | `quarter` | `1` through `4`. | | `period` | `quarterly` or `cumulative` β€” both are returned for each quarter. | | `obligated_quarterly`, `outlayed_quarterly` | Flow during the quarter. | | `obligated_cumulative`, `outlayed_cumulative` | Running total through end of the quarter. | | `quarterly_source` | Provenance flag β€” which SF-133 snapshot the row came from. | Coverage is FY21+. Earlier years return an empty page; use the account detail's lifecycle fields for FY17–FY20. ## Roll budget data up to an organization The Organization detail endpoint exposes budget rollups as two shape leaves. Use them when you want a budget view keyed by agency / office rather than by federal account. ```text GET /api/organizations/{key}/?shape=name,budget_appropriation(*),budget_spending(*) ``` ### `budget_appropriation(*)` The dept-level appropriation rollup β€” sums every federal account whose `agency_code` matches the org's CGAC. The payload carries a `scope` field so consumers can tell whose number they're looking at: | `scope` | When | What you're seeing | | --- | --- | --- | | `"self"` | Org is L1 (a department) | The dept's own appropriation totals. | | `"department"` | Org is L2+ (an agency or office inside a department) | The **parent dept's** totals (sub-orgs inherit the dept's CGAC). Useful as context on a sub-org page. | When summing across siblings, filter on `scope == "self"` to avoid double-counting β€” the same dept payload appears on every sub-org under it. The rollup leaves out credit financing (`account_category=credit_financing`) and proposed (`account_category=proposed`) accounts entirely. Request-only accounts (`account_category=request_only`) add their `requested_ba` to the department's request and are left out of the account counts, `top_accounts` and every other figure. Returns `null` only for orgs with no CGAC at all (rare; the org has no usable budget signal). ```text ?shape=name,budget_appropriation(*) # default FY = latest ?shape=name,budget_appropriation[fiscal_year=2024](*) # specific FY ?shape=name,budget_appropriation(cgac,fiscal_year,summary) # narrow projection ``` The payload includes a `top_accounts` array (top 10 by enacted BA) for quick orientation. ### `budget_spending(*)` The funding-office-side rollup β€” aggregates contract spending where the org (or any descendant in the FH subtree) was the funding office. Walks the hierarchy via the denormalized `l{level}_fh_key` fields, so an L2 like "Technology Transformation Services" can roll up its L3/L4 grandchildren without you having to chase them yourself. Returns `null` when nothing in the subtree has funding-office activity in the budget data. ```text ?shape=name,budget_spending(*) ?shape=name,budget_spending[fiscal_year=2024](*) ``` `summary.contract_obligated` is the headline number; `n_orgs_in_rollup` tells you how many orgs participated (1 = the org itself; >1 = the org plus descendants). ### Asking for both Departments can request both leaves in one shot β€” `budget_appropriation` returns the dept totals (`scope: "self"`), `budget_spending` returns the dept's *direct* funding-office activity (most dept rollups are nominal; the real spending sits in sub-offices). ```text ?shape=name,budget_appropriation(*),budget_spending(*) ``` ## Look up budget flows for a vendor The inverse of the recipients drill-down β€” given a UEI, list the federal accounts that paid this vendor: ```text GET /api/entities/{uei}/budget-flows/ GET /api/entities/{uei}/budget-flows/?fiscal_year=2024 ``` Each row is one (account Γ— funding office Γ— this UEI) flow, with surrounding account context (account title, agency, bureau, BEA category, total enacted BA, contract share of obligated) and a hydrated `contracts` list for the PIIDs in this flow. Sorted by `contract_obligated` desc β€” the largest accounts funding this vendor first. This is the right surface for "show me everywhere money flowed to this vendor, with budget context." Note it's **contract-side only** β€” grants and other assistance aren't in this index. ## A few things worth knowing ### Capped vs raw ratios Every ratio field comes in three forms β€” `*_pct`, `*_pct_capped`, and `*_pct_capped_flag`. The capped variant is bounded at a sensible upper limit (typically 5.0) so it sorts and charts cleanly without one extreme row blowing out an axis. The flag tells you whether the cap was actually applied for that row. Use raw (`obligated_to_apportioned_pct`) when you need exact math; use capped (`obligated_to_apportioned_pct_capped`) when filtering, sorting, or visualizing. ### Partial years The latest fiscal year is year-to-date. `data_through_period` (in the default shape, next to `fiscal_year`) is the fiscal period an account-year's figures run through: `12` for a closed year, lower for the year in progress, `null` when the row has no File A data. Check it before comparing the latest year with closed years β€” besides the missing months, mid-year figures for indefinite and trust-fund appropriations can run high until year-end, so a partial year can look larger than the prior full year when it isn't. To compare only complete years: ```text ?agency_code=075&fiscal_year__gte=2022&data_through_period=12&shape=fiscal_year,data_through_period,federal_account_symbol,enacted_ba ``` The `X-Tango-Data-As-Of` response header (e.g. `2026-P10`) gives the latest period across the whole publication. See [Partial fiscal years](../../api-reference/budget.md#partial-fiscal-years). ### Summing accounts Which `account_category` values to include depends on what you are adding up. - **Apportionment, obligation and enacted sums:** filter `account_category=budgetary`. Credit financing accounts (`credit_financing`) are non-budgetary: they carry apportionments but no obligations and no `enacted_ba`, and their apportionments are not budget authority, so leaving them in inflates an apportionment total. `request_only` and `proposed` rows have null execution figures and no obligations, so an unfiltered sum picks them up only as empty rows. - **A current-law `requested_ba` total:** filter `account_category__in=budgetary,request_only`. Request-only accounts (such as NIH `075-9915`) are current law and carry the request, so `=budgetary` alone drops them. Leave out `credit_financing` and `proposed` (requests for programs Congress never created). The organization `budget_appropriation(*)` rollup applies these rules for you. ```text ?fiscal_year=2025&agency_code=075&account_category=budgetary&shape=federal_account_symbol,enacted_ba,apportioned,obligated_total ?fiscal_year=2027&agency_code=075&account_category__in=budgetary,request_only&shape=federal_account_symbol,requested_ba ``` Within a fiscal year, the default ordering puts accounts with no `enacted_ba` (credit financing, request-only and proposed) last, so they land at the end of an unfiltered list. An explicit `?ordering=` also sorts nulls last in both directions. ### Source-data anomalies Each account carries `source_anomalies`, `[]` when the row is clean. When the USAspending File C contract total for an account exceeds its positive File A total obligations, `contract_obligated` is capped at `obligated_total` and the element records the reported value and the File C rows behind the excess. Two other codes are flagged without changing any value. Check this field before treating an extreme `contract_share_of_obligated` as real. Element-by-element definitions are in the [data dictionary](../../data-dictionary/budget.md#source-anomalies). These fields may be empty until the next data refresh. ### Top-recipient arrays vs the drill-down `top_contract_recipients` and `top_grant_recipients` on the account detail are lightweight name-only arrays β€” handy for a quick label on a card. For real recipient analysis use the `/recipients/` drill-down (or `/budget-flows/` from the vendor side) β€” it carries UEI, hydrated entity payload, PIIDs, and the full matching Contract records. ### Coverage windows | Surface | Years covered | | --- | --- | | `/api/budget/accounts/` lifecycle | FY17–FY26 | | `appendix(*)` | FY08–FY27 | | `narratives(*)` | FY08–FY27 | | `/quarters/` | FY21+ | | `/recipients/`, `/budget-flows/` | FY17–FY26 (matches lifecycle) | | Org rollups (`budget_appropriation`, `budget_spending`) | Whatever coverage the underlying lifecycle rollup has for the requested FY | When you ask for a year outside the covered window, lists return empty and shape leaves return `null` β€” no error, just absence. ### Cache TTL on Organization rollups `/api/organizations/{key}/` is cached at the response level (1-week TTL by default). If you've just been added to a hierarchy and a budget rollup looks stale, that's expected β€” the cached version will turn over within the TTL window, or you can bust it by varying any query param. The budget data itself updates whenever the upstream SF-133 / Appendix / contract-share signals refresh. ## What's intentionally not in this guide - **Account-level forecasts / projections.** Tango ships the President's next-year request as a single field (`next_year_requested_ba`) plus growth math, but doesn't model multi-year scenarios. Build those on top of the historic lifecycle + 5yr CAGR. - **Apportionment line-item detail.** OMB publishes line-item apportionments separately; Tango currently exposes only the rollup-level apportioned dollar amount per account, not the per-line restrictions. - **Treasury outlay reconciliation.** The outlay numbers are the SF-133 outlay totals as published. Reconciling against Treasury's daily statement is out of scope. ## See also - [Organizations API reference](../../api-reference/organizations.md) β€” full field list and filters for `/api/organizations/`. - [Entities API reference](../../api-reference/entities.md) β€” the UEI lookup surface. - [Contracts data dictionary](../../data-dictionary/contracts.md) β€” for the `contracts[]` rows returned by the recipients and budget-flows drill-downs. - [Response shaping](../patterns/response-shaping.md) β€” the `?shape=` syntax used throughout this guide. --- --- description: "A field-by-field mapping for moving a USAspending bulk-download pipeline for FPDS contracts and subawards onto the Tango API." tags: [usaspending, migration, api, guide] updated: 2026-08-18 --- # Migrate from USAspending bulk download You've been pulling USAspending's nightly bulk CSVs, unpacking them, and bundling transactions into your own award records. This guide moves the **FPDS contracts** side of that pipeline to the Tango API. ## Scope **In scope.** Prime contract awards (FPDS) and their subawards. The FPDS data Tango ingests is the same FPDS feed USAspending republishes β€” Tango pulls it directly twice daily and bundles transactions into one row per award. **Out of scope (today).** Financial assistance (FABS) β€” grants, loans, direct payments, cooperative agreements, insurance. If your pipeline consumes USAspending's `assistance_transactions.csv`, `subaward_*` assistance rows, or any `award_type` in the assistance set (`02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`), keep that on USAspending bulk for now. Tango has no first-class FABS endpoint yet β€” `/api/contracts/` is contract-only. **Also out of scope.** Outlays on prime contracts (USAspending's `prime_award_total_outlayed_amount` on the prime side). Obligations are the canonical money metric on `/api/contracts/`. Outlays are exposed on subawards only today. ## What you actually gain - **Twice-daily FPDS ingest vs USAspending's nightly FPDS pull.** Tango is ~12 hours fresher on contract data specifically. For FABS, USAspending is your only option and they're equivalent (both refresh daily). - **One row per award, not one row per modification.** USAspending ships `contract_award_transactions.csv` with a row per FPDS mod; you have to group by award and reconcile dollar fields yourself. Tango's `/api/contracts/` returns one row per award with all mods rolled up; if you need the per-mod detail, request `?shape=...,transactions(*)` or hit `GET /api/contracts/{key}/transactions/`. - **Stable canonical `key` per award.** Tango exposes a canonical `key` derived from the FPDS award components (`CONT_AWD_{piid}_{agency}_{parent_piid}_{parent_agency}`). It's stable across re-pulls and is the URL identifier (`/api/contracts/{key}/`). PIID is still available for human display and cross-checks. - **Filter + shape at request time.** Replace the ZIP-and-grep step with query params (`?awarding_agency=GSA&obligated_gte=1000000`) and a response-shape selector (`?shape=key,piid,obligated`). Cuts payload size 80–95% vs the full bulk schema. - **Push delivery (optional).** Subscribe to filter alerts via webhooks instead of diffing CSVs nightly. See [Polling vs webhooks](#change-capture-polling-vs-webhooks) below. ## Step-by-step ### 1. Inventory the USAspending columns you actually consume Most pipelines touch 20–40 columns out of USAspending's ~280-column contract schema. List the columns your downstream code reads (parquet writer, BI tool, vendor enrichment, etc.) β€” that's the only set you need to map. ### 2. Map each column to a Tango field Use the [Field mapping](#field-mapping) table below. Two things to know up front: - **Agency codes.** USAspending uses two codes per office: a 3-digit CGAC for the **top-tier** (e.g. `047` = GSA) and a 4-digit FPDS code for the **sub-tier** (e.g. `4740` = GSA Public Buildings Service). Tango exposes both on the `awarding_office` / `funding_office` expansions as `department_code` (CGAC) and `agency_code` (FPDS sub-tier). Don't swap them β€” the names look transposable but the codes won't match. - **Code/description objects.** Several USAspending columns are split across `_code` and `_description`. Tango returns them as `{code, description}` objects via expansion. To get the bare scalar, request `?shape=naics_code` (scalar) instead of `?shape=naics(code,description)` (object). ### 3. Replace the CSV download with a paginated GET `/api/contracts/` uses **cursor pagination** β€” there is no `page=` parameter. Each response is `{count, next, previous, cursor, results}`. Follow `next` until it's null, or pass the value from the `cursor` field on the response into the next request. `/api/subawards/` uses **page-number pagination** (`page=N&limit=M`). Different surface, same idea. Both endpoints accept the same filter syntax as the API reference: range filters like `obligated_gte`, multi-value filters using `|` (e.g. `naics=541511|541512`), and full-text via `search=`. ### 4. Shape the response Pass `?shape=` listing only the fields you actually use. Without `shape`, the API returns a sensible default but it's not the full FPDS record β€” and it's still much bigger than what most ETLs need. ### 5. Decide your dedup key Use `key` for upserts (canonical, stable, URL-safe). PIID alone is not unique β€” same PIID can recur across agencies and across fiscal years. The `key` field encodes the full FPDS award tuple. ## Field mapping This covers the most-used contract and subaward columns. For everything else, request `?show_shapes=true` on `/api/contracts/` to see the full available field set, or check the [Contracts data dictionary](../../data-dictionary/contracts.md). ### Contracts (`/api/contracts/`) #### Identifiers | USAspending column | Tango field | Notes | | --- | --- | --- | | `contract_award_unique_key` / `award_id` | `key` | Use `key` for all API operations. Format: `CONT_AWD_{piid}_{agency}_{parent_piid}_{parent_agency}`. | | `award_id_piid` | `piid` | Same string. PIID alone is not unique across agencies β€” prefer `key` for joins. | | `parent_award_id_piid` | `parent_award.piid` | `parent_award` is a `{key, piid}` reference. | | `parent_award_id` | `parent_award.key` | | #### Dollar amounts | USAspending column | Tango field | Notes | | --- | --- | --- | | `total_obligated_amount` | `obligated` | Total dollars obligated across all mods. | | `current_total_value_of_award` | `base_and_exercised_options_value` | | | `potential_total_value_of_award` | `total_contract_value` | Includes unexercised options. | | `federal_action_obligation` (transaction-level) | `transactions[].obligated` | One per FPDS mod. Request via `?shape=transactions(*)`. | #### Dates | USAspending column | Tango field | Notes | | --- | --- | --- | | `action_date` (initial transaction) | `award_date` | Date the award was first signed. | | `action_date` (per modification) | `transactions[].transaction_date` | One per mod, when expanded. | | `period_of_performance_start_date` | `period_of_performance.start_date` | | | `period_of_performance_current_end_date` | `period_of_performance.current_end_date` | | | `period_of_performance_potential_end_date` | `period_of_performance.ultimate_completion_date` | | | `fiscal_year` | `fiscal_year` | Federal FY (Oct–Sep). Same semantics as USAspending. | #### Awarding / funding agency USAspending splits agency identity across four code/name pairs per side (top-tier + sub-tier + office). Tango folds them into a single `awarding_office` / `funding_office` object with three levels. **Watch the code semantics β€” `department_code` is CGAC, `agency_code` is FPDS sub-tier.** | USAspending column | Tango field | Notes | | --- | --- | --- | | `awarding_agency_code` | `awarding_office.department_code` | CGAC top-tier code (3-digit, e.g. `047` for GSA). | | `awarding_agency_name` | `awarding_office.department_name` | | | `awarding_sub_agency_code` | `awarding_office.agency_code` | FPDS sub-tier code (4-digit, e.g. `4740` for GSA PBS). | | `awarding_sub_agency_name` | `awarding_office.agency_name` | | | `awarding_office_code` | `awarding_office.office_code` | AAC (Activity Address Code), e.g. `47PF52`. | | `awarding_office_name` | `awarding_office.office_name` | | | `funding_agency_code` | `funding_office.department_code` | Same CGAC/FPDS distinction as awarding. | | `funding_agency_name` | `funding_office.department_name` | | | `funding_sub_agency_code` | `funding_office.agency_code` | | | `funding_sub_agency_name` | `funding_office.agency_name` | | | `funding_office_code` | `funding_office.office_code` | | | `funding_office_name` | `funding_office.office_name` | | To filter by agency, use `?awarding_agency=` or `?funding_agency=` β€” these accept the CGAC code, the FPDS code, the name, or the abbreviation (best-effort matching). For reproducible jobs, use the CGAC code. #### Recipient | USAspending column | Tango field | Notes | | --- | --- | --- | | `recipient_uei` | `recipient.uei` | UEI is canonical post-SAM transition. | | `recipient_name` | `recipient.display_name` | DBA / common name. `recipient.legal_business_name` is the SAM legal name. | | `recipient_duns` | (not exposed on `/api/contracts/`) | DUNS is no longer the primary entity key. Use UEI. The legacy DUNS is still on subawards as `recipient_duns`. | | `cage_code` | `recipient.cage_code` | | | `recipient_parent_uei` | `recipient.parent_uei` (via `?shape=recipient(parent_uei)`) | | #### Place of performance USAspending's `primary_place_of_performance_*` columns map to the `place_of_performance` expansion: | USAspending column | Tango field | | --- | --- | | `primary_place_of_performance_country_code` | `place_of_performance.country_code` | | `primary_place_of_performance_country_name` | `place_of_performance.country_name` | | `primary_place_of_performance_state_code` | `place_of_performance.state_code` | | `primary_place_of_performance_state_name` | `place_of_performance.state_name` | | `primary_place_of_performance_city_name` | `place_of_performance.city_name` | | `primary_place_of_performance_zip_4` | `place_of_performance.zip_code` | #### NAICS / PSC / set-aside | USAspending column | Tango field | Notes | | --- | --- | --- | | `naics_code` | `naics_code` (scalar) or `naics.code` (via `?shape=naics(code,description)`) | | | `naics_description` | `naics.description` | | | `product_or_service_code` | `psc_code` (scalar) or `psc.code` | | | `product_or_service_code_description` | `psc.description` | | | `type_of_set_aside` | `set_aside.code` (via `?shape=set_aside(code,description)`) | | | `type_of_set_aside_description` | `set_aside.description` | | #### Competition USAspending flattens competition fields onto the row; Tango groups them under `competition`. Request via `?shape=competition(*)`. | USAspending column | Tango field | Notes | | --- | --- | --- | | `type_of_contract_pricing` | `competition.contract_type.code` | Returned as `{code, description}` β€” use `.code` for direct equivalence. | | `type_of_contract_pricing_description` | `competition.contract_type.description` | | | `extent_competed` | `competition.extent_competed.code` | | | `extent_competed_description` | `competition.extent_competed.description` | | | `solicitation_identifier` | `competition.solicitation_identifier` (also exposed as top-level `solicitation_identifier`) | | | `solicitation_procedures` | `competition.solicitation_procedures.code` | | | `number_of_offers_received` | `competition.number_of_offers_received` | | | `other_than_full_and_open_competition` | `competition.other_than_full_and_open_competition.code` | | #### Description and award type | USAspending column | Tango field | Notes | | --- | --- | --- | | `award_description` / `prime_award_base_transaction_description` | `description` | | | `award_type_code` | `award_type.code` (via `?shape=award_type(code,description)`) | | | `award_type` | `award_type.description` | | ### Subawards (`/api/subawards/`) A subaward row is one report, keyed by the report UUID USAspending publishes as `subaward_sam_report_id`. Recipient details come from the entity records rather than the row, so the USAspending recipient columns map onto the `subaward_recipient` and `prime_recipient` expansions. | USAspending column | Tango field | Notes | | --- | --- | --- | | `subaward_sam_report_id` | `key` | Lowercase. `fsrs_details.id` is the same value. | | `prime_award_unique_key` | `award_key` | Joins to `/api/contracts/{award_key}/`. | | `prime_award_piid` | `piid` | | | `prime_awardee_uei` | `prime_awardee_uei` | Also `prime_recipient.uei`; `prime_recipient_id` is the entity id. | | `prime_awardee_name` | `prime_recipient.display_name` | From the entity record. | | `subawardee_uei` / `recipient_uei` | `recipient_uei` | Also `subaward_recipient.uei`; `recipient_id` is the entity id. | | `subawardee_name` / `recipient_name` | `subaward_recipient.display_name` | From the entity record; `null` for a subawardee that is not a registered entity. | | `subawardee_duns` / `recipient_duns` | not served | DUNS is no longer carried; use the UEI. | | `subawardee_parent_uei` | `recipient_parent_uei` | `recipient_parent_id` is the parent's entity id. | | `subawardee_parent_duns` | not served | | | `subawardee_business_types` | `/api/entities/{uei}/` | On the entity record. | | `subaward_number` | `subaward_details.number` | | | `subaward_action_date` | `subaward_details.action_date` | | | `subaward_amount` | `subaward_details.amount` | As published; check `amount_suspect`. | | `subaward_description` | `subaward_details.description` | | | `subaward_primary_place_of_performance_*` | `place_of_performance(*)` | From the place record; `place_of_performance_id` is its id. | | `subaward_place_of_performance_cd_original` / `_cd_current` | `pop_cd_original` / `pop_cd_current` | | | `usaspending_permalink` | `usaspending_permalink` | Passed through verbatim. | | `highly_compensated_officer_*_name` / `_amount` | `highly_compensated_officers[].name` / `.amount` | List of `{name, amount}` objects. | | `subaward_sam_report_last_modified_date` | `fsrs_details.last_modified_date` | A timestamp; the change-detection field on subawards. Order with `ordering=-last_modified_date`. | ### Reference data | USAspending file | Tango endpoint | Notes | | --- | --- | --- | | Recipient profiles ZIP | `GET /api/entities/`, `GET /api/entities/{uei}/` | UEI-keyed. | | Agency reference CSV | `GET /api/organizations/` | Unified Federal Hierarchy with CGAC, FPDS, and FH keys. See [Federal Agency Hierarchy](../../api-reference/concepts/federal-agency-hierarchy.md). | | NAICS reference CSV | `GET /api/naics/` | `code` + `description`, full-text `search=`. | | PSC reference CSV | `GET /api/psc/` | Same shape as NAICS. | ## Worked example: replace one CSV job The classic: "GSA contracts awarded in FY2026 over $1M, with recipient and place of performance." On USAspending this is a bulk-download request + ZIP unpack + filter pass. On Tango it's a paginated loop with a shape selector. === "curl" ```bash # GSA: pass the name, "047" (CGAC), or the abbreviation β€” best-effort matching. # Use CGAC for reproducible jobs. curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?\ awarding_agency=047&\ fiscal_year=2026&\ obligated_gte=1000000&\ ordering=-award_date&\ limit=100&\ shape=key,piid,award_date,obligated,total_contract_value,\ recipient(uei,display_name),naics(code,description),\ place_of_performance(state_code,city_name)" # Then follow the `next` URL on each response until it's null. ``` === "Python (tango-python)" ```python import os from urllib.parse import parse_qs, urlparse from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) SHAPE = ( "key,piid,award_date,obligated,total_contract_value," "recipient(uei,display_name),naics(code,description)," "place_of_performance(state_code,city_name)" ) cursor: str | None = None rows: list = [] while True: resp = client.list_contracts( awarding_agency="047", # GSA CGAC fiscal_year=2026, obligated_gte="1000000", sort="award_date", order="desc", limit=100, cursor=cursor, shape=SHAPE, ) rows.extend(resp.results) if not resp.next: break cursor = parse_qs(urlparse(resp.next).query).get("cursor", [None])[0] print(f"Pulled {len(rows)} contracts") ``` === "Node (tango-node)" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const SHAPE = [ "key", "piid", "award_date", "obligated", "total_contract_value", "recipient(uei,display_name)", "naics(code,description)", "place_of_performance(state_code,city_name)", ].join(","); let cursor: string | null | undefined = undefined; const rows: unknown[] = []; while (true) { const resp = await client.listContracts({ awarding_agency: "047", // GSA CGAC fiscal_year: 2026, obligated_gte: "1000000", sort: "award_date", order: "desc", limit: 100, cursor, shape: SHAPE, }); rows.push(...resp.results); if (!resp.next) break; cursor = new URL(resp.next).searchParams.get("cursor"); } console.log(`Pulled ${rows.length} contracts`); ``` The subaward equivalent uses `client.list_subawards(...)` / `client.listSubawards(...)` with `page=N` instead of `cursor`. ## Change capture: polling vs webhooks Two patterns. Pick the one that matches your tolerance for latency and ops complexity. ### Polling (simpler default) Run a scheduled job that pulls awards newer than your last cursor. The change-capture filter is `award_date_gte`: ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?award_date_gte=2026-05-01&ordering=-award_date&limit=100&shape=..." ``` What this catches: - **New awards** since the last poll, ordered by `award_date`. βœ… - **Mods to existing awards** β€” only if the mod is significant enough that Tango re-materialized the award. The `/api/contracts/` API does not expose a `updated_at` / `modified_after` filter today; `award_date` is the only date-window filter. If you need per-mod change detection, pull the transactions endpoint for the awards you care about (next section) or use webhooks. The simple pattern most teams need: 1. Persist the latest `award_date` you've seen. 2. On each run, request `award_date_gte=` and follow `next` until exhausted. 3. Upsert by `key`. This is enough for most BI / dashboards / vendor-watch use cases. ### Webhooks (push, lower latency) For "tell me when a new contract matches this filter, within minutes of FPDS landing," subscribe to a filter alert and consume `alerts.contract.match` events. The webhook payload ships matched IDs only β€” your receiver pulls the full record from `/api/contracts/{key}/`. Full walkthrough including signature verification, deduping, and the receiver loop: [Stream contract awards](./stream-awards.md). The full subscription / payload / retry / circuit-breaker reference: [Webhooks user guide](../../webhooks/index.md). One thing to know before you `POST /api/webhooks/alerts/`: if your account has more than one webhook endpoint, you **must** include `"endpoint": ""` in the request body. Single-endpoint accounts auto-resolve; multi-endpoint accounts get a 400 without it. The Python SDK's `client.create_webhook_alert(..., endpoint="...")` exposes the same kwarg. ## Historical backfill For seeding history (years of contracts at cutover), use a date-windowed cursor crawl. The pattern: 1. Pick a window β€” fiscal-year-sized windows (`fiscal_year=2018`, then `2019`, ...) parallelize well because they're independent and roughly balanced (FPDS volumes per FY are within an order of magnitude). 2. For each window, cursor-paginate `/api/contracts/?fiscal_year=&ordering=-award_date&limit=100` and write batches as you go. 3. Checkpoint the `cursor` value after each successful batch so you can resume without re-pulling. 4. Subawards: `?fiscal_year_gte=&fiscal_year_lte=` with page-number pagination. For reference, FY2026 contracts on production are ~1.8M rows; a window-per-FY crawl at `limit=100` is on the order of ~20K requests per fiscal year. Use `shape=` aggressively to keep payloads small. If you're cutting over from USAspending, validate by spot-checking 50–100 random `key` lookups against your last USAspending CSV pull for the same agency/FY and confirm `obligated`, `recipient.uei`, and `awarding_office.agency_code` agree. ## Transactions completeness `/api/contracts/{key}/transactions/` returns the FPDS modifications Tango has for that award. Each item: `modification_number`, `transaction_date`, `obligated`, `description`, `action_type`. Transactions are loaded from FPDS at award materialization β€” for an award that exists in `/api/contracts/`, the transaction list reflects what FPDS has published for that award up to the most recent ingest cycle. If your downstream wants USAspending's per-transaction row shape (one row per mod, denormalized), don't try to recreate it from the bundled award. Hit the transactions detail endpoint per `key`, or request `?shape=...,transactions(*)` on the list call to get the mods inline. ## NULL semantics USAspending bulk CSVs and Tango JSON disagree on how absent values look. Plan for both: - **USAspending CSVs** emit empty strings (`""`), and in some columns sentinel strings like `"None"` or `"NULL"`. Your ingest probably already has cleanup for this. - **Tango JSON** uses JSON `null` for absent values and omits keys from shaped responses when the field isn't requested or isn't present. A shaped response with `?shape=key,piid,recipient(uei)` will not include `recipient` at all if the recipient is unresolved β€” vs an empty object β€” so check key presence, not just truthiness, when transforming. - **Numeric fields** (`obligated`, `total_contract_value`) come back as JSON numbers, not strings. USAspending's CSVs are strings β€” your existing parser needs to handle both or you'll write strings to a numeric column. - **DUNS on contracts** is not exposed β€” see the field-mapping note above. Don't try to map `recipient_duns` through `/api/contracts/`; it'll be missing every time. DUNS lives on subawards (`recipient_duns`) for legacy joins. - **`awarding_office` codes can be `null` independently.** An award can have a known department (`department_code = "047"`) but a missing sub-tier or office. Don't assume the three levels are co-populated. ## Pitfalls - **Don't filter agency by name unless you have to.** `awarding_agency=047` (CGAC code) is exact for GSA. `awarding_agency=GSA` does best-effort name resolution β€” great for ad-hoc, can match more or fewer orgs than you expect on a production job. Use CGAC for reproducibility. The FPDS sub-tier code (e.g. `4700`) is stored on org records but **isn't a reliable filter** on `/api/contracts/` β€” use CGAC. - **`fiscal_year` is federal FY (Oct–Sep).** Same as USAspending; just don't accidentally pass a calendar year. - **`obligated_gte` / `obligated_lte` are exact USD.** Pass `1000000`, not `"1M"`. - **Multi-value filters use `|`.** `naics=541511|541512` matches either. Same for `psc` and other scalar filters. - **Cursor pagination doesn't accept `page=`.** `/api/contracts/` uses keyset cursors β€” follow `next` or pass `cursor=`. `/api/subawards/` is the opposite β€” page-number pagination with `page=N`. They are not interchangeable. - **Default response shape is opinionated.** It's a sensible middle ground, not the full FPDS record. Pass `?shape=` explicitly for production jobs; `?show_shapes=true` lists the available fields. - **PIID is not unique.** Use `key` for upserts and joins. PIID alone repeats across agencies. ## What's out of scope today - **FABS / assistance data.** No grants, loans, direct payments, cooperative agreements. Keep that on USAspending bulk. See the [Grants API reference](../../api-reference/grants.md) for what Tango does ship on the grants side β€” it's Grants.gov data, not FABS-derived. - **Prime-contract outlays.** Obligations only on `/api/contracts/`. `prime_award_total_outlayed_amount` is exposed on subawards. - **Per-mod change feed across all contracts.** No global "give me every FPDS mod since timestamp X" endpoint. Polling on `award_date_gte` catches new awards; webhook filter alerts cover filtered slices in near-real-time; per-award transaction history is on `/api/contracts/{key}/transactions/`. ## Related - [Contracts API reference](../../api-reference/contracts.md) - [Contracts data dictionary](../../data-dictionary/contracts.md) - [Subawards API reference](../../api-reference/subawards.md) - [Subawards data dictionary](../../data-dictionary/subawards.md) - [Federal Agency Hierarchy](../../api-reference/concepts/federal-agency-hierarchy.md) - [Stream contract awards](./stream-awards.md) β€” webhook receiver pattern for `alerts.contract.match` - [Webhooks user guide](../../webhooks/index.md) --- --- description: "How to post a Slack message whenever a saved opportunity filter alert matches, using a signed Tango webhook delivery." tags: [opportunities, webhooks, slack, guide] updated: 2026-08-18 --- # Opportunity updates in Slack Get a Slack message every time a new SAM.gov opportunity matches a saved filter β€” e.g., "new HHS solicitations in NAICS 541512." Tango POSTs an `alerts.opportunity.match` event; your receiver maps it to a Slack Block Kit message and forwards to a Slack [Incoming Webhook](https://api.slack.com/messaging/webhooks). ## The 1-line answer Stand up a tiny HTTP receiver that: 1. verifies the Tango signature on the inbound POST, 2. iterates `events[].matches.new[]` β€” each entry is a summary object with the fields you need (opportunity ID, notice title, solicitation number, NAICS, response deadline), 3. converts each match to Slack Block Kit blocks and POSTs to your Slack Incoming Webhook URL. Then register your receiver URL as a Tango webhook endpoint and attach an opportunity alert. !!! info "The payload already has what you need" Tango's webhook payload includes a `matches.new[]` array of summary objects β€” `id` (the opportunity's UUID), `latest_notice_title`, `solicitation_number`, `naics_code`, `response_deadline`. No fan-out fetch required for a Slack notification. See the [Webhooks payload format](../../webhooks/index.md#6-payload-format) for the full shape. ## Prerequisites - Tango API key (`TANGO_API_KEY`). - A Slack workspace where you can install an app β€” you need permission to create an Incoming Webhook. - Somewhere to host the receiver. Anywhere that can serve a public HTTPS endpoint works: a Cloudflare Worker, an AWS Lambda + API Gateway, a Fly.io / Render / Railway service, a Vercel / Netlify Function, or your own server. ## Step 1 β€” Create the Slack Incoming Webhook Follow [Slack's setup guide](https://api.slack.com/messaging/webhooks) β€” it's three clicks: create a Slack app, enable "Incoming Webhooks," and "Add New Webhook to Workspace." Pick the channel you want messages to land in. Slack hands you a URL that looks like: ```text https://hooks.slack.com/services/T0XXXX/B0XXXX/abcDEFghi123… ``` Treat this URL as a secret β€” anyone with it can post to your channel. Smoke-test it before wiring up Tango: ```bash curl -X POST -H "Content-Type: application/json" \ --data '{"text": "Hello from Tango setup test."}' \ "$SLACK_WEBHOOK_URL" ``` You should see a plain message land in the channel within a second. ## Step 2 β€” Stand up the receiver The receiver is one HTTP handler. Four things it must do: 1. **Verify the `X-Tango-Signature` header.** Reject mismatches with 401. 2. **Dedupe on `delivery_id`** if you might receive the same delivery twice (Tango retries on 5xx). The `delivery_id` is a UUID on the top-level payload, stable across retries. 3. **Iterate `event.matches.new[]`.** Each entry is a summary object β€” `id` (the opportunity's UUID), `latest_notice_title`, `solicitation_number`, `naics_code`, `response_deadline`. No additional fetch required. 4. **Convert each match to a Slack message and POST it.** Pick whichever runtime fits your stack. Below are minimal examples in Python and Node; both use the helpers shipped in the official SDKs. === "Python (FastAPI)" ```python # pip install tango-python[webhooks] fastapi uvicorn httpx import os import httpx from fastapi import FastAPI, Request, HTTPException from tango.webhooks.signing import verify_signature, SIGNATURE_HEADER SLACK_URL = os.environ["SLACK_WEBHOOK_URL"] SECRET = os.environ["TANGO_WEBHOOK_SECRET"] app = FastAPI() seen_deliveries: set[str] = set() # use Redis/DB in production @app.post("/tango/webhooks") async def receive(req: Request): body = await req.body() if not verify_signature(body, SECRET, req.headers.get(SIGNATURE_HEADER)): raise HTTPException(401, "invalid signature") payload = await req.json() # Dedupe on the top-level delivery_id (stable across retries). delivery_id = payload.get("delivery_id") if delivery_id and delivery_id in seen_deliveries: return {"ok": True} if delivery_id: seen_deliveries.add(delivery_id) async with httpx.AsyncClient(timeout=5.0) as http: for event in payload["events"]: if event["event_type"] != "alerts.opportunity.match": continue alert_id = event.get("alert_id", "") # The payload carries summary objects β€” no fetch needed. for match in event.get("matches", {}).get("new", []): blocks = opportunity_to_blocks(match, alert_id) await http.post(SLACK_URL, json={"blocks": blocks}) return {"ok": True} def opportunity_to_blocks(match: dict, alert_id: str) -> list[dict]: title = match.get("latest_notice_title") or "(untitled opportunity)" sol = match.get("solicitation_number") or "β€”" deadline = match.get("response_deadline") or "β€”" naics = match.get("naics_code") or "β€”" url = f"https://sam.gov/opp/{match['id']}/view" return [ {"type": "header", "text": {"type": "plain_text", "text": f"New: {title[:140]}"}}, {"type": "section", "fields": [ {"type": "mrkdwn", "text": f"*Solicitation*\n{sol}"}, {"type": "mrkdwn", "text": f"*Response by*\n{deadline}"}, {"type": "mrkdwn", "text": f"*NAICS*\n{naics}"}, {"type": "mrkdwn", "text": f"*Alert*\n{alert_id[:8]}…"}, ]}, {"type": "actions", "elements": [ {"type": "button", "text": {"type": "plain_text", "text": "View on SAM.gov"}, "url": url}, ]}, ] ``` === "Node (Hono / Bun / Node 18+)" ```typescript // npm i @makegov/tango-node hono import { Hono } from "hono"; import { verifySignature, SIGNATURE_HEADER } from "@makegov/tango-node"; const SLACK_URL = process.env.SLACK_WEBHOOK_URL!; const SECRET = process.env.TANGO_WEBHOOK_SECRET!; const seenDeliveries = new Set(); // use a real store in production const app = new Hono(); app.post("/tango/webhooks", async (c) => { const body = await c.req.text(); if (!verifySignature(body, SECRET, c.req.header(SIGNATURE_HEADER))) { return c.json({ error: "invalid signature" }, 401); } const payload = JSON.parse(body); // Dedupe on the top-level delivery_id (stable across retries). const deliveryId: string | undefined = payload.delivery_id; if (deliveryId && seenDeliveries.has(deliveryId)) { return c.json({ ok: true }); } if (deliveryId) seenDeliveries.add(deliveryId); for (const event of payload.events) { if (event.event_type !== "alerts.opportunity.match") continue; const alertId: string = event.alert_id ?? ""; // The payload carries summary objects β€” no fetch needed. for (const match of (event.matches?.new ?? []) as any[]) { await fetch(SLACK_URL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ blocks: opportunityToBlocks(match, alertId) }), }); } } return c.json({ ok: true }); }); function opportunityToBlocks(match: any, alertId: string) { const title = (match.latest_notice_title ?? "(untitled opportunity)").slice(0, 140); const sol = match.solicitation_number ?? "β€”"; const deadline = match.response_deadline ?? "β€”"; const naics = match.naics_code ?? "β€”"; const url = `https://sam.gov/opp/${match.id}/view`; return [ { type: "header", text: { type: "plain_text", text: `New: ${title}` } }, { type: "section", fields: [ { type: "mrkdwn", text: `*Solicitation*\n${sol}` }, { type: "mrkdwn", text: `*Response by*\n${deadline}` }, { type: "mrkdwn", text: `*NAICS*\n${naics}` }, { type: "mrkdwn", text: `*Alert*\n${alertId.slice(0, 8)}…` }, ]}, { type: "actions", elements: [ { type: "button", text: { type: "plain_text", text: "View on SAM.gov" }, url }, ]}, ]; } export default app; ``` Both examples assume `TANGO_WEBHOOK_SECRET` matches the secret you set when registering the endpoint with Tango (next step). For full receiver patterns β€” async deduplication, retries, structured logging β€” see the [Webhooks user guide](../../webhooks/index.md#8-best-practices-on-your-side). ## Step 3 β€” Register the receiver with Tango and create the alert Two API calls: one to register the endpoint, one to create the alert. === "curl" ```bash # 1. Register the receiver URL as a webhook endpoint. ENDPOINT_ID=$(curl -sS -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/endpoints/" \ -d '{ "name": "Slack β€” HHS NAICS 541512", "callback_url": "https://your-receiver.example.com/tango/webhooks", "is_active": true }' | jq -r '.endpoint_id') # The response also includes a `secret`. Save it as TANGO_WEBHOOK_SECRET # on the receiver β€” that's the shared secret Tango signs with. # 2. Create the opportunity alert targeting this endpoint. curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d "{ \"name\": \"HHS NAICS 541512 opportunities\", \"query_type\": \"opportunity\", \"filters\": {\"agency\": \"7500\", \"naics\": \"541512\", \"active\": true}, \"frequency\": \"realtime\", \"endpoint\": \"$ENDPOINT_ID\" }" ``` === "Python" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) endpoint = client.create_webhook_endpoint( name="Slack β€” HHS NAICS 541512", callback_url="https://your-receiver.example.com/tango/webhooks", is_active=True, ) print("Save this as TANGO_WEBHOOK_SECRET:", endpoint["secret"]) alert = client.create_webhook_alert( name="HHS NAICS 541512 opportunities", query_type="opportunity", filters={"agency": "7500", "naics": "541512", "active": True}, frequency="realtime", endpoint=endpoint["endpoint_id"], ) ``` === "Node" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const endpoint = await client.createWebhookEndpoint({ name: "Slack β€” HHS NAICS 541512", callback_url: "https://your-receiver.example.com/tango/webhooks", is_active: true, }); console.log("Save this as TANGO_WEBHOOK_SECRET:", (endpoint as any).secret); const alert = await client.createWebhookAlert({ name: "HHS NAICS 541512 opportunities", query_type: "opportunity", filters: { agency: "7500", naics: "541512", active: true }, frequency: "realtime", endpoint: (endpoint as any).endpoint_id, }); ``` !!! info "Save the endpoint secret" The endpoint-create response includes a one-time `secret`. Tango signs every delivery with this secret; your receiver verifies with the same value. Store it as `TANGO_WEBHOOK_SECRET` in your receiver's environment. Lose it and you'll have to rotate by recreating the endpoint. ## Step 4 β€” Test before you wait for a real match You don't want to discover the receiver is broken when the first real match shows up. Use `client.test_webhook_delivery()` (or `client.testWebhookEndpoint()` in Node) to fire a synthetic delivery at your endpoint immediately: === "Python" ```python client.test_webhook_delivery(endpoint_id=endpoint["endpoint_id"]) ``` === "Node" ```typescript await client.testWebhookEndpoint(endpoint.endpoint_id); ``` You should see a Slack message arrive within a few seconds. If you don't: - Check the endpoint logs β€” does the request reach the receiver? - Did `verifySignature` return `false`? Double-check `TANGO_WEBHOOK_SECRET` matches the endpoint secret. - Did `payload["events"]` exist? The sample-payload shape is documented in the [Webhooks user guide Β§6](../../webhooks/index.md#6-payload-format). For deeper local debugging, the SDKs ship a `WebhookReceiver` that records deliveries to an in-process queue and a `simulate.deliver()` helper that signs a payload without involving the live Tango API at all. See the [Python](../../sdks/python/webhooks.md#programmatic-use) / [Node](../../sdks/node/webhooks.md#programmatic-use) reference. ## Tuning the filter Too many alerts is worse than too few β€” Slack channels die from noise. Two levers: - **Narrow the filter.** Add `set_aside`, `agency`, or `place_of_performance` to cut volume. The same filter parameters available on `GET /api/opportunities/` work in the alert `filters` object. - **Switch frequency.** `realtime` fires on every ingestion cycle (multiple times per day). For lower-priority feeds, `daily` rolls all new matches from the past 24h into a single delivery β€” fewer Slack messages, batched. To see how many matches your current filter is producing before going live: ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?agency=7500&naics=541512&active=true&first_notice_date_after=2026-04-01" | jq '.count' ``` If `count` is in the thousands, narrow the filter β€” that's roughly how many alerts your channel will see when matches start landing. ## Updating or pausing the alert ```bash # Pause without deleting curl -X PATCH -H "X-API-KEY: $TANGO_API_KEY" -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/$ALERT_ID/" \ -d '{"is_active": false}' # Resume curl -X PATCH -H "X-API-KEY: $TANGO_API_KEY" -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/$ALERT_ID/" \ -d '{"is_active": true}' ``` A resumed alert matches from the moment you resume it β€” opportunities posted or changed while it was paused don't reach the channel. `filters` and `query_type` are immutable post-create β€” to change either, delete and recreate. ## What about contracts, grants, forecasts? Same pattern. Swap `query_type` for `contract` / `grant` / `forecast`, point `filters` at the same fields you'd pass to the equivalent list endpoint, and adapt the Block Kit mapping to the relevant entity (PIID + recipient + obligation for contracts, opportunity number + funding categories for grants, etc.). The signature verification, dedup, and Slack-post pieces are identical. --- --- description: "How to turn free-text agency strings into canonical Tango organization identifiers using the /api/resolve/ endpoint." tags: [organizations, resolution, api, guide] updated: 2026-08-18 --- # Resolve free-text agency names You have a column of agency strings β€” `"Department of Energy"`, `"DOE"`, `"Energy"`, `"Lab @ Argonne"` β€” and you need canonical Tango identifiers (a CGAC code, an FPDS code, an `Organization` UUID) before you can join, filter, or load. This guide shows you the smallest loop that gets you there. ## The 1-line answer === "curl" ```bash curl -X POST https://tango.dev/api/resolve/ \ -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Department of Energy", "target_type": "organization"}' ``` === "Python" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) result = client.resolve(name="Department of Energy", target_type="organization") for c in result.candidates: print(c.identifier, c.display_name, c.match_tier) ``` === "Node" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const result = await client.resolve({ name: "Department of Energy", target_type: "organization", }); for (const c of result.candidates) { console.log(c.identifier, c.display_name, c.match_tier); } ``` `target_type` is `"organization"` for any government org (department, agency, sub-agency, office). `"entity"` is for vendors/recipients. ## What you get back ```json { "candidates": [ { "identifier": "362361bf-4dd3-5254-85a3-4649884108d6", "display_name": "ENERGY, DEPARTMENT OF", "match_tier": "high" } ], "count": 1 } ``` - `identifier` β€” the UUID `key` of the matching `Organization`. Use it directly against [`/api/organizations/{identifier}/`](../../api-reference/organizations.md). To use in an agency filter on list endpoints, prefer the `fh_key` or CGAC code (obtainable by hydrating the org record first, or by using the org's `short_name`/abbreviation directly in the filter). See [Agency search pattern guide](../patterns/agency-search.md) for full filter semantics. - `display_name` β€” the canonical name on file. - `match_tier` β€” `"high"` / `"medium"` / `"low"`. **Free tier callers do not get this field**; they see only `identifier` and `display_name` and at most 3 candidates. Pro+ gets up to 5 candidates with `match_tier`. See the [resolve reference](../../api-reference/resolve.md) for the full contract. The endpoint does **not** return hierarchy context (parent department, level, etc.) inline. If you need that, hydrate via `/api/organizations/{identifier}/` once you have a winner. !!! info "Free-text only" `/api/resolve/` is for *free-text strings*. If your input is already a numeric code (3-digit CGAC, 4-digit FPDS), you don't need to resolve β€” skip to [Numeric codes](#numeric-codes-skip-the-resolver) below. ## Boost quality with context The resolver weights signals beyond the bare name. If your spreadsheet has city, state, or any descriptive context, pass it: === "curl" ```bash curl -X POST https://tango.dev/api/resolve/ \ -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Lab @ Argonne", "target_type": "organization", "state": "IL", "context": "national laboratory, basic science research, DOE" }' ``` === "Python" ```python result = client.resolve( name="Lab @ Argonne", target_type="organization", state="IL", context="national laboratory, basic science research, DOE", ) ``` === "Node" ```typescript const result = await client.resolve({ name: "Lab @ Argonne", target_type: "organization", state: "IL", context: "national laboratory, basic science research, DOE", }); ``` Useful context fields: industry references (NAICS/PSC), parent department name, location signals, mission text from the source row. More context generally narrows the candidate set. ## Handling low-confidence matches Treat `match_tier` as a **heuristic, not a verdict.** Empirically the tiers are noisy in both directions: a `high`-tier hit on an abbreviation collision can still be the wrong org, and a `low`-tier hit on a partial string (`"Environmental Protection"` β†’ EPA at `low`) can still be the right one. | Tier | Reasonable default | Caveat | | --- | --- | --- | | `high` | Promising. Safe enough for human-reviewed surfaces (search dropdowns, autocomplete). | A `high` tier can still be wrong on abbreviation collisions β€” don't auto-join into a downstream system without spot-checking. | | `medium` | Inspect `candidates[1:]` before accepting. | Often the second candidate is what you actually wanted. | | `low` | Treat as a suggestion. | Sometimes correct (e.g., a clipped partial name) β€” don't discard before reviewing. | | `count: 0` | Queue for human review. | No match at all β€” the string didn't hit anything. | On the free tier you don't get `match_tier`, so use ordinal position as a weak proxy (first candidate is best) and lean harder on validating downstream β€” or upgrade if this is core to your workflow. !!! warning "Don't assume the top hit is right" The resolver returns *ranked candidates*, not a single answer. For ambiguous strings ("Energy" could be the Department, an EERE office, an EIA program) the second candidate is sometimes what you wanted. If your input might be ambiguous, log all candidates, not just `[0]`. !!! danger "Anti-pattern: tiered auto-accept into automated joins" Wiring `if tier == "high": auto_accept()` straight into an ETL pipeline that writes to a downstream system is a great way to ship silently-wrong joins. Strings like `"Dept of Energy"` (no period, abbreviated "Dept") have been observed to resolve to unrelated logistics orgs at `high` tier in some snapshots β€” the resolver is doing its best on noisy input, but it can't tell you when it's wrong. **Rule of thumb:** if a wrong answer would corrupt a downstream join, send anything below explicit, reviewed confidence through a human-in-the-loop step regardless of tier. ## Numeric codes: skip the resolver If your input is already a federal code, the resolve endpoint is the wrong tool β€” it's tuned for free-text names. Use the [`Organizations` API](../../api-reference/organizations.md) or any list endpoint's agency filter, which understand numeric codes directly: | Input shape | Means | Resolves to | | --- | --- | --- | | 3-digit (`069`, `075`, `089`) | CGAC code | L1 department | | 4-digit (`2100`, `7530`) | FPDS sub-tier code | L2 agency under the matching department | | 8-9 digit (`100011980`) | `fh_key` | Exact `Organization` row | | Letters + digits (`15JCRM`) | Office / AAC code | Office-level org | === "curl" ```bash # CGAC β€” direct list filter curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/organizations/?cgac=089" # FPDS code β€” multi-stage search picks it up via aliases curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/organizations/?search=2100" # fh_key β€” direct path lookup (DOE fh_key = 100011980) curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/organizations/100011980/" ``` === "Python" ```python # CGAC β€” direct list filter resp = client.list_organizations(cgac="089") # FPDS code β€” multi-stage search picks it up via aliases resp = client.list_organizations(search="2100") # fh_key β€” direct path lookup org = client.get_organization("100011980") ``` === "Node" ```typescript // CGAC β€” direct list filter let resp = await client.listOrganizations({ cgac: "089" }); // FPDS code β€” multi-stage search picks it up via aliases resp = await client.listOrganizations({ search: "2100" }); // fh_key β€” direct path lookup const org = await client.getOrganization("100011980"); ``` For filter-time use ("give me contracts under DOE"), the agency filter on every list endpoint accepts any of these forms β€” see the [Agency search pattern guide](../patterns/agency-search.md) for full semantics. ## Batch loop: clean a CSV The endpoint is per-call, not bulk. To clean a CSV column, loop with light concurrency. !!! note "Illustrative, not production-ready" The scripts below are teaching examples β€” sequential, no de-duplication, no retries, no concurrency. For real 1000-row ETL jobs, dedupe inputs first (`"DOE"` appears 400 times β†’ resolve once, fan out), wrap calls in retry-with-backoff, and pace yourself off the SDK's exposed rate-limit headers: `client.rate_limit_info` (Python) / `client.rateLimitInfo` (Node). Both expose `remaining`, `reset`, and `retryAfter` after each request. === "Python" ```python import csv import os import time from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) def resolve_agency(name: str, *, state: str | None = None, context: str | None = None) -> dict: """Return the top candidate plus the full ranked list for review.""" result = client.resolve( name=name, target_type="organization", state=state, context=context, ) candidates = result.candidates return { "input": name, "match_count": result.count, "top_identifier": candidates[0].identifier if candidates else None, "top_display_name": candidates[0].display_name if candidates else None, "top_tier": candidates[0].match_tier if candidates else None, # None on free tier "all_candidates": candidates, } with open("agencies_in.csv") as fin, open("agencies_resolved.csv", "w") as fout: reader = csv.DictReader(fin) writer = csv.DictWriter( fout, fieldnames=["input", "identifier", "display_name", "tier", "needs_review"], ) writer.writeheader() for row in reader: result = resolve_agency(row["agency"], state=row.get("state")) tier = result["top_tier"] writer.writerow( { "input": result["input"], "identifier": result["top_identifier"] or "", "display_name": result["top_display_name"] or "", "tier": tier or "", "needs_review": tier in (None, "low") or result["match_count"] == 0, } ) time.sleep(0.05) # be polite; standard rate limits apply ``` === "Node" ```typescript import { TangoClient, type ResolveCandidate } from "@makegov/tango-node"; import { createReadStream, createWriteStream } from "node:fs"; import { setTimeout as sleep } from "node:timers/promises"; import { parse } from "csv-parse"; import { stringify } from "csv-stringify"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); async function resolveAgency( name: string, opts: { state?: string; context?: string } = {}, ) { const result = await client.resolve({ name, target_type: "organization", state: opts.state, context: opts.context, }); const candidates: ResolveCandidate[] = result.candidates ?? []; const top = candidates[0]; return { input: name, matchCount: result.count ?? 0, topIdentifier: top?.identifier ?? null, topDisplayName: top?.display_name ?? null, topTier: top?.match_tier ?? null, // null on free tier allCandidates: candidates, }; } const parser = createReadStream("agencies_in.csv").pipe( parse({ columns: true }), ); const writer = stringify({ header: true, columns: ["input", "identifier", "display_name", "tier", "needs_review"], }); writer.pipe(createWriteStream("agencies_resolved.csv")); for await (const row of parser) { const result = await resolveAgency(row.agency, { state: row.state }); const tier = result.topTier; writer.write({ input: result.input, identifier: result.topIdentifier ?? "", display_name: result.topDisplayName ?? "", tier: tier ?? "", needs_review: tier === null || tier === "low" || result.matchCount === 0, }); await sleep(50); // be polite; standard rate limits apply } writer.end(); ``` Either script writes `identifier` (the UUID `key` returned by the resolver) into the output column. That UUID is `Organization.key` β€” it's what `/api/organizations/{identifier}/` accepts. It is **not** an `fh_key` (the 8–9 digit numeric Federal Hierarchy code); if you need the `fh_key` for downstream filter use, hydrate the org record first. ## Pitfalls - **`target_type` is `"organization"`, not `"agency"`.** The endpoint has no `"agency"` choice; all government orgs (department, agency, sub-agency, office) live under `"organization"`. - **GET won't work.** This endpoint is POST-only with a JSON body. Drop the `?q=` pattern you may have seen in older snippets. - **"Department of X" vs codes.** The resolver handles both well in isolation, but mixed input shapes ("DOE", `089`, "Energy") in one column means you should branch: route numeric-looking values through `/api/organizations/?search=` and free text through `/api/resolve/`. - **Sub-offices bubble up.** A string like `"NNSA Office of Defense Programs"` may resolve to NNSA (L2) rather than the specific program office (L3). Pass the office name in `context` to nudge the resolver, or hydrate the result and walk down via `/api/organizations/?parent_fh_key=...`. - **Deprecated / reorganized agencies.** Tango preserves demoted Federal Hierarchy records by `fh_key` so historical IDs still resolve, but the `display_name` you get back may be the *current* canonical name, not the historical one. If you're matching contracts from 2010, expect the modern descendant org back β€” that's intentional. See [Federal agency hierarchy](../../api-reference/concepts/federal-agency-hierarchy.md) for the provenance story. - **Empty `candidates` array, HTTP 200.** No match is not an error. Always check `count` before indexing `candidates[0]`. - **`identifier` is a UUID, not an `fh_key`.** The resolver returns the org's UUID `key`. If your downstream system expects the 8–9 digit `fh_key`, hydrate the org record first β€” don't pipe the UUID into an `?fh_key=...` filter. ## See also - [Resolve endpoint reference](../../api-reference/resolve.md) β€” full request/response contract, tier limits, error codes. - [Organizations API](../../api-reference/organizations.md) β€” direct lookups by `fh_key`, CGAC filter, search. - [Federal agency hierarchy](../../api-reference/concepts/federal-agency-hierarchy.md) β€” what CGAC, FPDS, L1/L2/L3 mean and where the data comes from. - [Agency search pattern](../patterns/agency-search.md) β€” how the agency filter on every list endpoint resolves the same shapes of input at query time. --- --- description: "A worked recipe for finding live SAM.gov opportunities by NAICS code, from browsing codes through pagination and webhook alerts." tags: [opportunities, naics, search, api, guide] updated: 2026-08-18 --- # Search opportunities by NAICS Find live SAM.gov opportunities matching one or more NAICS codes, sorted by response deadline. ## The 1-line answer `GET /api/opportunities/` with `naics=` + `active=true` + `ordering=response_deadline`. === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?naics=541512&active=true&ordering=response_deadline" ``` === "Python" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) resp = client.list_opportunities( naics="541512", active=True, ordering="response_deadline", limit=50, ) for opp in resp.results: print(opp.response_deadline, opp.opportunity_id, opp.title) ``` === "Node" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const resp = await client.listOpportunities({ naics: "541512", active: true, ordering: "response_deadline", limit: 50, }); for (const opp of resp.results) { console.log(opp.response_deadline, opp.opportunity_id, opp.title); } ``` That's it. The rest of this guide is refinements: looking up codes you don't know, getting `naics_code` back in the payload, layering narrowing filters, drilling into a single opportunity, paginating, and staying fresh with webhooks. !!! warning "Filter name gotcha" The filter is `naics`, not `naics_code`. And it's `active=true`, not `status=active` β€” there is no `status` filter on this endpoint. ## Step 1 β€” Find the NAICS codes you care about Most users don't have `541512` memorized. Browse `/api/naics/` with `search=` first. It matches both code prefix and description text: === "curl" ```bash # All NAICS in the 5415 (Computer Systems Design) family curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/naics/?search=5415&limit=25" # Free-text on description (returns 9 hits today) curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/naics/?search=computer&limit=25" ``` === "Python" ```python # All NAICS in the 5415 family family = client.list_naics(search="5415", limit=25) for r in family.results: # list_naics() returns plain dicts, not shaped objects β€” use dict access. print(r["code"], "-", r["description"]) # Free-text on description computer = client.list_naics(search="computer", limit=25) ``` === "Node" ```typescript const family = await client.listNaics({ search: "5415", limit: 25 }); for (const r of family.results) { console.log(r.code, "-", r.description); } const computer = await client.listNaics({ search: "computer", limit: 25 }); ``` !!! tip "Search terms that miss" The NAICS table uses Census Bureau wording. Industry jargon often misses β€” `cybersecurity`, `cyber`, and `cloud` all return zero hits because those words don't appear in any NAICS description. Try the underlying activity: `computer`, `security`, `programming`, `data processing`, `software`. Once you've picked your codes, `|`-OR them together for the opportunities call (see [Multi-NAICS search](#multi-naics-search) below). Full reference: [NAICS API](../../api-reference/naics.md). ## Step 2 β€” Get `naics_code` back in the response The default opportunity shape for `list_opportunities()` is minimal (`opportunity_id, title, solicitation_number, response_deadline, active`) and does **not** include `naics_code`. If you're searching by NAICS you almost certainly want to see which code each result matched. Ask for it explicitly via `shape=`: === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?naics=541511|541512&active=true&ordering=response_deadline&shape=opportunity_id,title,response_deadline,naics_code,office(*),set_aside" ``` === "Python" ```python resp = client.list_opportunities( naics="541511|541512", active=True, ordering="response_deadline", shape="opportunity_id,title,response_deadline,naics_code,office(*),set_aside", limit=50, ) for opp in resp.results: print(opp.naics_code, opp.response_deadline, opp.title) ``` === "Node" ```typescript const resp = await client.listOpportunities({ naics: "541511|541512", active: true, ordering: "response_deadline", shape: "opportunity_id,title,response_deadline,naics_code,office(*),set_aside", limit: 50, }); for (const opp of resp.results) { console.log(opp.naics_code, opp.response_deadline, opp.title); } ``` The list-detail default shape is documented in [Opportunities reference β†’ Response Shaping](../../api-reference/opportunities.md#response-shaping). For the syntax (nested expansions, wildcards, flattening), see the [Response Shaping pattern guide](../patterns/response-shaping.md). ## Step 3 β€” Add the usual narrowing filters In practice you almost never search by NAICS alone. Layer on whatever applies. Keep it to two or three narrowing filters at a time β€” five at once usually reduces the result set to zero on any single day: === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?\ naics=541512&\ active=true&\ agency=DOD&\ response_deadline_after=2026-05-15&\ ordering=response_deadline" ``` === "Python" ```python resp = client.list_opportunities( naics="541512", active=True, agency="DOD", response_deadline_after="2026-05-15", ordering="response_deadline", limit=50, ) ``` === "Node" ```typescript const resp = await client.listOpportunities({ naics: "541512", active: true, agency: "DOD", response_deadline_after: "2026-05-15", ordering: "response_deadline", limit: 50, }); ``` | Filter | What you'd use it for | | --- | --- | | `set_aside` | Small-business / 8(a) / WOSB / SDVOSB carve-outs. | | `agency` | Limit to a department or sub-agency (vector-backed; `"DOD"`, `"Department of Energy"`, `"NAVSEA"` all work). | | `notice_type` | `Solicitation`, `Combined Synopsis/Solicitation`, `Sources Sought`, `Presolicitation`, etc. Validated server-side. | | `response_deadline_after` | Drop anything already closed or closing too soon to bid. | | `response_deadline_before` | Cap how far out you look. | | `place_of_performance` | Free-text-ish match on PoP. | | `search` | Full-text search on the opportunity itself. | See the full list in the [Opportunities API reference](../../api-reference/opportunities.md). ## Multi-NAICS search Most vendors care about a portfolio of NAICS codes, not just one. Use `|` to pass multiple: === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?naics=541511|541512|541519&active=true&ordering=response_deadline" ``` === "Python" ```python resp = client.list_opportunities( naics="541511|541512|541519", active=True, ordering="response_deadline", limit=50, ) ``` === "Node" ```typescript const resp = await client.listOpportunities({ naics: "541511|541512|541519", active: true, ordering: "response_deadline", limit: 50, }); ``` The same `|` syntax works for `psc` and other filters that accept multiple values. ## Paginating through results A single NAICS code can easily return hundreds of opportunities (`541512` alone returns ~500). At the default `limit=50` that's ten pages. The endpoint is page-based β€” there is no cursor for opportunities β€” and the response includes `next`/`previous` URLs. === "curl" ```bash # Page 2, 3, ... until response.next is null curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities/?naics=541512&active=true&ordering=response_deadline&limit=50&page=2" ``` === "Python" ```python # tango-python doesn't ship an iterator β€” drive it yourself. page = 1 while True: resp = client.list_opportunities( naics="541512", active=True, ordering="response_deadline", limit=50, page=page, ) for opp in resp.results: print(opp.response_deadline, opp.opportunity_id) if not resp.next: break page += 1 ``` === "Node" ```typescript // tango-node ships an async iterator that walks pages for you. for await (const opp of client.iterateOpportunities({ naics: "541512", active: true, ordering: "response_deadline", limit: 50, })) { console.log(opp.response_deadline, opp.opportunity_id); } ``` Always pass an `ordering=` when paginating. Without one, page boundaries are undefined and you can see duplicates or skipped rows across pages. ## Drilling into a single opportunity The list endpoint gives you summary fields. To pull the full record β€” description, attachments, notice history β€” hit the detail endpoint: === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/opportunities//?shape=opportunity_id,title,naics_code,response_deadline,description,attachments(name,mime_type,url)" ``` === "Python" ```python # No public get_opportunity() yet β€” use the lower-level _get(). See note below. opp = client._get( f"/api/opportunities/{opp_id}/", params={"shape": "opportunity_id,title,naics_code,response_deadline," "description,attachments(name,mime_type,url)"}, ) print(opp["title"], "-", len(opp.get("attachments") or []), "attachment(s)") for a in (opp.get("attachments") or []): print(" -", a["name"], a["mime_type"], a["url"]) ``` === "Node" ```typescript // No public getOpportunity() yet β€” use fetch directly. See note below. const r = await fetch( `https://tango.dev/api/opportunities/${oppId}/?shape=opportunity_id,title,naics_code,response_deadline,description,attachments(name,mime_type,url)`, { headers: { "X-API-KEY": process.env.TANGO_API_KEY! } }, ); const opp = await r.json(); console.log(opp.title, "-", (opp.attachments ?? []).length, "attachment(s)"); ``` !!! info "No `get_opportunity()` convenience method yet" Neither SDK currently ships a typed `get_opportunity()` / `getOpportunity()`. The examples above use `client._get(...)` (Python) and `fetch` (Node). A typed wrapper is on the roadmap; the URL shape will not change. !!! warning "`attachments(extracted_text)` is Pro+ tier" The default `attachments(...)` expansion gives you `attachment_id, file_size, mime_type, name, posted_date, resource_id, type, url`. The `extracted_text` sub-field (full OCR'd text of each attachment) is **Pro+ tier only**. Free-tier callers who request it get the response without it plus a `meta.upgrade_hints` entry. See [pricing](../../getting-started/pricing.md). ## Stay fresh with webhooks Polling `/api/opportunities/` every few minutes works, but it's wasteful and you'll miss the window on fast-turn solicitations. Use a **filter subscription** instead. The full webhooks model β€” endpoint setup, signing, retries β€” lives in the [Webhooks user guide](../../webhooks/index.md); this is the abbreviated version for "watch a NAICS portfolio." !!! info "`endpoint` is required for multi-endpoint accounts" If your account has more than one webhook endpoint configured, the alert-create call **must** include the `endpoint` UUID (the server returns 400 otherwise so deliveries can't go to the wrong receiver). Single-endpoint accounts may omit it. List your endpoints first with `GET /api/webhooks/endpoints/` or `client.list_webhook_endpoints()`. === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "NAICS 5415xx opportunities (SBA)", "query_type": "opportunity", "filters": { "naics": "541511|541512|541519", "active": "true", "set_aside": "SBA" }, "frequency": "realtime", "endpoint": "" }' ``` === "Python" ```python # Single-endpoint account β€” `endpoint=` may be omitted. # Multi-endpoint account β€” pass the UUID explicitly. alert = client.create_webhook_alert( name="NAICS 5415xx opportunities (SBA)", query_type="opportunity", filters={ "naics": "541511|541512|541519", "active": "true", "set_aside": "SBA", }, frequency="realtime", endpoint="", # required if you have >1 endpoint ) print(alert.alert_id, alert.status) ``` === "Node" ```typescript const alert = await client.createWebhookAlert({ name: "NAICS 5415xx opportunities (SBA)", query_type: "opportunity", filters: { naics: "541511|541512|541519", active: "true", set_aside: "SBA", }, frequency: "realtime", endpoint: "", // required if you have >1 endpoint }); console.log(alert.alert_id, alert.status); ``` Tango re-evaluates the filter on its schedule and POSTs matching opportunities to your endpoint as they appear. Deliveries carry IDs only β€” fetch the full record with the [drill-in pattern](#drilling-into-a-single-opportunity) above. Tier limits and cron-vs-realtime semantics in the [Webhooks user guide](../../webhooks/index.md). ## Combining with agency search NAICS + agency together is the most common shape, and `agency` is vector-backed β€” you don't have to know the exact CGAC/FPDS code. `agency=DOD`, `agency=Navy`, `agency=NAVSEA` all do something sensible. If you need precise agency-tree semantics (e.g. *the whole Department* vs. *just this sub-agency*), see the [agency search pattern guide](../patterns/agency-search.md). ## Common pitfalls - **`active=true` vs `notice_type`.** `active=true` filters by Tango's archive flag β€” i.e., the opportunity isn't archived/expired. It does **not** filter by phase. If you want only currently-biddable solicitations, combine `active=true` with `notice_type=Solicitation` (or `Combined Synopsis/Solicitation`) **and** `response_deadline_after=`. - **NAICS code format.** Six-digit string, no hyphens, no leading zeros stripped. `"541512"` is correct; `541512` (int) works in JSON but URL-encode it as a string. Five-digit and four-digit prefixes are **not** matched β€” use the [NAICS browse path](#step-1-find-the-naics-codes-you-care-about) to find the exact six-digit codes you want, then `|`-OR them together. - **Default ordering.** Without `ordering=`, list responses come back in an undefined order. If you care about "soonest deadline first," always pass `ordering=response_deadline`. This matters double when paginating. - **`naics_code` isn't in the default shape.** If `opp.naics_code` raises `AttributeError`, you forgot the `shape=` override from [Step 2](#step-2-get-naics_code-back-in-the-response). ## Related - [Opportunities API reference](../../api-reference/opportunities.md) - [NAICS API reference](../../api-reference/naics.md) - [Response Shaping pattern](../patterns/response-shaping.md) - [Webhooks user guide](../../webhooks/index.md) - [Agency search patterns](../patterns/agency-search.md) --- --- description: "Polling vs. webhook options for getting notified when a new contract award matches a saved filter, with worked examples of each." tags: [awards, webhooks, api, guide] updated: 2026-08-18 --- # Get notified when new awards match your filter You want a heads-up when a new contract award matches a saved filter β€” say, "DOD awards over $1M in NAICS 541512." There are two ways to do it. **Polling is the default for most teams.** Webhooks are the upgrade if you already run that kind of infrastructure. ## The 1-line answer - **Polling:** `GET /api/contracts/?&modified_after=` on a 15-30 min cron. Dedupe on `key`. Done. - **Webhooks:** create a filter alert (`POST /api/webhooks/alerts/`) β€” and if your account has more than one webhook endpoint, you **must** pass `endpoint=` (see [Step 1: Create the filter alert](#step-1-create-the-filter-alert) under Option B). ## How fast is "new"? Whichever option you pick, latency is bounded by upstream data sources, not by your transport: | Source | Cadence | | --- | --- | | FPDS publishes new contract rows | Irregular; weekday business hours, large catch-ups overnight | | Tango ingests from FPDS | Twice daily | | Tango's `realtime` alert evaluator | `*/5 * * * *` (every 5 min) | So the gap between a contract being signed and you finding out is typically **hours, sometimes a day** β€” not seconds. The 5-min webhook cron is *downstream* of the twice-daily FPDS pull; it does not make the upstream feed any fresher. If you need true second-level streaming, neither option will give it to you, because FPDS itself doesn't. ## When to pick which | | Polling | Webhooks | | --- | --- | --- | | Latency from FPDS ingest | 0-30 min (your poll interval) | ≀ 5 min | | Latency from FPDS *publish* | Hours (FPDS cadence) | Hours (same) | | Needs public HTTPS endpoint | No | Yes | | Needs HMAC verifier | No | Yes | | Needs a job queue | No | Strongly recommended | | Retry / dedupe logic | Free (idempotent by construction) | Required (at-least-once delivery) | | Backpressure if your end is slow | None | Tango opens the circuit breaker on you | Webhook only wins when you're already running a webhook stack (Stripe, GitHub, Slack, etc.). For a single BD / analytics team, a polling job has half the moving parts and the same effective freshness. --- ## Option A β€” Polling (the default) Run a cron that hits `/api/contracts/` with your filters plus `modified_after=`. Track the last-run timestamp in your DB or a state file; dedupe on each result's `key`. ### Sketch ```text every 15-30 min: since = read last_successful_run_ts() # ISO 8601 results = GET /api/contracts/?&modified_after=&ordering=-award_date&limit=100 for row in results.paginate(): if row.key not in already_seen_table: handle(row) already_seen_table.insert(row.key) write last_successful_run_ts(now_before_request) ``` A few rules to keep this boring: - Record `now_before_request` *before* you send the call, not after. Otherwise you'll lose records that landed during your fetch window. - Always paginate (`next` cursor). The default page size is small; a busy filter will exceed it. - Dedupe on `key` (the contract's stable primary id), not on `(piid, agency)`. PIIDs are not globally unique. - `modified_after` covers both new and modified rows β€” that's normally what you want. If you only want net-new awards, also filter on `award_date_gte=`. - Allowed `ordering` values are `award_date`, `obligated`, `total_contract_value` (and the same with a `-` prefix). `key` is not an allowed ordering. ### Three-language smoke test === "curl" ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?\ funding_agency=DOD&naics=541512&obligated_gte=1000000\ &modified_after=2026-05-12T00:00:00Z&ordering=-award_date&limit=20" ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) # The Python SDK takes `naics_code=` and maps it to the API's `naics=`. # Same story for `psc_code` β†’ `psc`. # # `modified_after` isn't exposed as a top-level kwarg on list_contracts() yet, # so pass it via `filters={...}` β€” values there get forwarded verbatim. contracts = client.list_contracts( funding_agency="DOD", naics_code="541512", obligated_gte="1000000", ordering="-award_date", limit=20, filters={"modified_after": "2026-05-12T00:00:00Z"}, ) for c in contracts.results: handle(c) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); // The Node SDK accepts BOTH `naics` (raw API name) and `naics_code` (alias). const page = await client.listContracts({ funding_agency: "DOD", naics: "541512", obligated_gte: "1000000", modified_after: "2026-05-12T00:00:00Z", ordering: "-award_date", limit: 20, }); for (const c of page.results) { handle(c); } ``` That's the whole pattern. Half of all "stream awards" use cases stop here. If yours is one of them, you're done. --- ## Option B β€” Webhooks (advanced) Pick webhooks if you already run a public HTTPS endpoint with HMAC verification and a job queue, and want push delivery instead of polling. Otherwise stick with Option A. ### Step 1: Create the filter alert `POST /api/webhooks/alerts/` is the entrypoint. Returns **201 Created** with the new alert, or **200 OK** with the existing one if a subscription with the same `query_type` + `filters` already exists (dedup by SHA-256 hash of the canonical filter). !!! warning "Multi-endpoint accounts must specify `endpoint`" If your account has more than one webhook endpoint, the API rejects `POST /api/webhooks/alerts/` without an explicit `endpoint=` field β€” it will not guess which one to use. Single-endpoint accounts get auto-resolve for free. List your endpoints with `GET /api/webhooks/endpoints/` and copy the `id` of the one you want. === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "DOD IT services > $1M", "query_type": "contract", "filters": { "funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000" }, "frequency": "realtime", "endpoint": "" }' ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) # Filter keys here match the RAW API param names (`naics`, `psc`), not the # `list_contracts()` kwarg aliases (`naics_code`, `psc_code`). alert = client.create_webhook_alert( name="DOD IT services > $1M", query_type="contract", filters={ "funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000", }, frequency="realtime", endpoint="", # required if you have >1 endpoint ) print(alert.alert_id, alert.status) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const alert = await client.createWebhookAlert({ name: "DOD IT services > $1M", query_type: "contract", filters: { funding_agency: "DOD", naics: "541512", obligated_gte: "1000000", }, frequency: "realtime", endpoint: "", // required if you have >1 endpoint }); console.log(alert.alert_id, alert.status); ``` #### Frequency choices | Frequency | When it runs | Tier | | --- | --- | --- | | `realtime` | Every 5 minutes (`*/5 * * * *`); independent of FPDS ingest | All tiers | | `daily` | Once per day | All tiers | | `custom` | 5-field cron in `cron_expression` (e.g. `0 8 * * 1` for weekly) | Small and above | "Realtime" is the most-frequent option, not a true streaming pipe. The evaluator polls every 5 min regardless of whether anything new landed upstream. ### Step 2: Build the receiver Tango POSTs a signed JSON batch to your endpoint. The receiver has three jobs: **verify the signature, dedupe on `delivery_id`, return 2xx fast.** #### The payload shape (real production deliveries) ```json { "timestamp": "2026-05-12T18:20:14Z", "delivery_id": "8c5e3f6a-1234-4abc-9def-9b21abcde000", "events": [ { "event_type": "alerts.contract.match", "alert_id": "e4c4aaaa-bbbb-cccc-dddd-eeeeffff0000", "query_type": "contract", "filters": {"funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000"}, "matches": { "new_count": 2, "modified_count": 0, "new": [ {"id": "CONT_AWD_47QFWA26F0009_4732_47QTCK18D0004_4732", "piid": "47QFWA26F0009", "total_contract_value": 5364614.65, "recipient_legal_business_name": "ACME CORP"}, {"id": "CONT_AWD_FA8773_24_C_0099_5700_GS35F0119Y_4732", "piid": "FA877324C0099", "total_contract_value": 1450000.00, "recipient_legal_business_name": "BETA INDUSTRIES LLC"} ], "modified": [] }, "checked_at": "2026-05-12T18:20:12Z" } ] } ``` See [Webhooks user guide Β§6 β€” Payload format](../../webhooks/index.md#6-payload-format) for the field-by-field reference. The summary objects in `matches.new[]` / `matches.modified[]` carry just enough to route on (`id`, `piid`, `total_contract_value`, `recipient_legal_business_name`); pull the full record from `GET /api/contracts/{id}/` if you need more. !!! info "Sample-payload preview vs production" `GET /api/webhooks/endpoints/sample-payload/?event_type=alerts.contract.match` returns a **simplified preview** (just `new_ids` / `modified_ids`, no `delivery_id`, no `matches.new[]`). Real deliveries from the dispatcher carry the richer shape above. Build against this guide and the webhooks user guide Β§6 β€” not against the sample-payload response. #### Python receiver (Flask) ```python import hashlib import hmac import json import os import flask SECRET = os.environ["TANGO_WEBHOOK_SECRET"].encode() app = flask.Flask(__name__) # Replace with Redis / your DB. Must persist across restarts and be fast. _seen_deliveries: set[str] = set() @app.post("/tango/webhooks") def recv(): body = flask.request.get_data() # raw bytes, NOT request.json sig_header = flask.request.headers.get("X-Tango-Signature", "") expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest() received = sig_header.removeprefix("sha256=") if not hmac.compare_digest(expected, received): return "Invalid signature", 401 payload = json.loads(body) # 1. Idempotency: Tango guarantees at-least-once delivery. delivery_id = payload.get("delivery_id") if delivery_id and delivery_id in _seen_deliveries: return "ok", 200 if delivery_id: _seen_deliveries.add(delivery_id) # 2. Enqueue and return 2xx fast. Don't process inline β€” slow handlers # trigger retries and eventually trip the circuit breaker. for event in payload.get("events", []): if event.get("event_type") != "alerts.contract.match": continue # ignore other event types in the same batch matches = event.get("matches", {}) for match in matches.get("new", []) + matches.get("modified", []): enqueue_match(event["alert_id"], match) # match has id, piid, total_contract_value, recipient_legal_business_name return "ok", 200 def enqueue_match(alert_id: str, match: dict): # Push to Celery / RQ / SQS / whatever. Your worker fetches the full # award details from /api/contracts/{id}/ as needed. ... ``` #### Node receiver (Express) ```typescript import crypto from "node:crypto"; import express from "express"; const SECRET = process.env.TANGO_WEBHOOK_SECRET!; const app = express(); // Replace with Redis / your DB. Must persist across restarts. const seenDeliveries = new Set(); // IMPORTANT: capture the raw body for HMAC. JSON-parse from the buffer, NOT via express.json(). app.post( "/tango/webhooks", express.raw({ type: "*/*" }), (req, res) => { const body = req.body as Buffer; // raw bytes const sigHeader = (req.header("x-tango-signature") || "").replace(/^sha256=/, ""); const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); const a = Buffer.from(expected, "utf8"); const b = Buffer.from(sigHeader, "utf8"); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) { return res.status(401).send("Invalid signature"); } const payload = JSON.parse(body.toString("utf8")); // 1. Idempotency const deliveryId: string | undefined = payload.delivery_id; if (deliveryId && seenDeliveries.has(deliveryId)) { return res.status(200).send("ok"); } if (deliveryId) seenDeliveries.add(deliveryId); // 2. Enqueue + ack for (const event of payload.events ?? []) { if (event.event_type !== "alerts.contract.match") continue; const matches = event.matches ?? {}; for (const m of [...(matches.new ?? []), ...(matches.modified ?? [])]) { enqueueMatch(event.alert_id, m); } } res.status(200).send("ok"); }, ); function enqueueMatch(alertId: string, match: unknown) { // Push to BullMQ / SQS / whatever. Pull full record from // GET /api/contracts/{id}/ in the worker. } ``` Key rules: - **Sign the raw body bytes**, not a re-serialized JSON. Any whitespace change breaks the HMAC. - **Constant-time compare** (`hmac.compare_digest` / `crypto.timingSafeEqual`) β€” never `==`. - **Return 2xx within a few seconds.** Synchronous work trips retries and eventually opens the circuit breaker. - **Dedupe on `delivery_id`** β€” same `delivery_id` may arrive more than once on retry. It is the canonical idempotency key. - **Ignore unknown event types** in the batch (don't 4xx) β€” a single delivery may contain multiple event types for the same endpoint. ### Step 3: Test end-to-end with the cookbook receiver The public [tango-cookbook](https://github.com/makegov/tango-cookbook) ships a [webhook receiver example](https://github.com/makegov/tango-cookbook/tree/main/examples/webhook-receiver) β€” a small FastAPI app that verifies signatures, dedupes redelivered events, and routes each one to stdout or Slack. Use it during integration before you have a production endpoint. ```bash # In your tango-cookbook checkout: just webhook-serve # starts on localhost:8000 cloudflared tunnel --url http://localhost:8000 # public URL just webhook-register https:///webhooks/tango ``` Then trigger a test delivery: ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/endpoints/test-delivery/" \ -d '{"endpoint": ""}' # required for multi-endpoint accounts ``` ### Managing the alert ```bash # List your filter alerts curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts/" # Pause without deleting curl -X PATCH -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts//" \ -d '{"is_active": false}' # Delete curl -X DELETE -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts//" ``` `query_type` and `filters` are **immutable** after creation β€” delete and recreate to change them. You can update `name`, `frequency`, `cron_expression`, and `is_active`. --- ## Common pitfalls - **Expecting sub-minute latency.** Don't. FPDS ingests twice daily; effective end-to-end latency from "vendor signs contract" to "your code sees it" is measured in hours, not seconds β€” regardless of whether you poll or use webhooks. - **Forgetting `endpoint=` on multi-endpoint accounts.** Any `POST /api/webhooks/alerts/` (and any `test-delivery`) returns 400 with `"You have multiple webhook endpoints. Please specify which endpoint to use via the 'endpoint' field."` Pass the UUID explicitly. - **Python SDK kwarg surprise.** `client.list_contracts(naics=...)` raises β€” the kwarg is `naics_code` (the SDK maps it to the API's `naics`). Same for `psc_code` β†’ `psc`. The raw HTTP filter, and the `filters={}` dict you pass to `create_webhook_alert()`, both use the API name (`naics`, `psc`). - **Filter doesn't match `/api/contracts/`.** Test the filter against the API first. If `/api/contracts/?` returns nothing, the alert will never fire and your poll loop will never see anything. - **HMAC mismatch.** You're hashing a re-serialized body, or you stripped a trailing newline. Hash the **raw request bytes** as received. Signature is `sha256=<64 hex chars>` over `body` using your endpoint's secret. - **Slow receiver.** If your handler takes more than a few seconds, Tango retries with exponential backoff (up to 10 min between attempts) and eventually opens the circuit breaker. Always enqueue + return 2xx. - **At-least-once duplicates.** The same `delivery_id` can land more than once on retry. If your downstream isn't idempotent, you'll double-write. Dedupe on `delivery_id`. - **Polling without `modified_after`.** A raw `award_date_gte` poll will miss modifications to existing records. `modified_after` covers both new and updated rows. Use both if you want strict "new awards only". - **Tier caps.** Free tier gets 1 filter alert; Small 5; Medium 10; Large 25. Hitting the cap returns 400. ## Related - [Contracts API reference](../../api-reference/contracts.md) - [Webhooks user guide](../../webhooks/index.md) β€” full subscription / payload / retry / circuit-breaker reference (see [Β§6 Payload format](../../webhooks/index.md#6-payload-format)) - [Vendor watchlist recipe](../../webhooks/recipes/vendor-watchlist.md) β€” N-alerts pattern for tracking specific UEIs - [Awards by NAICS recipe](../../webhooks/recipes/awards-by-naics.md) β€” single alert across multiple NAICS codes --- --- description: "Index of task-oriented guides for the Tango API β€” getting started, cross-cutting patterns, and how-to recipes." tags: [api, guide] updated: 2026-09-21 --- # Guides Task-oriented walkthroughs for working with the Tango API. If you know what you want to *do*, start here. If you know what you want to *look up*, jump to the [API reference](../api-reference/index.md). ## Getting Started New to Tango? These get you to a working request fast. - [Quick start](../getting-started/quick-start.md) β€” your first API call in under five minutes - [Authentication](../getting-started/authentication.md) β€” API keys and OAuth2 - [Plans & pricing](../getting-started/pricing.md) β€” what each tier unlocks ## Patterns Cross-cutting techniques you'll use on every endpoint. - [Response shaping](patterns/response-shaping.md) β€” pick exactly the fields you want - [Pagination & result counts](patterns/result-counts.md) β€” cursor pagination, totals, large result sets - [Rate limits & retries](patterns/rate-limits.md) β€” what the headers tell you and how to back off - [Vehicles explained](patterns/vehicles.md) β€” IDVs, BPAs, GWACs, schedule contracts ## How-to recipes Specific jobs, end-to-end. - [Search opportunities by NAICS](how-to/search-opportunities-naics.md) - [Resolve free-text agency names](how-to/resolve-agency-names.md) - [Send opportunity updates to Slack](how-to/opportunity-updates-in-slack.md) - [Stream contract awards in real time](how-to/stream-awards.md) - [Migrate from USAspending bulk download](how-to/migrate-usaspending.md) - [Explore federal budget data](how-to/explore-federal-budget.md) β€” **Beta** ## Webhook recipes Filter-based webhook alerts (`/api/webhooks/alerts/`) β€” see also the [Webhooks user guide](../webhooks/index.md). - [Vendor watchlist](../webhooks/recipes/vendor-watchlist.md) - [Awards by NAICS](../webhooks/recipes/awards-by-naics.md) - [Track entity changes](../webhooks/recipes/track-entity-changes.md) - [Grants by agency](../webhooks/recipes/grants-by-agency.md) - [Forecast pipeline](../webhooks/recipes/forecast-pipeline.md) --- Looking for SDK-specific examples? See the [Python](../sdks/python/index.md) or [Node](../sdks/node/index.md) SDK docs. --- --- description: "How the agency filter (and its awarding_agency/funding_agency variants) resolves names, abbreviations, and codes to an organization subtree." tags: [agencies, search, api, guide] updated: 2026-10-30 --- # Agency search The `agency` filter (and its variants β€” `awarding_agency`, `funding_agency`) on every endpoint that exposes one is a **resolver**, not a substring search. You hand it any agency identifier β€” a name, abbreviation, code β€” and Tango figures out which `Organization` (and its hierarchy subtree) you meant. ## What it accepts A single agency identifier value, in any of these forms: | You pass | Example | Resolves to | | --- | --- | --- | | Abbreviation | `HHS`, `DOD`, `FDA` | The agency whose canonical short name matches | | Name (full or partial) | `Health and Human Services`, `Defense` | The closest matching agency by full-text / fuzzy name | | CGAC code (3-digit) | `075` | The L1 department | | FPDS sub-agency code (4-digit) | `7530` | The L2 agency under the matching department | | Federal Hierarchy key (fh_key) | `100004222` | The exact org row in `agencies_organization` | | AAC code | `87FCAB` | The org row whose AAC matches | You don't pick a "type". You just hand over the identifier you have, and Tango ranks candidates across multiple signal types (abbreviation > acronym > alternate name > hierarchy) plus direct field matches (CGAC, FPDS code, fh_key, name trigram). ## Multi-value OR (`|`) Use `|` to filter by multiple agencies at once. Each token is resolved **independently**, then results are the **union** of every token's subtree. ```http GET /api/contracts/?awarding_agency=HHS|DOD ``` Returns contracts awarded by anything under HHS *or* anything under DOD, as a flat list in the endpoint's default order. What `|` does **not** do: - It does **not** group results by token. - It does **not** preserve token order. - It is **not** "search by N inputs and merge with deduplication" β€” each token is an independent agency selection. If you need bucketed-by-agency results (e.g. `5 HHS contracts + 5 DOD contracts`), make N separate calls. A lopsided union (huge agency + tiny agency) buries the small one in pagination. ## Pagination The response shape is identical to a single-token query. Standard pagination fields (`count`, `next`, `previous`, `results`) apply to the union. ## Examples ### Single agency by abbreviation ```http GET /api/contracts/?awarding_agency=HHS&limit=5 ``` ### Single agency by FPDS code ```http GET /api/contracts/?awarding_agency=7530 ``` ### Two agencies (OR) ```http GET /api/contracts/?awarding_agency=HHS|DOD ``` ### Forecast filter with fh_key ```http GET /api/forecasts/?agency=100004222 ``` ### Mixed inputs You can mix forms across `|`-separated tokens β€” abbreviation in one, fh_key in the next, name in the third: ```http GET /api/opportunities/?agency=HHS|100000700|Treasury ``` Each token is resolved independently. ## Endpoints The same resolver is used wherever you see an agency filter: - `/api/contracts/` β€” `awarding_agency`, `funding_agency` - `/api/idvs/` β€” `awarding_agency`, `funding_agency` - `/api/otas/` β€” `awarding_agency`, `funding_agency` - `/api/otidvs/` β€” `awarding_agency`, `funding_agency` - `/api/subawards/` β€” `awarding_agency`, `funding_agency` - [`/api/assistance/grants/`](../../api-reference/assistance-grants.md#agencies), [`/api/assistance/loans/`](../../api-reference/assistance-loans.md#agencies), [`/api/assistance/direct_payments/`](../../api-reference/assistance-direct-payments.md#agencies), [`/api/assistance/other/`](../../api-reference/assistance-other.md#agencies) β€” `awarding_agency`, `funding_agency` - `/api/vehicles/` β€” `agency` - `/api/opportunities/` β€” `agency` - `/api/notices/` β€” `agency` - `/api/forecasts/` β€” `agency` - [`/api/news/award_announcements/`](../../api-reference/award-announcements.md) β€” `agency` - `/api/grants/` β€” `agency` - `/api/protests/` β€” `agency` For the per-endpoint filter list, see the relevant API reference page (e.g. [Contracts](../../api-reference/contracts.md)). ## See also - [Federal agency hierarchy](../../api-reference/concepts/federal-agency-hierarchy.md) β€” how Tango models L1 / L2 / L3 / sub-office relationships. - [Organizations API](../../api-reference/organizations.md) β€” direct access to the underlying `Organization` records. --- --- description: "How Tango's daily and burst rate-limit headers work, what a 429 response looks like, and how to back off and retry." tags: [performance, api, guide] updated: 2026-11-10 --- # Rate limits Tango enforces rate limits to keep the API fast and reliable for everyone. Limits apply at the **account level**: requests made via **API keys** and **OAuth2 tokens** for the same account all draw from the same quotas. **On a team, limits apply at the team level.** Every member's requests draw from the team's daily, burst, and premium quotas, the rate-limit headers report the team's remaining allowance, and a 429 says the limit is shared. See [Teams](../../getting-started/teams.md#how-limits-count-on-a-team). ## Where to see your limits and usage - **Your current plan limits + near-real-time usage**: [Account profile](https://tango.makegov.com/accounts/profile/) - **Upgrade pricing / higher limits**: [Pricing](https://tango.dev/subscriptions/pricing/) ## How rate limits work (burst + daily) Most plans have **more than one** rate limit window: - **Burst**: short window (e.g. per minute) that protects the API from sudden spikes - **Daily**: fixed window that resets at midnight UTC, caps total volume per day You may be β€œfine” on daily usage but still hit burst limits (or vice versa). ## Rate limit headers Every `/api/*` response includes rate limit headers. ### Overall headers (most restrictive window) These headers summarize the **most restrictive** window (the one you’re closest to hitting): - `X-RateLimit-Limit`: total requests allowed for that window - `X-RateLimit-Remaining`: requests remaining in that window - `X-RateLimit-Reset`: **seconds until reset** for that window ### Per-window headers (daily, burst, etc.) For each configured window (commonly `Daily` and `Burst`), you’ll also see: - `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining`, `X-RateLimit-Daily-Reset` - `X-RateLimit-Burst-Limit`, `X-RateLimit-Burst-Remaining`, `X-RateLimit-Burst-Reset` Each `*-Reset` value is **seconds until that specific window resets**. ### Quick header check (curl) ```bash curl -s -D - -o /dev/null \ -H "X-API-KEY: your-api-key-here" \ "https://tango.dev/api/contracts/?limit=1" ``` Example response headers: ```http X-RateLimit-Daily-Limit: 1500 X-RateLimit-Daily-Remaining: 1450 X-RateLimit-Daily-Reset: 18000 X-RateLimit-Burst-Limit: 100 X-RateLimit-Burst-Remaining: 95 X-RateLimit-Burst-Reset: 45 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 45 X-Execution-Time: 0.045s ``` Here `X-RateLimit-Daily-Reset: 18000` means there are 5 hours left in the current UTC day. It does **not** mean you have been throttled β€” it is simply how much of today is left. ## Understanding the daily reset The daily window is a **fixed calendar-day bucket, not a rolling 24 hours**. It refills at midnight UTC no matter when you started sending requests. This has one consequence worth planning around: **`X-RateLimit-Daily-Reset` tells you how much of the current UTC day is left, so the wait you get after exhausting your daily quota depends on *when* you exhaust it.** - Exhaust your daily quota at **19:00 UTC** and you wait **~5 hours** for the reset. - Exhaust the very same quota at **02:00 UTC** and you wait **~22 hours**. Midnight UTC is **8:00 PM Eastern** (Mar–Nov) or **7:00 PM Eastern** (Nov–Mar). If you run in a US timezone, your quota therefore refills in the evening and is spent over the course of the business day β€” so a heavy morning can leave you throttled for the rest of the afternoon. If you have a large daily batch job, running it just **after** the midnight-UTC reset gives it the full day's quota to draw from. ## Premium query limits (select endpoints) Some endpoint families carry their own **premium query budget** instead of your account-wide limits. A request to one of those endpoints draws from that budget and does not count against your daily or per-minute allowance. ### How premium limits work - **Separate budget**: The premium budget exists only for designated endpoint families. Standard endpoints use your account-wide quotas. - **Replaces your standard limits**: on these endpoints the premium budget is the only limit that applies β€” your daily and per-minute quotas are neither checked nor spent. - **Shared across endpoint family**: Multiple endpoints may share a single premium counter. For example, the CALC labor-rate endpoints (`GET /api/idvs/{key}/lcats/` and `GET /api/entities/{uei}/lcats/`) share one premium budget. - **Counts requests, not rows**: Each API call costs one request, regardless of pagination or the number of rows returned. - **Fixed daily window**: The premium budget resets daily at **00:00 UTC**. ### Premium headers On responses from endpoints with a premium budget (including 429s), you'll see: - `X-RateLimit-Premium-Limit`: total requests allowed in the premium budget - `X-RateLimit-Premium-Remaining`: requests remaining in the premium budget - `X-RateLimit-Premium-Reset`: **seconds until reset** for the premium budget These headers appear **only** on requests to endpoints with a premium budget β€” they are absent everywhere else. ### Finding your premium limits Check your [account profile](https://tango.makegov.com/accounts/profile/) to see your current premium usage and limits per endpoint family. To request a higher limit, email [hello@makegov.com](mailto:hello@makegov.com). ## What happens when you exceed a limit (HTTP 429) When you hit a rate limit, Tango responds with **HTTP 429** and a JSON body like: ```json { "detail": "Rate limit exceeded for burst. Please try again in 45 seconds.", "wait_in_seconds": 45 } ``` ### Recommended client behavior - **Stop retrying immediately** after a 429. - Sleep for **at least** `wait_in_seconds` (preferred) or `X-RateLimit-Reset`. - But **cap how long you are willing to sleep.** A *burst* 429 clears in under a minute; a *daily* 429 can report a wait of many hours (however much of the UTC day is left). Blindly sleeping on that value will park your process until the small hours. Treat a multi-hour wait as "daily quota exhausted" β€” log it, alert, and stop, rather than sleeping through it. - Then retry with **exponential backoff + jitter** to avoid a thundering herd. #### Python example ```python import random import time import httpx url = "https://tango.dev/api/contracts/?limit=1" headers = {"X-API-KEY": "your-api-key-here"} # Never block the process for hours. A burst 429 clears in under a minute, but # a *daily* 429 can report a wait of many hours (until midnight UTC) β€” that is # a quota problem to surface, not to sleep through. MAX_SLEEP_SECONDS = 120 backoff = 1.0 for _ in range(10): r = httpx.get(url, headers=headers) if r.status_code != 429: r.raise_for_status() break body = r.json() wait = body.get("wait_in_seconds") if wait is None: wait = r.headers.get("X-RateLimit-Reset") if wait is not None: wait = float(wait) if wait > MAX_SLEEP_SECONDS: raise RuntimeError( f"Daily quota exhausted; resets in {wait / 3600:.1f}h " f"(midnight UTC). Upgrade your plan or retry after the reset." ) time.sleep(wait) continue time.sleep(backoff + random.random()) backoff = min(backoff * 2, 60) ``` #### JavaScript example This example assumes `fetch` is available (modern browsers or Node 18+). ```javascript (async () => { const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); const url = "https://tango.dev/api/contracts/?limit=1"; const headers = { "X-API-KEY": "your-api-key-here" }; // Never block for hours. A burst 429 clears in under a minute, but a *daily* // 429 can report a wait of many hours (until midnight UTC) β€” that is a quota // problem to surface, not to sleep through. const MAX_SLEEP_SECONDS = 120; let backoffMs = 1000; for (let i = 0; i < 10; i++) { const r = await fetch(url, { headers }); if (r.status !== 429) { if (!r.ok) throw new Error(`HTTP ${r.status}`); break; } const body = await r.json(); const wait = body.wait_in_seconds ?? r.headers.get("X-RateLimit-Reset"); if (wait != null) { const waitSeconds = Number(wait); if (waitSeconds > MAX_SLEEP_SECONDS) { throw new Error( `Daily quota exhausted; resets in ${(waitSeconds / 3600).toFixed(1)}h ` + `(midnight UTC). Upgrade your plan or retry after the reset.`, ); } await sleep(waitSeconds * 1000); continue; } await sleep(backoffMs + Math.random() * 250); backoffMs = Math.min(backoffMs * 2, 60_000); } })().catch((err) => { console.error("Request failed:", err); }); ``` ## Reduce calls (and avoid limits) in practice - Use **response shaping** (`shape=`) to avoid extra β€œfollow-up” requests. See the [Response Shaping Guide](response-shaping.md). - Paginate responsibly; avoid re-fetching the same pages repeatedly. - Cache hot lookups on your side when appropriate (e.g. β€œentity by UEI”). - Prefer webhooks for event-driven updates instead of polling where possible. --- --- description: "The shape query parameter syntax for selecting fields and expansions on Tango endpoints, plus per-endpoint field references." tags: [shaping, api, guide] updated: 2026-11-03 --- # Response Shaping (Custom Fields) Tango’s API lets you request only the fields you want by passing a `shape` query parameter. Shaped responses are built directly from your selection for speed and consistency. If you omit `shape`, the endpoint returns the default serializer output. ## Endpoints with shaping - Agencies (legacy lookups): - Departments: `/api/departments/` - Agencies: `/api/agencies/` - Offices: `/api/offices/` - Reference data: - Business Types: `/api/business_types/` - NAICS: `/api/naics/` - PSC: `/api/psc/` - Assistance Listings: `/api/assistance_listings/` - MAS SINs: `/api/mas_sins/` - Awards (canonical routes): - Contracts: `/api/contracts/` - IDVs: `/api/idvs/` - OTAs: `/api/otas/` - OTIDVs: `/api/otidvs/` - Subawards: `/api/subawards/` - Vehicles: `/api/vehicles/` - GSA eLibrary Contracts: `/api/gsa_elibrary_contracts/` - CALC Rates (nested): `/api/idvs/{key}/lcats/`, `/api/entities/{uei}/lcats/` - Financial assistance: - Grants: `/api/assistance/grants/` - Loans: `/api/assistance/loans/` - Direct payments: `/api/assistance/direct_payments/` - Other assistance: `/api/assistance/other/` - Subgrants: `/api/assistance/subgrants/` - Organizations: `/api/organizations/` - Entities: `/api/entities/` - Exclusions: `/api/exclusions/` - Forecasts: `/api/forecasts/` - Grants: `/api/grants/` - IT Dashboard: `/api/itdashboard/` - Opportunities (canonical routes): - Opportunities: `/api/opportunities/` - Opportunity Notices: `/api/notices/` - SBIR/STTR: - Topics: `/api/sbir/topics/` - Solicitations: `/api/sbir/solicitations/` - DIBBS: - RFQs: `/api/dibbs/rfqs/` - Solicitations (RFP/IFB): `/api/dibbs/rfps/` - Awards: `/api/dibbs/awards/` - State & Local (Beta): - Solicitations: `/api/sled/opportunities/` - Forecasts: `/api/sled/forecasts/` - Protests: `/api/protests/` - Contract appeals: `/api/contract_appeals/` - Federal Register: `/api/federal_register/` - Award announcements: `/api/news/award_announcements/` - eBuy: `/api/ebuy/requests/` All standard filters, ordering, pagination, throttling, and rate‑limit headers still apply. ## Shape syntax - Root leaves: `key,piid,award_date` - Expansions (related objects): `recipient(display_name,uei)` - Multiple items: `key,piid,recipient(display_name),awarding_office(office_code,office_name)` - Star in child selections: `recipient(*)` returns all allowed fields of `recipient` - Aliasing: `field::alias` or `child(field::alias)` - Bracket parameters: `expand[key=value](children)` β€” pass configuration to an expansion ### Bracket parameters Some expansions accept parameters via bracket syntax. Parameters go between the expansion name and the child selection: ```bash # Top 10 agencies in past_performance /api/entities/?shape=uei,past_performance[top=10](*) # Multiple params (comma-separated) /api/entities/?shape=uei,past_performance[top=3](summary,top_agencies) ``` Parameters are validated server-side with type checking and range enforcement. Unknown or out-of-range parameters return a 400 error with details. ### Leaves vs expansions In the shape DSL there are two different kinds of selections: - **Leaf**: `field_name` - **Expansion**: `expand_name(child1,child2,...)` Some endpoints expose the **same name** as both a leaf and an expansion. In those cases, the API will keep the selection as a **leaf** unless the shaping runtime determines that treating the token as a leaf would be unsafe (see β€œBare expansions” below). Example (Opportunities set-aside): ```bash # Leaf (code string) /api/opportunities/?shape=opportunity_id,title,set_aside # Expansion (structured form) /api/opportunities/?shape=opportunity_id,title,set_aside(code,description) ``` ### Bare expansions (shorthand) If you write an expansion name **without** parentheses, e.g. `office` instead of `office(*)`, Tango will sometimes treat it as shorthand for `office(*)`. This shorthand is applied **only when needed for safety**: - when the expansion is a relation fetched via a database join, or - when the expansion is a β€œvirtual” expansion that reads its values from the parent object, **unless** the value is field-map-backed. Examples (Notices): ```bash # Bare expansions: office == office(*), opportunity == opportunity(*) /api/notices/?shape=notice_id,opportunity_id,office,opportunity&limit=1 ``` Example response (shape excerpt): ```json [ { "notice_id": "d2e3f9bf-9c2e-4c58-84f1-2b2b8a1d3b4d", "opportunity_id": "ff12a2d0-3b8a-4a1d-8d7f-7d8c2b6c0a11", "office": { "organization_id": "f3ab8e7c-6c2d-4e8e-9f1a-2b3c4d5e6f70", "office_code": "W91QF5", "office_name": "ACC-APG", "agency_code": "9700", "agency_name": "DEPT OF THE ARMY", "department_code": "97", "department_name": "DEPARTMENT OF DEFENSE" }, "opportunity": { "opportunity_id": "ff12a2d0-3b8a-4a1d-8d7f-7d8c2b6c0a11", "link": "/api/opportunities/ff12a2d0-3b8a-4a1d-8d7f-7d8c2b6c0a11/" } } ] ``` Examples: ```bash # Basic /api/contracts/?shape=key,piid,recipient(display_name) # Aliasing /api/contracts/?shape=key::id,recipient(display_name::name) # Star in nested expansion /api/contracts/?shape=key,recipient(*),transactions(*) ``` Child field aliasing inside an expand: ```bash /api/contracts/?shape=key,awarding_office(agency_name::foo) ``` Response: ```json [ { "key": "CONT_AWD_...", "awarding_office": { "foo": "General Services Administration" } } ] ``` Notes: - `*` is only valid inside a child selection (e.g., `recipient(*)`). Root‑level `*` is not supported. - Shaping requests that include unknown fields/expands, malformed shapes, or `shape` on non-shaping endpoints return a 400 with a structured error payload. ### Flattening Add `flat=true` to flatten nested objects with a joiner (default `.`). Works with both paginated and single‑object responses. ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/contracts/?shape=key,recipient(display_name)&flat=true&joiner=." ``` Response: ```json [ { "key": "CONT_AWD_...", "recipient.display_name": "ACME CORP" } ] ``` Notes: - Flattening applies to nested objects (dicts). Lists remain arrays for readability and stability by default. Expansions like `relationships` (entities) and `attachments` (opportunities/notices) will remain arrays of objects even when `flat=true`. - Optional: `flat_lists=true` will additionally flatten lists of objects into indexed keys (e.g., `relationships.0.uei`). This is opt‑in and defaults to `false`. Examples: ```bash # Flatten dicts only (default list behavior) /api/entities/?shape=uei,relationships(uei,display_name)&flat=true # Also flatten list elements into indexed keys /api/entities/?shape=uei,relationships(uei,display_name)&flat=true&flat_lists=true&joiner=. ``` ## Validation & limits - Unknown fields or expansions return a 400 with structured issues. - Malformed shapes (syntax errors) return a 400 with a `parse_error` issue. - Passing `shape` to an endpoint that does not support shaping returns a 400 (instead of ignoring `shape`). - Default limits (subject to change): - `SHAPE_MAX_DEPTH` = 2 - `SHAPE_MAX_FIELDS` = 64 (for user-supplied `?shape=` params; server-controlled default shapes may exceed this) Example errors: ```json { "error": "Invalid shape", "issues": [{"path": "foo", "reason": "unknown_field"}], "available_fields": { "fields": ["award_date", "key", "piid", "recipient"], "expands": {"recipient": {"fields": ["uei", "display_name"], "expands": {}, "wildcard_fields": false}}, "wildcard_fields": false } } ``` ```json { "error": "Invalid shape", "issues": [{"path": "$", "reason": "parse_error (Unclosed '(')"}], "available_fields": { "fields": ["award_date", "key", "piid", "recipient"], "expands": {"recipient": {"fields": ["uei", "display_name"], "expands": {}, "wildcard_fields": false}}, "wildcard_fields": false } } ``` ```json { "error": "Invalid shape value(s): foo. Shaping is not available for /api/example/.", "issues": [{"path": "$", "reason": "shape_not_supported"}] } ``` ## Discovering available fields Every shaped endpoint supports `?show_shapes=true` for schema discovery. Truthy values: `true`, `1`, `yes`, `on`. It works in two modes: ### Schema-only (no `?shape=`) Pass `?show_shapes=true` without a `?shape=` parameter to get just the schema β€” no data is fetched, no DB query is made: ```bash /api/contracts/?show_shapes=true ``` ```json { "available_fields": { "fields": ["award_date", "awarding_office", "description", "key", "naics_code", "piid", "recipient", "transactions"], "expands": { "awarding_office": {"fields": ["organization_id", "agency_code", "agency_name", "office_code", "office_name", "department_code", "department_name"], "expands": {}, "wildcard_fields": false}, "recipient": {"fields": ["cage_code", "display_name", "legal_business_name", "uei"], "expands": {}, "wildcard_fields": false}, "transactions": {"fields": ["action_type", "description", "modification_number", "obligated", "transaction_date"], "expands": {}, "wildcard_fields": false} }, "wildcard_fields": false } } ``` ### Schema appended to data (with `?shape=`) Pass both `?shape=...` and `?show_shapes=true` to get the normal shaped response with a `_shaping` block appended: ```bash /api/contracts/?shape=key,piid&show_shapes=true ``` ```json { "count": 1234, "next": "...", "previous": null, "results": [ {"key": "CONT_AWD_...", "piid": "GS00Q14OADS134"} ], "_shaping": { "available_fields": { "fields": ["award_date", "awarding_office", "description", "key", "naics_code", "piid", "recipient", "transactions"], "expands": { "awarding_office": {"fields": ["organization_id", "agency_code", "agency_name", "office_code", "office_name", "department_code", "department_name"], "expands": {}, "wildcard_fields": false}, "recipient": {"fields": ["cage_code", "display_name", "legal_business_name", "uei"], "expands": {}, "wildcard_fields": false}, "transactions": {"fields": ["action_type", "description", "modification_number", "obligated", "transaction_date"], "expands": {}, "wildcard_fields": false} }, "wildcard_fields": false } } } ``` ### Schema structure Each level of the schema contains: | Key | Type | Meaning | | --- | --- | --- | | `fields` | array | All valid shape keys at this level, including both leaf fields and expand names. | | `expands` | object | Expandable relations, each containing its own nested `{fields, expands, wildcard_fields}` schema. | | `wildcard_fields` | boolean | When `true`, the expansion accepts any field name (i.e., `expand(*)` returns all keys from the underlying data, and you can also request arbitrary keys by name). When `false`, only the fields listed in `fields` are valid. Most endpoints return `false`; `wildcard_fields: true` appears on expansions backed by freeform JSON (e.g., `raw_data(*)` on forecasts). | Notes: - Schema-only mode (`?show_shapes=true` alone) makes no DB queries β€” safe to call frequently. - `_shaping` is appended after `results` in paginated responses and after all other keys in detail responses, so existing clients that ignore unknown keys are unaffected. - All 400 error responses for invalid shapes also include `available_fields` at the top level (no `?show_shapes` needed). ## Date/time formatting All datetimes in shaped responses are formatted using a consistent ISO‑8601 format. ## Identity fallback for missing relations When an expanded relation is missing (e.g., a join yields no row), the API returns a minimal identity object using the relation's key value instead of `null`: ```json { "parent_award": {"key": "PARENT-123"} } ``` ## Field reference by endpoint (excerpt) Below is a concise reference of commonly used fields and expansions per endpoint. Use `(*)` inside an expansion to request all allowed fields for that relation. ### Departments `/api/departments/` - Leaves: `code`, `name`, `abbreviation`, `description`, `cgac`, `website`, `congressional_justification` - No expansions. Default response (no `?shape=`): `code,name,abbreviation` ```bash # Select specific fields /api/departments/?shape=code,name # Extended department info /api/departments/?shape=code,name,description,cgac,website,congressional_justification ``` ### Agencies `/api/agencies/` - Leaves: `code`, `name`, `abbreviation` - Expansions: - `department(code,name,abbreviation,description,cgac,website,congressional_justification)` Default response (no `?shape=`): `code,name,abbreviation,department(name,code)` ```bash # Just codes and names /api/agencies/?shape=code,name # Include department info /api/agencies/?shape=code,name,department(name,code) # Department with extended fields /api/agencies/?shape=code,department(name,description,cgac,website) # All department fields /api/agencies/?shape=code,department(*) ``` ### Offices `/api/offices/` - Leaves: `code`, `name`, plus flat aliases `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name` - Expansions: - `agency(code,name,abbreviation)` - `department(code,name,abbreviation,description,cgac,website,congressional_justification)` Default response (no `?shape=`): `office_code,office_name,agency_code,agency_name,department_code,department_name` (flat aliases) ```bash # Default flat format /api/offices/?shape=office_code,office_name,agency_name # Direct leaves with nested expansions /api/offices/?shape=code,name,agency(code,name,abbreviation) # Office with department details /api/offices/?shape=code,name,department(name,description,website) # Both expansions /api/offices/?shape=code,name,agency(code,name),department(code,name) ``` ### Business Types `/api/business_types/` - Leaves: `name`, `code` - No expansions. Default response (no `?shape=`): `name,code` ```bash # Select a single field /api/business_types/?shape=name ``` ### NAICS `/api/naics/` - Leaves: `code`, `description` - Expansions: - `size_standards(employee_limit,revenue_limit)` β€” SBA size standards for this NAICS code. `revenue_limit` is in whole dollars (e.g., `2250000`). - `federal_obligations(total,active)` β€” obligation rollups. Each sub-object contains `awards_obligated` (float) and `awards_count` (int). Default response (list, no `?shape=`): `code,description` Default response (detail or `show_limits=1`): `code,description,size_standards(*),federal_obligations(*)` **Note:** The legacy `?show_limits=1` parameter is still supported β€” it triggers the same response as `?shape=code,description,size_standards(*),federal_obligations(*)`. Prefer using `?shape=` directly. ```bash # List with just code and description (default) /api/naics/?shape=code,description # Include size standards and obligations (equivalent to ?show_limits=1) /api/naics/?shape=code,description,size_standards(*),federal_obligations(*) # Size standards only /api/naics/541330/?shape=code,description,size_standards(employee_limit,revenue_limit) # Obligations total only /api/naics/541330/?shape=code,federal_obligations(total) ``` ### PSC `/api/psc/` - Leaves: `code`, `parent`, `category`, `level_1_category`, `level_1_category_code`, `level_2_category`, `level_2_category_code` - Expansions: - `current(name,active,start_date,end_date,description,includes,excludes)` β€” active or latest description - `historical(name,active,start_date,end_date,description,includes,excludes)` β€” all descriptions Default response (no `?shape=`): `code,current(*),parent,category,level_1_category,level_1_category_code,level_2_category,level_2_category_code` ```bash # Just code and current description name /api/psc/?shape=code,current(name) # Code with current and historical descriptions /api/psc/AD12/?shape=code,current(name,active),historical(name,active) ``` ### Assistance Listings `/api/assistance_listings/` - Leaves: `number`, `title`, `published_date`, `archived_date`, `popular_name`, `objectives`, `applicant_eligibility`, `benefit_eligibility` - No expansions. Default response (list, no `?shape=`): `number,title` **Note:** Detail responses (`/api/assistance_listings/{number}/`) use the full serializer (includes all fields) when no `?shape=` param is provided. ```bash # Include extra fields /api/assistance_listings/?shape=number,title,objectives # Detail with specific fields /api/assistance_listings/10.001/?shape=number,title,objectives,popular_name ``` ### MAS SINs `/api/mas_sins/` - Leaves: `sin`, `large_category_code`, `large_category_name`, `sub_category_code`, `sub_category_name`, `psc_code`, `state_local`, `set_aside_code`, `service_comm_code`, `expiration_date`, `tdr`, `olm`, `naics_codes`, `title`, `description` - No expansions. Default response (no `?shape=`): all 15 fields above. ```bash # Select a subset of fields /api/mas_sins/?shape=sin,title,description ``` ### Organizations `/api/organizations/` Organizations uses a default shape β€” all responses go through the shaping pipeline even without `?shape=`. - Default shape: `key,fh_key,name,short_name,type,level,is_active,code,fpds_code,cgac,canonical_code,parent_fh_key,full_parent_path_name` - Additional leaves: `fpds_org_id`, `aac_code`, `start_date`, `end_date`, `logo`, `summary`, `l1_fh_key` through `l8_fh_key`, `total_obligations`, `tree_obligations`, `mod_status`, `description`, `obligations`, `obligation_rank` - Expansions: - `parent(key,fh_key,name,short_name,type,level,is_active,code,cgac)` - `ancestors(fh_key,name,short_name,level)` - `children(key,fh_key,name,short_name,type,level,is_active,code,cgac)` - `department(code,name,abbreviation)` - `agency(code,name,abbreviation)` ```bash # Default response (all responses are shaped) /api/organizations/ # Select specific fields /api/organizations/?shape=fh_key,name,type,level # Include department and agency expands /api/organizations/?shape=fh_key,name,department(code,name),agency(code,name,abbreviation) ``` ### Contracts `/api/contracts/` - Leaves: `key`, `piid`, `award_date`, `naics_code`, `psc_code`, `total_contract_value`, `description`, `base_and_exercised_options_value`, `fiscal_year`, `obligated`, `set_aside`, `award_type`, `transactions`, `subawards_summary` - Expansions: - `recipient(uei,display_name,legal_business_name,cage,cage_code,...)` - `awarding_office(organization_id,office_code,office_name,agency_code,agency_name,department_code,department_name)` - `funding_office(...)` β€” same 7-key shape as `awarding_office` - `place_of_performance(country_code,country_name,state_code,state_name,city_name,zip_code)` - `parent_award(key,piid)` - `period_of_performance(start_date,current_end_date,ultimate_completion_date)` - `transactions(modification_number,transaction_date,obligated,description,action_type)` - `subawards_summary(count,total_amount)` - `competition(contract_type,extent_competed,number_of_offers_received,other_than_full_and_open_competition,solicitation_date,solicitation_identifier,solicitation_procedures)` - `officers(highly_compensated_officer_1_name,highly_compensated_officer_1_amount,highly_compensated_officer_2_name,highly_compensated_officer_2_amount,highly_compensated_officer_3_name,highly_compensated_officer_3_amount,highly_compensated_officer_4_name,highly_compensated_officer_4_amount,highly_compensated_officer_5_name,highly_compensated_officer_5_amount)` – returns `null` if no officers are on record. Not included in default serializers; available only via shaping. Examples: ```bash # Minimal contract fields /api/contracts/?shape=key,piid,award_date # Recipient and awarding office /api/contracts/?shape=key,recipient(display_name),awarding_office(office_code,office_name) # Period and transactions /api/contracts/?shape=key,period_of_performance(start_date,current_end_date),transactions(modification_number,obligated) # Officers (subset) /api/contracts/?shape=key,officers(highly_compensated_officer_1_name,highly_compensated_officer_1_amount) # Officers (all allowed fields) /api/contracts/?shape=key,officers(*) ``` ### IDVs `/api/idvs/` - Leaves: `key`, `piid`, `vehicle_uuid`, `solicitation_identifier`, `award_date`, `naics_code`, `psc_code`, `total_contract_value`, `description`, `fiscal_year`, `obligated`, `idv_type`, `multiple_or_single_award_idv`, `type_of_idc`, `set_aside`, `transactions`, `subawards_summary` - Detail-only leaves: `commercial_item_acquisition_procedures`, `consolidated_contract`, `contingency_humanitarian_or_peacekeeping_operation`, `contract_bundling`, `contract_financing`, `cost_accounting_standards_clause`, `cost_or_pricing_data`, `dod_acquisition_program`, `dod_transaction_number`, `domestic_or_foreign_entity`, `email_address`, `epa_designated_product`, `evaluated_preference`, `fair_opportunity_limited_sources`, `fed_biz_opps`, `fee_range_lower_value`, `fee_range_upper_value`, `fixed_fee_value`, `foreign_funding`, `government_furnished_property`, `idv_website`, `inherently_governmental_functions`, `local_area_set_aside`, `major_program`, `number_of_actions`, `number_of_offers_source`, `ordering_procedure`, `performance_based_service_acquisition`, `program_acronym`, `recovered_materials_sustainability`, `research`, `sam_exception`, `simplified_procedures_for_certain_commercial_items`, `small_business_competitiveness_demonstration_program`, `subcontracting_plan`, `total_estimated_order_value`, `tradeoff_process`, `type_of_fee_for_use_of_service`, `undefinitized_action`, `who_can_use` - Expansions: - `recipient(uei,display_name,legal_business_name,cage,cage_code,...)` - `awarding_office(organization_id,office_code,office_name,agency_code,agency_name,department_code,department_name)` - `funding_office(...)` β€” same 7-key shape as `awarding_office` - `place_of_performance(country_code,country_name,state_code,state_name,city_name,zip_code)` - `parent_award(key,piid)` - `period_of_performance(start_date,last_date_to_order)` β€” note: uses `last_date_to_order` instead of contracts' `current_end_date`/`ultimate_completion_date` - `transactions(modification_number,transaction_date,obligated,description,action_type)` - `subawards_summary(count,total_amount)` - `idv_type(code,description)` β€” IDV type as structured code/description - `multiple_or_single_award_idv(code,description)` β€” single/multiple award designation - `type_of_idc(code,description)` β€” IDC type as structured code/description - `set_aside(code,description)` β€” set-aside type - `naics(code,description)` β€” resolved NAICS lookup - `psc(code,description)` β€” resolved PSC lookup - `competition(contract_type,extent_competed,number_of_offers_received,other_than_full_and_open_competition,solicitation_date,solicitation_identifier,solicitation_procedures)` - `officers(...)` β€” same fields as contracts; `null` when absent; shaping-only - `awards(key,piid,award_date,naics_code,psc_code,total_contract_value,description,base_and_exercised_options_value,fiscal_year,obligated,transactions)` β€” child awards under this IDV - `gsa_elibrary(schedule,contract_number,uei,sins,cooperative_purchasing,disaster_recovery_purchasing,file_urls,extracted_text,external_id,source_data)` β€” GSA eLibrary enrichment (`null` when no match) - `legislative_mandates(...)` β€” legislative mandate flags Default response (list, no `?shape=`): `award_date,awarding_office(*),description,fiscal_year,funding_office(*),gsa_elibrary(*),idv_type(*),key,legislative_mandates(*),multiple_or_single_award_idv(*),naics_code,obligated,parent_award(*),period_of_performance(*),piid,place_of_performance(*),psc_code,recipient(*),set_aside,solicitation_identifier,subawards_summary(*),total_contract_value,type_of_idc(*),vehicle_uuid` Default response (detail): adds all detail-only leaves plus `competition(*)` and `officers(*)` ```bash # Minimal IDV fields /api/idvs/?shape=key,piid,award_date # Expand idv_type to get code + description /api/idvs/?shape=key,piid,idv_type(code,description) # IDV with recipient and awarding office /api/idvs/?shape=key,piid,recipient(display_name,uei),awarding_office(office_name,agency_name) # Period of performance with last_date_to_order /api/idvs/?shape=key,piid,period_of_performance(start_date,last_date_to_order) # GSA eLibrary enrichment /api/idvs/?piid=GS-35F-0001X&shape=key,piid,gsa_elibrary(schedule,contract_number,sins,file_urls) # Child awards under an IDV /api/idvs/{key}/?shape=key,piid,awards(key,piid,total_contract_value) ``` ### Vehicles `/api/vehicles/` - Leaves: `uuid`, `solicitation_identifier`, `agency_id`, `organization_id`, `vehicle_type`, `fiscal_year`, `agency_details`, `descriptions`, `competition_details`, `type_of_idc`, `contract_type`, `awardee_count`, `order_count`, `vehicle_obligations`, `vehicle_contracts_value`, `solicitation_title`, `solicitation_description`, `solicitation_date`, `naics_code`, `psc_code`, `set_aside` - Expansions: - `awardees(...)`: expands to the underlying IDVs that make up the vehicle - `opportunity(...)`: expands to the linked SAM.gov Opportunity (supports all Opportunity fields and expansions like `office`, `attachments`, `meta`) - `competition_details(...)`: expands the `competition_details` JSON object (fields: `extent_competed`, `number_of_offers_received`, `set_aside`, `solicitation_procedures`, etc., or `*` for all) Default response (list, no `?shape=`): `agency_details,award_date,awardee_count,competition_details(*),contract_type,description,fiscal_year,last_date_to_order,latest_award_date,naics_code,order_count,psc_code,set_aside,solicitation_date,solicitation_identifier,solicitation_title,type_of_idc,uuid,vehicle_contracts_value,vehicle_obligations,vehicle_type,who_can_use` Default response (detail): adds `agency_id`, `organization_id`, `solicitation_description` Notes: - `GET /api/vehicles/?search=...` performs **vehicle-level** full-text search. - On `GET /api/vehicles/{uuid}/`, `?search=` is reserved for filtering expanded `awardees(...)` (it does not filter the vehicle itself). - Opportunity-derived fields (`solicitation_title`, `solicitation_description`, `solicitation_date`, `naics_code`, `psc_code`, `set_aside`) are populated from the linked SAM.gov Opportunity's latest notice when available. Examples: ```bash # Find vehicles by term /api/vehicles/?search=schedule # Vehicle detail + shaped award expansion /api/vehicles//?shape=uuid,solicitation_identifier,awardees(key,uuid,piid,award_date,recipient(display_name,uei)) # Include opportunity-derived fields /api/vehicles//?shape=uuid,solicitation_identifier,solicitation_title,solicitation_date,naics_code,psc_code # Expand linked Opportunity with office details /api/vehicles//?shape=uuid,solicitation_identifier,opportunity(opportunity_id,title,first_notice_date,office(office_name,agency_name)) # Expand JSON detail fields to select specific sub-fields /api/vehicles//?shape=uuid,competition_details(extent_competed,number_of_offers_received),type_of_idc,contract_type # Filter expanded awards within a vehicle /api/vehicles//?shape=uuid,awardees(key,uuid,recipient(display_name))&search=acme ``` ### OTAs `/api/otas/` - Leaves: `key`, `piid`, `award_date`, `psc_code`, `total_contract_value`, `description`, `base_and_exercised_options_value`, `fiscal_year`, `obligated`, `award_type`, `type_of_ot_agreement`, `extent_competed`, `consortia`, `consortia_uei`, `dod_acquisition_program`, `non_governmental_dollars`, `non_traditional_government_contractor_participation`, `parent_award_modification_number`, `transactions` - Expansions: - `recipient(uei,display_name,legal_business_name,cage,cage_code,...)` - `awarding_office(organization_id,office_code,office_name,agency_code,agency_name,department_code,department_name)` - `funding_office(...)` β€” same 7-key shape as `awarding_office` - `place_of_performance(country_code,country_name,state_code,state_name,city_name,zip_code)` - `parent_award(key,piid)` - `period_of_performance(start_date,current_end_date,ultimate_completion_date)` - `transactions(modification_number,transaction_date,obligated,description,action_type)` - `psc(code,description)` - `award_type(code,description)` β€” OTA-specific choices ("O" = Other Transaction Non-Research, "R" = Other Transaction for Research) - `type_of_ot_agreement(code,description)` - `extent_competed(code,description)` Default response (no `?shape=`): `award_date,award_type,awarding_office(*),base_and_exercised_options_value,consortia,consortia_uei,dod_acquisition_program,extent_competed,fiscal_year,funding_office(*),key,non_governmental_dollars,non_traditional_government_contractor_participation,parent_award(key,piid),parent_award_modification_number,period_of_performance(start_date,current_end_date,ultimate_completion_date),piid,place_of_performance(*),psc_code,recipient(*),type_of_ot_agreement` **Note:** OTAs have no `naics_code` field and no `naics` expand. ```bash # Minimal OTA fields /api/otas/?shape=key,piid,award_date # Expand award_type to get OTA-specific code + description /api/otas/?shape=key,piid,award_type(code,description) # Expand extent competed and type of OT agreement /api/otas/?shape=key,piid,extent_competed(code,description),type_of_ot_agreement(code,description) # OTA with recipient and awarding office /api/otas/?shape=key,piid,recipient(display_name,uei),awarding_office(office_name,agency_name) ``` ### OTIDVs `/api/otidvs/` - Leaves: `key`, `piid`, `award_date`, `psc_code`, `total_contract_value`, `description`, `base_and_exercised_options_value`, `fiscal_year`, `obligated`, `idv_type`, `type_of_ot_agreement`, `extent_competed`, `consortia`, `consortia_uei`, `dod_acquisition_program`, `non_governmental_dollars`, `non_traditional_government_contractor_participation`, `transactions` - Expansions: - `recipient(uei,display_name,legal_business_name,cage,cage_code,...)` - `awarding_office(organization_id,office_code,office_name,agency_code,agency_name,department_code,department_name)` - `funding_office(...)` β€” same 7-key shape as `awarding_office` - `place_of_performance(country_code,country_name,state_code,state_name,city_name,zip_code)` - `period_of_performance(start_date,current_end_date,ultimate_completion_date)` - `transactions(modification_number,transaction_date,obligated,description,action_type)` - `psc(code,description)` - `type_of_ot_agreement(code,description)` - `extent_competed(code,description)` Default response (no `?shape=`): `award_date,awarding_office(*),base_and_exercised_options_value,consortia,consortia_uei,dod_acquisition_program,extent_competed,fiscal_year,funding_office(*),idv_type,key,non_governmental_dollars,non_traditional_government_contractor_participation,period_of_performance(start_date,current_end_date,ultimate_completion_date),piid,place_of_performance(*),psc_code,recipient(*),type_of_ot_agreement` **Note:** OTIDVs have no `naics_code` field, no `naics` expand, and no `parent_award` expand. ```bash # Minimal OTIDV fields /api/otidvs/?shape=key,piid,award_date # Expand extent competed and type of OT agreement /api/otidvs/?shape=key,piid,extent_competed(code,description),type_of_ot_agreement(code,description) # OTIDV with recipient /api/otidvs/?shape=key,piid,recipient(display_name,uei),awarding_office(office_name,agency_name) ``` ### Subawards `/api/subawards/` Subawards use a default shape β€” all responses go through the shaping pipeline even without `?shape=`. - Default response (no `?shape=`): `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)` - Leaves: `key` (the report UUID), `award_key`, `piid`, the three UEIs (`prime_awardee_uei`, `recipient_uei`, `recipient_parent_uei`) and their entity ids (`prime_recipient_id`, `recipient_id`, `recipient_parent_id`), `place_of_performance_id`, `pop_cd_original`, `pop_cd_current`, `amount_suspect`, `retired_at`, `usaspending_permalink` - Expansions: - `subaward_details(description,type,number,amount,action_date,fiscal_year)` - `fsrs_details(last_modified_date,id,year,month)` - `place_of_performance(city,state,zip,country_code)`, from the shared place record - `highly_compensated_officers(name,amount)` - `prime_recipient(uei,display_name)`, `subaward_recipient(uei,display_name,duns)`, from the entity records - `awarding_office(*)`, `funding_office(*)` ```bash # Default response (shaped automatically) /api/subawards/ # Select specific fields /api/subawards/?shape=key,piid,subaward_details(*) # Recipient and office info /api/subawards/?shape=key,prime_recipient(uei,display_name),awarding_office(*) ``` ### Subgrants `/api/assistance/subgrants/` Subgrants use a default shape β€” all responses go through the shaping pipeline even without `?shape=`. The shape is the subaward one with `fain` and `assistance_listings` in place of `piid`. - Default response (no `?shape=`): `amount_suspect,assistance_listings,award_key,awarding_office(*),fain,fsrs_details(*),funding_office(*),key,place_of_performance(*),place_of_performance_id,prime_assistance_group,prime_recipient(uei,display_name),prime_recipient_id,recipient_id,recipient_parent_id,retired_at,subgrant_details(*),subgrant_recipient(uei,display_name)` - Leaves: `key`, `award_key`, `fain`, `assistance_listings`, `prime_assistance_group`, the three UEIs and their entity ids, `place_of_performance_id`, `pop_cd_original`, `pop_cd_current`, `amount_suspect`, `retired_at`, `usaspending_permalink` - Expansions: - `subgrant_details(description,type,number,amount,action_date,fiscal_year)` - `fsrs_details(last_modified_date,id,year,month)` - `place_of_performance(city,state,zip,country_code)` - `highly_compensated_officers(name,amount)` - `prime_recipient(uei,display_name)`, `subgrant_recipient(uei,display_name,duns)` - `awarding_office(*)`, `funding_office(*)` ```bash # Default response (shaped automatically) /api/assistance/subgrants/ # Select specific fields /api/assistance/subgrants/?shape=key,fain,subgrant_details(*) # The program and the prime's awarding office /api/assistance/subgrants/?shape=key,assistance_listings,awarding_office(*) ``` ### GSA eLibrary Contracts `/api/gsa_elibrary_contracts/` - Leaves: `uuid`, `schedule`, `contract_number`, `sins`, `cooperative_purchasing`, `disaster_recovery_purchasing`, `file_urls` - Expansions: - `recipient(uei,display_name)` - `idv(key,award_date)` ```bash # Basic fields /api/gsa_elibrary_contracts/?shape=uuid,schedule,contract_number # With recipient info /api/gsa_elibrary_contracts/?shape=uuid,contract_number,recipient(uei,display_name) ``` ### Financial assistance `/api/assistance/{type}/` The four financial-assistance endpoints (`grants`, `loans`, `direct_payments`, `other`) share one shape. Field definitions are in each endpoint's data dictionary: [grant awards](../../data-dictionary/assistance-grants.md), [loans](../../data-dictionary/assistance-loans.md), [direct payments](../../data-dictionary/assistance-direct-payments.md) and [other assistance](../../data-dictionary/assistance-other.md). - Default shape: `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: - `recipient(uuid,uei,duns,legal_business_name,legal_business_name_raw,county,congressional_district,congressional_district_original,highest_owner,business_types)` β€” the shared recipient record, shaped like an entity, with the latest values the recipient filed; `business_types` is a list of `{code, description}`; `null` on aggregate and PII-redacted records - `recipient_address(address_line1,address_line2,city,state_or_province_code,zip_code,zip_code_plus4,country_code,county_fips,state_fips,foreign_city_name,foreign_province_name,foreign_postal_code,congressional_district_original,congressional_district_current)` β€” the recipient record's address plus the two congressional districts filed on the award - `place_of_performance(country,state_code,state_name,state_fips,county_fips,county_name,city_name,zip_code,zip_plus_four,code,scope,foreign_location)` - `awarding_office(organization_id,office_code,office_name,agency_code,agency_name,department_code,department_name)` - `funding_office(...)` β€” same 7-key shape as `awarding_office` - `assistance_listing(number,title)` β€” the primary listing from the catalog; `null` when the catalog lacks the number - `assistance_type(code,description)` - `period_of_performance(start_date,current_end_date)` - `officers(highly_compensated_officer_1_name,highly_compensated_officer_1_amount,...,highly_compensated_officer_5_amount)` β€” `null` when none are reported - `obligations_by_fiscal_year(fiscal_year,obligated)` - `listings(cfda_number,is_primary,obligated,pragmatic_obligations,non_federal_funding_amount,indirect_cost_federal_share_amount,face_value_of_loan,loan_subsidy_cost,transactions_count,first_action_date,last_action_date)` β€” the award's money by assistance listing, primary first - `transactions(key,modification_number,transaction_date,action_type,assistance_type_code,correction_delete_indicator,cfda_number,obligated,pragmatic_obligations,non_federal_funding_amount,indirect_cost_federal_share_amount,face_value_of_loan,loan_subsidy_cost,award_amount_basis,award_recipient_basis,action_date_fiscal_year,last_modified_date,initial_report_date)` β€” latest first ```bash # Minimal grant fields /api/assistance/grants/?shape=key,fain,award_date,obligated # Recipient and its latest address /api/assistance/direct_payments/?shape=key,recipient(legal_business_name,uei),recipient_address(city,state_or_province_code,zip_code) # A program breakdown and per-year obligations /api/assistance/grants/?shape=key,cfda_number,listings(cfda_number,is_primary,obligated),obligations_by_fiscal_year(*) # Loans, by subsidy cost /api/assistance/loans/?shape=key,face_value_of_loan,loan_subsidy_cost,pragmatic_obligations&ordering=-pragmatic_obligations ``` ### Opportunities `/api/opportunities/` - Leaves: `opportunity_id`, `latest_notice_id`, `archive_date`, `title`, `description`, `naics_code`, `psc_code`, `response_deadline`, `first_notice_date`, `last_notice_date`, `active`, `set_aside`, `award_number`, `awarded`, `award_date`, `award_amount`, `awardee`, `awardee_uei`, `award_count`, `solicitation_opportunity_id`, `solicitation_number`, `snippet`, `sam_url`, plus relation id leaves: `agency_id`, `department_id`, `office_id` - Expansions: - `attachments(attachment_id,extracted_text,file_size,mime_type,name,posted_date,resource_id,type,url)` (shorthand: `attachments` β†’ `attachments(*)`) - `awards(opportunity_id,notice_id,award_number,award_date,award_amount,awardee,awardee_uei)` β€” up to ten of the most recent awards linked to a solicitation; `award_count` is the total - `office(office_code,office_name,agency_code,agency_name,department_code,department_name)` (shorthand: `office` β†’ `office(*)`) - `agency(*)` (shorthand: `agency` β†’ `agency(*)`) - `department(*)` (shorthand: `department` β†’ `department(*)`) - `latest_notice(notice_id,link)` (shorthand: `latest_notice` β†’ `latest_notice(*)`) - `place_of_performance(street_address,city,state,zip,country)` - `meta(notices_count,attachments_count,files_count,links_count,notice_type(code,type))` β€” `files_count` and `links_count` from API version 5.9.0 - `set_aside(code,description)` - `notice_history(index,notice_id,latest,title,deleted,posted_date,notice_type_code,solicitation_number,parent_notice_id,related_notice_id)` - `primary_contact(title,full_name,email,phone,fax)` - `secondary_contact(title,full_name,email,phone,fax)` Default response (list, no `?shape=`): `active,award_number,awarded,first_notice_date,last_notice_date,meta(*),naics_code,office(*),opportunity_id,place_of_performance(*),psc_code,response_deadline,sam_url,set_aside,solicitation_number,title` Default response (detail): `active,attachments(attachment_id,file_size,mime_type,name,posted_date,resource_id,type,url),award_amount,award_count,award_date,award_number,awarded,awardee,awardee_uei,awards(*),description,first_notice_date,last_notice_date,meta(*),naics_code,notice_history(*),office(*),opportunity_id,place_of_performance(*),primary_contact(*),psc_code,response_deadline,sam_url,set_aside,solicitation_number,solicitation_opportunity_id,title` Award fields are filled only where SAM has posted an award notice; see [Opportunities β†’ Awards](../../api-reference/opportunities.md#awards). `meta.attachments_count` counts links as well as files; see [Attachments: files and links](../../data-dictionary/opportunities.md#attachments-files-and-links). ```bash # Expand set_aside to get code + description /api/opportunities/?shape=opportunity_id,title,set_aside(code,description) # Office + attachments using bare expand shorthand /api/opportunities/?shape=opportunity_id,title,office,attachments&limit=1 # Detail with notice history /api/opportunities/{id}/?shape=opportunity_id,title,notice_history(*) # Contacts /api/opportunities/{id}/?shape=opportunity_id,primary_contact(*),secondary_contact(*) # A solicitation and the awards linked to it /api/opportunities/{id}/?shape=opportunity_id,title,awarded,award_count,awards(*) ``` ### Notices `/api/notices/` - Leaves: `notice_id`, `opportunity_id`, `title`, `description`, `naics_code`, `psc_code`, `posted_date`, `response_deadline`, `last_updated`, `active`, `set_aside`, `sam_url`, `attachment_count`, `file_count`, `link_count`, `award_number`, `award_date`, `award_amount`, `awardee`, `awardee_uei`, `solicitation_number` - Expansions: - `attachments(attachment_id,extracted_text,file_size,mime_type,name,posted_date,resource_id,type,url)` (shorthand: `attachments` β†’ `attachments(*)`) - `address(city,state,zip,country)` - `archive(date,type)` - `place_of_performance(street_address,city,state,zip,country)` - `primary_contact(title,full_name,email,phone,fax)` - `secondary_contact(title,full_name,email,phone,fax)` - `meta(parent_notice_id,related_notice_id,notice_type(code,type),link)` - `office(office_code,office_name,agency_code,agency_name,department_code,department_name)` (shorthand: `office` β†’ `office(*)`) - `opportunity(opportunity_id,link)` (shorthand: `opportunity` β†’ `opportunity(*)`) - `set_aside(code,description)` Default response (list, no `?shape=`): `active,address(*),attachment_count,award_number,description,file_count,last_updated,link_count,meta(*),naics_code,notice_id,office(*),opportunity(*),place_of_performance(*),posted_date,psc_code,response_deadline,sam_url,set_aside,solicitation_number,title` Default response (detail): adds `archive(*)`, `primary_contact(*)`, `secondary_contact(*)` `file_count` and `link_count` are available from API version 5.9.0. `attachment_count` counts links as well as files; see [Attachments: files and links](../../data-dictionary/opportunities.md#attachments-files-and-links). ```bash # Expand set_aside to get code + description /api/notices/?shape=notice_id,title,set_aside(code,description) # Include archive and contacts on detail /api/notices/{id}/?shape=notice_id,title,archive(*),primary_contact(*) # Get linked opportunity reference /api/notices/?shape=notice_id,opportunity(opportunity_id,link) ``` ### Entities `/api/entities/` Entities default to the shaping pipeline. Default responses include core identity fields (list) or the full detail set (retrieve) with normalized field formats. Use `?shape=` to customize. - Leaves: `uei`, `uuid`, `display_name`, `legal_business_name`, `dba_name`, `cage_code`, `dodaac`, `registered`, `registration_status`, `primary_naics`, `psc_codes`, `email_address`, `entity_url`, `description`, `capabilities`, `keywords`, `sam_activation_date`, `sam_registration_date`, `sam_expiration_date`, `last_update_date`, `congressional_district`, `evs_source`, `uei_status`, `uei_expiration_date`, `uei_creation_date`, `public_display_flag`, `exclusion_status_flag`, `exclusion_url`, `entity_division_name`, `entity_division_number`, `entity_start_date`, `fiscal_year_end_close_date`, `submission_date` - Expansions: - `physical_address(address_line1,address_line2,city,state_or_province_code,zip_code,zip_code_plus4,country_code,country_name)` β€” normalized snake_case keys - `mailing_address(...)` β€” same fields as `physical_address` - `business_types(code,description)` β€” normalized `[{code, description}]`; auto-normalizes dict-format DSBS data - `sba_business_types(code,description,entry_date,exit_date)` β€” normalized SBA certifications - `naics_codes(code,sba_small_business)` β€” normalized; converts plain string arrays automatically - `federal_obligations(total,active)` β€” expand-only; `total` and `active` sub-objects with obligation metrics - `highest_owner(cage_code,legal_business_name,uei)` β€” highest corporate owner - `immediate_owner(cage_code,legal_business_name,uei)` β€” immediate parent entity - `relationships(relation,type,source,uei,display_name)` β€” corporate ownership, corporate succession, and reported prime/sub ties; match on `type`, not the `relation` display label (see the [entities data dictionary](../../data-dictionary/entities.md#relationships)) - `entity_structure(code,description)` β€” falls back to ENTITY_STRUCTURE_MAP for description - `entity_type(code,description)` β€” falls back to BUSINESS_TYPE_MAP for description - `profit_structure(code,description)` β€” falls back to BUSINESS_TYPE_MAP for description - `organization_structure(code,description)` β€” falls back to BUSINESS_TYPE_MAP for description - `state_of_incorporation(code,description)` β€” uses model description - `country_of_incorporation(code,description)` β€” falls back to the GENC standard for country names when SAM.gov doesn't provide one - `purpose_of_registration(code,description)` β€” falls back to PURPOSE_OF_REGISTRATION_MAP for description - `past_performance[top=N](summary,top_agencies)` β€” aggregated contract history; `summary` has `total_obligated`, `total_awards`, `agency_count`, `naics_count`, `psc_count`; `top_agencies` lists top N agencies (default 5, max 100) with `agency_code`, `agency_name`, `department_code`, `department_name`, `obligations`, `awards_count`, `top_naics`, `top_psc`. Accepts bracket param `[top=N]`. ```bash # List with default shape (core identity fields) /api/entities/ # Detail with all fields + normalized expands /api/entities/ZQGGHJH74DW7/ # Custom shape: just UEI and business types /api/entities/?shape=uei,business_types(code,description) # Federal obligations for a specific entity /api/entities/ZQGGHJH74DW7/?shape=uei,federal_obligations(total) # Structured code/description fields /api/entities/ZQGGHJH74DW7/?shape=uei,entity_structure(*),purpose_of_registration(*) # Owner info /api/entities/ZQGGHJH74DW7/?shape=uei,highest_owner(*),immediate_owner(*) # Past performance (default top 5 agencies) /api/entities/ZQGGHJH74DW7/?shape=uei,past_performance(*) # Past performance with top 10 agencies /api/entities/ZQGGHJH74DW7/?shape=uei,past_performance[top=10](summary,top_agencies) ``` ### Forecasts `/api/forecasts/` - Leaves: `id`, `source_system`, `external_id`, `agency`, `title`, `description`, `anticipated_award_date`, `fiscal_year`, `naics_code`, `is_active`, `status`, `created`, `modified`, `primary_contact`, `place_of_performance`, `estimated_period`, `set_aside`, `contract_vehicle`, `raw_data` - Expansions: - `display(title,description,agency,anticipated_award_date,fiscal_year,naics_code,status,primary_contact,place_of_performance,estimated_period,set_aside,contract_vehicle)` β€” normalized view of the forecast's display data - `raw_data(*)` β€” the raw JSON data from the source system; accepts wildcard fields ```bash # Basic forecast fields /api/forecasts/?shape=id,title,agency,anticipated_award_date,status # With display expansion for normalized view /api/forecasts/?shape=id,title,display(agency,anticipated_award_date,primary_contact,place_of_performance) # Include raw source data /api/forecasts/?shape=id,title,raw_data(*) ``` ### Grants `/api/grants/` - Leaves: `agency_code`, `applicant_eligibility_description`, `description`, `forecast`, `funding_activity_category_description`, `grant_id`, `grantor_contact`, `last_updated`, `opportunity_history`, `opportunity_number`, `status`, `synopsis`, `title` - Expansions: - `cfda_numbers(number,title)` β€” associated CFDA/Assistance Listing numbers - `applicant_types(code,description)` - `category(code,description)` β€” opportunity category - `funding_categories(code,description)` - `funding_instruments(code,description)` - `status(code,description)` β€” expanded status with code and label (use this when you want the structured form; `status` alone is treated as a leaf unless the runtime must expand it for safety) - `important_dates(posted_date,response_date,response_date_description,estimated_synopsis_post_date,estimated_application_response_date,estimated_application_response_date_description,estimated_project_start_date)` β€” key dates (fields vary by status: posted opportunities return `posted_date`/`response_date`; forecasted ones return `estimated_*` fields) - `funding_details(award_ceiling,award_floor,estimated_total_funding,expected_number_of_awards)` - `grantor_contact(name,phone,email)` - `additional_info(link,description)` - `attachments(mime_type,name,posted_date,resource_id,type,url)` ```bash # Basic grant fields /api/grants/?shape=grant_id,title,status,agency_code # With CFDA numbers and applicant types /api/grants/?shape=grant_id,title,cfda_numbers(number,title),applicant_types(code,description) # Expanded status and funding instruments /api/grants/?shape=grant_id,title,status(code,description),funding_instruments(code,description) ``` ### IT Dashboard `/api/itdashboard/` IT Dashboard exposes **tiered shaping**: Free gets basic investment metadata, Small+ adds the `funding` and `details` expansions, and Medium+ adds nested sub-tables (contracts, projects, CIO evaluations, performance metrics, etc.) plus the `business_case_html` leaf. Fields or expansions above the caller's tier are silently stripped from the response, and removed nodes are listed in `meta.upgrade_hints`. For the full tier/field matrix, see the [IT Dashboard API Reference](../../api-reference/itdashboard.md#response-shaping). - Leaves (all tiers): `uii`, `agency_code`, `agency_name`, `bureau_code`, `bureau_name`, `investment_title`, `type_of_investment`, `part_of_it_portfolio`, `updated_time`, `url` - Medium+ leaf: `business_case_html` - Expansions (Small+): - `funding(*)` β€” fiscal-year internal funding and contributions (FY2020–FY2025) - `details(*)` β€” extended metadata: description, previous/current UII, classification, business case URL, public URLs - Expansions (Medium+): `cio_evaluation(*)`, `contracts(*)`, `projects(*)`, `cost_pools_towers(*)`, `funding_sources(*)`, `performance_metrics(*)`, `performance_actual(*)`, `operational_analysis(*)` Default response (no `?shape=`): - List: `uii,agency_name,bureau_name,investment_title,type_of_investment,part_of_it_portfolio,updated_time,url` - Detail: adds `agency_code,bureau_code` ```bash # Free tier: basic metadata /api/itdashboard/?shape=uii,investment_title,agency_name,url # Small+ tier: funding and details /api/itdashboard/?shape=uii,investment_title,funding(*),details(*) # Medium+ tier: nested sub-tables + business case HTML /api/itdashboard/{uii}/?shape=uii,investment_title,cio_evaluation(*),performance_metrics(*),business_case_html ``` ### Protests `/api/protests/` Both list and detail return case-level objects identified by `case_id`. Dockets are available via the `dockets(...)` expansion. - Leaves: `case_id`, `source_system`, `case_number`, `title`, `protester`, `agency`, `solicitation_number`, `case_type`, `outcome`, `filed_date`, `posted_date`, `decision_date`, `due_date`, `docket_url`, `decision_url`, `digest` - Expansions: - `dockets(source_system,case_number,docket_number,title,protester,agency,solicitation_number,case_type,outcome,filed_date,posted_date,decision_date,due_date,docket_url,decision_url,digest)` Default response (no `?shape=`): `case_id,source_system,case_number,title,protester,agency,solicitation_number,case_type,outcome,filed_date,posted_date,decision_date,due_date,docket_url,decision_url` (no nested dockets) Notes: - `case_number` is the base B-number (e.g. `b-424214`) identifying the case. - `docket_number` (e.g. `b-424214.1`) identifies a specific sub-docket; only available inside `dockets(...)`. - `digest` is opt-in only (decision summary text from `raw_data`). ```bash # Case-level fields with nested dockets /api/protests/?shape=case_id,case_number,title,dockets(docket_number,filed_date,outcome) # Case-level only /api/protests/?shape=case_id,title,outcome,decision_date # Detail with dockets /api/protests/{case_id}/?shape=case_id,title,dockets(docket_number,filed_date) ``` ### Contract appeals `/api/contract_appeals/` A flat resource: every field is a leaf and there are no expansions, so use explicit field lists. - Leaves: `uuid`, `board`, `docket_numbers`, `docket_source`, `docket_raw`, `decision_date`, `decision_date_raw`, `decision_date_repaired`, `appellant`, `judge`, `decision_type`, `decision_type_raw`, `url`, `document_id`, `listing_url`, `listing_year`, `first_listed_at`, `listed`, `text_status`, `text_char_count`, `decision_text` Default list shape: `uuid,board,docket_numbers,decision_date,appellant,judge,decision_type,url` Default detail shape: the list fields plus `docket_raw`, `docket_source`, `decision_date_repaired`, `decision_type_raw`, `listing_year`, `first_listed_at`, `listed`, `text_status`, `text_char_count` Notes: - `docket_numbers` is an **array** β€” a consolidated appeal carries several dockets. - `decision_text` requires an **Enterprise** plan and is in neither default shape. Naming it on a lower plan returns 200 with the field omitted and a `meta.upgrade_hints` entry; every other field is available on every plan. - `text_status` and `text_char_count` report whether a decision has extracted text behind it, at any plan. ```bash # List payload for a docket lookup /api/contract_appeals/?board=asbca&docket=57530&shape=uuid,docket_numbers,appellant,decision_date,url # Polling shape β€” newest observations first /api/contract_appeals/?ordering=-first_listed_at&shape=uuid,board,docket_numbers,appellant,first_listed_at # Detail with the decision body (Enterprise) /api/contract_appeals/{uuid}/?shape=uuid,board,docket_numbers,appellant,decision_date,decision_text ``` ### Federal Register `/api/federal_register/` A flat resource: every field is a leaf and there are no expansions, so use explicit field lists. - Leaves: `uuid`, `document_number`, `publication_date`, `citation`, `title`, `type`, `subtype`, `abstract`, `action`, `dates`, `comments_close_on`, `effective_on`, `signing_date`, `start_page`, `end_page`, `page_length`, `volume`, `significant`, `toc_doc`, `toc_subject`, `correction_of`, `corrections`, `disposition_notes`, `executive_order_notes`, `executive_order_number`, `presidential_document_number`, `proclamation_number`, `not_received_for_publication`, `comment_url`, `regulations_dot_gov_url`, `html_url`, `body_html_url`, `pdf_url`, `public_inspection_pdf_url`, `raw_text_url`, `agencies`, `cfr_references`, `dockets`, `docket_ids`, `topics`, `regulation_id_numbers`, `regulation_id_number_info`, `regulations_dot_gov_info`, and on the detail endpoint only, `full_text` Default list shape: `uuid,document_number,publication_date,type,subtype,title,abstract,action,agencies,cfr_references,citation,significant,comments_close_on,effective_on,html_url,pdf_url` Default detail shape: the list fields plus `dates`, `signing_date`, `start_page`, `end_page`, `volume`, `docket_ids`, `dockets`, `regulation_id_numbers`, `topics`, `correction_of`, `corrections`, `executive_order_number`, `presidential_document_number`, `proclamation_number`, `comment_url`, `regulations_dot_gov_url`, `raw_text_url`, `body_html_url` Notes: - `full_text` is detail-only and in neither default shape; naming it on the list endpoint returns 400. It is available on every plan. - `agencies`, `cfr_references`, `dockets` and `topics` are the Federal Register's own structures, served as published β€” they are leaves, not expansions, so they cannot be narrowed with `field(subfield)` syntax. ```bash # Lean list payload for a CFR part /api/federal_register/?cfr_title=40&cfr_part=52&shape=uuid,document_number,publication_date,title,citation # Comment-deadline tracker /api/federal_register/?comments_open=true&shape=uuid,document_number,title,comments_close_on,comment_url # Detail with the body /api/federal_register/{uuid}/?shape=uuid,document_number,title,full_text ``` ### Award announcements `/api/news/award_announcements/` - Leaves: `uuid`, `source`, `source_name`, `source_url`, `source_record_id`, `published_date`, `award_date`, `title`, `text`, `amount`, `value_kind`, `obligated_at_award`, `action_type`, `announcement_type`, `award_kind`, `awardee_count`, `piids`, `award_uuids`, `civilian`, `component`, `contracting_activity`, `is_modification`, `is_multiple_award`, `corrections`, `is_withdrawn` - Expansions: `awardees(...)` β€” `name`, `uei`, `location`, `small_business`; `organization(...)` β€” the canonical 7-key office payload Default list shape: `uuid,source,source_name,source_url,published_date,award_date,title,amount,value_kind,action_type,announcement_type,awardee_count,piids,is_modification,is_multiple_award,is_withdrawn,awardees(*)` Default detail shape: the list fields plus `source_record_id`, `text`, `obligated_at_award`, `award_kind`, `award_uuids`, `civilian`, `component`, `contracting_activity`, `corrections`, `organization(*)` Notes: - `text` is in the detail default only, but it can be named on the list endpoint. - Keep `source` in any shape that includes `text`: a `makegov_generated` paragraph is not government text. ```bash # Lean list payload for one source /api/news/award_announcements/?source=official_release&shape=uuid,published_date,amount,value_kind,piids # Awardee names and UEIs /api/news/award_announcements/?shape=uuid,source,published_date,awardees(name,uei) # Detail with the awarding organization's names only /api/news/award_announcements/{uuid}/?shape=uuid,source,text,organization(agency_name,department_name) ``` ### eBuy `/api/ebuy/requests/` - Leaves: `rfq_id`, `request_type`, `title`, `description`, `schedule`, `sin`, `status`, `buyer_name`, `buyer_agency`, `buyer_agency_code`, `buyer_email`, `buyer_user_id`, `reference_number`, `award_method`, `contract_type`, `commercial_type`, `follow_on`, `source_sought`, `issue_date`, `close_date`, `cancel_date`, `last_mod_date`, `pop_start_date`, `pop_end_date`, `oco_name`, `oco_title`, `oco_agency`, `oco_phone`, `oco_aac`, `ocs_name`, `ocs_title`, `ocs_agency`, `ocs_phone`, `ocs_aac`, `amendment_count`, `mod_version`, `qa_document_count`, `attachment_count`, `link_count`, `amendments`, `line_items`, `addresses`, `detail_fetched`, `first_seen`, `last_seen` - Expansions: `organization(...)` β€” the canonical 7-key office payload; `attachments(...)` β€” `doc_seq_num`, `doc_name`, `doc_type`, `doc_path`, `is_link`, `doc_session_date`, `extracted_text` (only when named; `attachments(*)` does not include it) Default list shape: `rfq_id,request_type,title,schedule,sin,status,buyer_name,buyer_agency,buyer_agency_code,reference_number,issue_date,close_date,attachment_count,link_count,last_seen` Default detail shape: every leaf, plus `organization(*)` and `attachments(*)` Notes: - Only requests under your own linked contracts are returned; see the [eBuy API reference](../../api-reference/ebuy.md). - `status` is frozen as eBuy supplied it β€” read `last_seen` for staleness. ```bash # Lean list payload /api/ebuy/requests/?status=Open&shape=rfq_id,title,sin,close_date,last_seen # Detail with attachments, for picking a download /api/ebuy/requests/RFQ1835158/?shape=rfq_id,title,attachments(doc_seq_num,doc_name,is_link) # Detail with each document's text /api/ebuy/requests/RFQ1835158/?shape=rfq_id,title,attachments(doc_seq_num,doc_name,extracted_text) ``` --- --- description: "Which Tango endpoints return exact vs. approximate result counts, and how to force an exact count with ?exact=true." tags: [api, guide] updated: 2026-10-25 --- # Result counts Every paginated response includes a `count` field with the total number of matching results. The `X-Results-CountType` response header indicates whether that count is exact or approximate. ## Which endpoints use approximate counts? Most endpoints always return **exact counts**. These high-volume endpoints use approximate counting by default: - `/api/contracts/` - `/api/idvs/` - `/api/assistance/grants/`, `/api/assistance/loans/`, `/api/assistance/direct_payments/`, `/api/assistance/other/` - `/api/opportunities/` - `/api/notices/` Other endpoints (entities, grants, subawards, vehicles, protests, etc.) always return exact counts. The `?exact=true` parameter has no effect on those β€” they're already exact. Inspect the `X-Results-CountType` response header (`exact` or `approximate`) on any request to confirm. ## How approximate counts work On the endpoints above, a filtered request is counted exactly up to 10,000 results, so most filtered searches return an exact `count` and `X-Results-CountType: exact`. Past 10,000 results the `count` is approximate: a database query-planner estimate, never lower than 10,001. Read it as "at least 10,001" rather than a precise size, and add `?exact=true` when you need the real figure. An unfiltered request (for example, every contract) returns an approximate count taken from table statistics. ## Requesting exact counts For the endpoints that use approximate counting, add `?exact=true` to force an exact count: ```bash GET /api/contracts/?exact=true GET /api/opportunities/?exact=true&search=software ``` **Performance note:** Exact counts run a full `COUNT(*)` query, which can be slow on large, unfiltered result sets (e.g., all contracts). Use this when accuracy matters more than speed. Pagination does not depend on the count: `next` is present as long as more results exist, with or without `?exact=true`, so you can page to the last result either way. ## Knowing whether a count is exact Check the `X-Results-CountType` response header: ```plaintext X-Results-CountType: exact X-Results-CountType: approximate ``` This header is present on all paginated **list** responses. It is not included on detail (single-resource) endpoints. ## Examples ### Contracts (approximate by default) ```bash curl -sI -H "X-API-KEY: your-key" \ "https://tango.dev/api/contracts/" | grep X-Results ``` ```plaintext X-Results-CountType: approximate ``` ```json { "count": 2541837, "next": "...", "results": [...] } ``` ### Contracts with exact count ```bash curl -sI -H "X-API-KEY: your-key" \ "https://tango.dev/api/contracts/?exact=true" | grep X-Results ``` ```plaintext X-Results-CountType: exact ``` ```json { "count": 2541293, "next": "...", "results": [...] } ``` ### Entities (always exact) ```bash curl -sI -H "X-API-KEY: your-key" \ "https://tango.dev/api/entities/" | grep X-Results ``` ```plaintext X-Results-CountType: exact ``` ```json { "count": 487293, "next": "...", "results": [...] } ``` --- --- description: "How Tango's Vehicles resource groups related IDVs by solicitation, and how to search, filter, and pull task orders under one." tags: [vehicles, api, guide] updated: 2026-10-24 --- # Vehicles Vehicles provide a solicitation-centric way to discover groups of related IDVs and then expand into the underlying awards. ## What is a Vehicle? In Tango, a **Vehicle** is a grouping of multiple IDVs that share the same `solicitation_identifier` and the same awarding-agency identifier derived from the IDV award `key`. >In federal data, *each IDV award is a vehicle*. >In practice, people often think of a β€œvehicle” as the *solicitation that produced many IDV awards* (one per awardee). We model that higher-level grouping explicitly. Vehicles are useful when you want to: - Find β€œthe contract vehicle” behind a set of IDVs (e.g., the solicitation that produced a schedule/IDIQ vehicle) - Search across a vehicle’s underlying IDVs - Pull a shaped list of the IDVs that make up a vehicle ## Endpoints - **List**: `GET /api/vehicles/` - **Detail**: `GET /api/vehicles/{uuid}/` - **Awardees** (the underlying IDVs): `GET /api/vehicles/{uuid}/awardees/` β€” supports `?search=` - **Task Orders**: `GET /api/vehicles/{uuid}/orders/` ## Search ### Vehicle-level search (list) Use `?search=` on the list endpoint to search vehicles: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles/?search=GSA%20schedule&page=1" ``` ### Award-within-vehicle search (detail, when expanding awards) On the detail endpoint, `?search=` is used to filter **expanded awardees** (IDVs) when your `shape` includes `awardees(...)`. ## Filtering Vehicles support a rich filter set across enums, reference codes, org hierarchy, numeric ranges, and dates. Multi-value enum filters use `|` for OR semantics. See the full list and details on the [Vehicles API Reference](../../api-reference/vehicles.md#filtering). Quick examples: ```bash # All SEWP-program vehicles awarded in FY 2024 or later GET /api/vehicles/?program_acronym=SEWP&fiscal_year=2024 # IDIQ vehicles where DOD or DHS is the awarding org GET /api/vehicles/?type_of_idc=A&agency=DOD|DHS # Vehicles with at least 100 task orders and $100M+ obligated GET /api/vehicles/?order_count_min=100&total_obligated_min=100000000 ``` ## Ordering The vehicles list endpoint supports ordering by activity metrics and statistics using the `?ordering=` query parameter. ### Available ordering fields (8 total) - `vehicle_obligations` - Total obligations across all IDVs in the vehicle (annotated) - `latest_award_date` - Most recent IDV award date in the vehicle (annotated) - `total_obligated` - Direct column rollup - `award_date` - Earliest IDV award date - `last_date_to_order` - Latest "last date to order" across IDVs - `fiscal_year` - Vehicle fiscal year - `idv_count` - Denormalized IDV count - `order_count` - Denormalized task-order count `holder_count` (distinct companies holding the vehicle's contracts), `order_winner_count` (distinct companies that have won a task order under it), the deprecated `awardee_count` (same value as `order_winner_count`) and `vehicle_contracts_value` are returned on every vehicle but are not orderable; `?ordering=` on any of them returns a 400. ### Ordering syntax - Ascending: `?ordering=vehicle_obligations` - Descending: `?ordering=-vehicle_obligations` (prefix with `-`) - Multiple fields: `?ordering=-vehicle_obligations,-latest_award_date` ### Examples Sort by total obligations (highest first): ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles/?ordering=-vehicle_obligations&page=1" ``` Sort by most recent award activity: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles/?ordering=-latest_award_date&page=1" ``` Sort by obligations, then by latest award date: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles/?ordering=-vehicle_obligations,-latest_award_date&page=1" ``` **Note**: When no `?ordering=` parameter is provided, vehicles are ordered by `solicitation_identifier`, `agency_id`, and `uuid` (default ordering). ## Task Orders The `GET /api/vehicles/{uuid}/orders/` endpoint returns all task orders (contracts) issued against all IDVs within a vehicle. This endpoint supports pagination, response shaping, filtering, search, and transaction expansion, similar to the `/api/contracts/` endpoint. ### Basic usage ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?page=1" ``` ### Filtering Filter task orders using the same filters available on `/api/contracts/`: ```bash # Filter by date range curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?award_date_gte=2024-01-01&award_date_lte=2024-12-31" # Filter by recipient curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?recipient=ACME" ``` ### Response shaping Use the `shape` parameter to customize fields and expand related objects: ```bash # Include recipient and transaction details curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?shape=key,piid,award_date,recipient(display_name,uei),transactions(description,transaction_date,modification_number)" ``` ### Search Search task order descriptions: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?search=software" ``` ### Ordering The orders endpoint supports ordering by contract fields using the `?ordering=` parameter (the same allowlist as `/api/contracts/`): - `award_date` - Contract award date (default: descending, newest first) - `obligated` - Obligated amount - `total_contract_value` - Total contract value (base + all options) **Default ordering**: When no `?ordering=` parameter is provided, task orders are ordered by `-award_date, -uuid` (newest first). **Examples**: ```bash # Default ordering (newest first) curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?page=1" # Order by obligated amount (highest first) curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?ordering=-obligated&page=1" # Order by total contract value curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//orders/?ordering=-total_contract_value&page=1" ``` The response includes vehicle context in the metadata (vehicle UUID and solicitation identifier). ## Vehicle metrics and organization Vehicle responses can include two enrichment expansions: - `metrics(*)` β€” 12 computed vehicle metrics (HHI, competed-rate, top-recipient share, etc.). Included in the default detail shape; opt-in via `?shape=...,metrics(*)` on the list endpoint. - `organization(*)` β€” canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Both bare `?shape=organization` (leaf) and `?shape=organization(*)` (expand) work and return the same payload. ```bash # List vehicles with their metrics bundle and resolved org curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles/?shape=uuid,solicitation_identifier,metrics(*),organization(*)&limit=5" ``` ## Synthetic GWAC vehicles Some GWAC vehicles lack a real solicitation number; Tango synthesizes a vehicle so the grouping still works. Identify these via: - `is_synthetic_solicitation` β€” boolean, `true` for synthetic rows - `program_acronym` β€” the GWAC's identifier (e.g. `SEWP`) - `solicitation_identifier` β€” the user-facing value, with the internal `ACRO:` storage prefix stripped automatically ## Response shaping Vehicles support the `shape` parameter, including the `awardees(...)` expansion. Example: fetch a vehicle with a shaped list of its IDVs: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//?shape=uuid,solicitation_identifier,organization_id,holder_count,order_winner_count,order_count,vehicle_obligations,vehicle_contracts_value,awardees(key,uuid,piid,award_date,recipient(display_name,uei))" ``` Example: include opportunity-derived fields and expand the linked Opportunity: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//?shape=uuid,solicitation_identifier,solicitation_title,solicitation_date,naics_code,opportunity(opportunity_id,title,first_notice_date,office(office_name,agency_name))" ``` Example: expand JSON detail fields to select specific sub-fields: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//?shape=uuid,solicitation_identifier,competition_details(extent_competed,number_of_offers_received),type_of_idc,contract_type" ``` Example: filter expanded awards within a vehicle: ```bash curl -H "X-API-KEY: " \ "https://tango.dev/api/vehicles//?shape=uuid,awardees(key,uuid,recipient(display_name))&search=acme" ``` See [Response Shaping](response-shaping.md) for full syntax and flattening options. --- --- description: "How to connect an AI agent to the hosted Tango MCP server, including install-from-directory setup, authentication, and the available tools." tags: [mcp, guide] updated: 2026-08-10 --- # Tango MCP (AI agents) The **Tango MCP server** gives AI agents access to federal procurement competitive intelligence via the [Tango API](https://tango.dev). The server is **hosted at `https://tango.dev/mcp`** and uses **HTTP transport** β€” you connect your MCP client to the remote endpoint; no local install required. `https://govcon.dev/mcp` is the original endpoint and keeps working; it is not deprecated and we are not retiring it. Both addresses reach the same server. Use `tango.dev/mcp` for new setups, and see [Which endpoint should I use?](#which-endpoint-should-i-use) if you are already connected to `govcon.dev`. Tango is listed in both major assistant directories, and you can also point any MCP-compatible client β€” Cursor, the OpenAI Responses API, your own β€” at the endpoint directly. ## Install from a directory Installing from a directory is one click plus a Tango sign-in. You never handle an API key and there is nothing to configure: - **Claude** β€” [`tango.dev/claude`](https://tango.dev/claude) opens the Tango connector in Anthropic's directory. You can also find it in Claude under Settings β†’ Connectors. Works on web, desktop, and mobile. - **ChatGPT** β€” [`tango.dev/chatgpt`](https://tango.dev/chatgpt) opens the Tango app in the ChatGPT app directory. Both connect to the same hosted server and authenticate through Tango's OAuth flow, so the assistant sees exactly the data your account and plan already allow. Manage the connection β€” or revoke it β€” from your account at [tango.dev](https://tango.dev). The rest of this page covers connecting other MCP clients, where you supply the endpoint and credentials yourself. ## What it does The server exposes 5 tools that let an AI agent research government contracting data on your behalf: - **Discover what's in the data** β€” Use `resolve` to find entities, agencies, vehicles, NAICS/PSC codes, contracts, opportunities, OTAs, OTIDVs, subawards, organizations, protests, and IT Dashboard investments by name or keyword; get identifiers and previews to use with other tools. - **Search awards and related data** β€” Use `search` to query contracts, IDVs, vehicles, OTAs, OTIDVs, subawards, organizations, GSA eLibrary contracts, CALC labor rates (LCATs), bid protests, IT Dashboard investments, grants, and federal budget accounts. Filter by vendor, agency, NAICS, PSC, dates, and many other criteria; optionally profile a capped sample of the matches (obligated amounts, set-aside breakdown, etc.) β€” see [`include_summary` is a sample, not a market total](#include_summary-is-a-sample-not-a-market-total). - **Search active opportunities** β€” Use `search_opportunities` to find SAM.gov opportunities and agency forecasts by agency, NAICS, set-aside type, response deadline, and keyword. - **Get full details for any item** β€” Use `get_details` to retrieve detailed information for a specific entity, contract, IDV, vehicle, opportunity, OTA, OTIDV, organization, subaward, protest, MAS SIN, GSA eLibrary contract, or IT Dashboard investment by ID, with optional related-data enrichment. - **Read curated API documentation** β€” Use `fetch_api_docs` to pull short, LLM-friendly documentation for any major Tango resource (contracts, opportunities, vehicles, IT Dashboard, etc.). ## Quick start Skip this section if you installed from the Claude or ChatGPT directory β€” those handle the endpoint and the sign-in for you. ### Prerequisites - A **Tango API key** (from the [Tango web interface](https://tango.dev)), or for OAuth clients: access tokens via `Authorization: Bearer ` - An MCP-compatible client (e.g. Cursor, Claude Desktop) ### Connect via HTTP The MCP endpoint is **`https://tango.dev/mcp`**. Configure your client to connect to this URL over HTTP and send your API key (see [Using with MCP clients](#using-with-mcp-clients) below). ### Which endpoint should I use? | | | | --- | --- | | **New setups** | `https://tango.dev/mcp` | | **Already connected to `govcon.dev/mcp`** | Stay there. Nothing is changing and there is no migration deadline. | The two addresses are the same server, but they are **distinct OAuth protected resources** β€” each advertises its own `resource` identifier, and access tokens are bound to the one you authorized against. Switching an existing OAuth connection from `govcon.dev/mcp` to `tango.dev/mcp` therefore means re-authorizing. That is the only reason to think twice; if you connect with an API key rather than OAuth, you can switch freely. ## Using with MCP clients ### Remote MCP (HTTP) β€” recommended Connect your client to the hosted server over HTTP using [mcp-remote](https://github.com/geelen/mcp-remote). The server expects your Tango API key in the `X-Tango-API-Key` header (or an OAuth bearer token in `Authorization: Bearer`). **Cursor / Claude with remote URL (API key):** ```json { "mcpServers": { "tango-remote": { "command": "npx", "args": [ "-y", "mcp-remote", "https://tango.dev/mcp", "--header", "X-Tango-API-Key: your_api_key_here" ] } } } ``` **Cursor / Claude with remote URL (OAuth bearer token):** ```json { "mcpServers": { "tango-remote-oauth": { "command": "npx", "args": [ "-y", "mcp-remote", "https://tango.dev/mcp", "--header", "Authorization: Bearer your_oauth_token_here" ] } } } ``` Use a fresh access token from your Tango OAuth flow; refresh the token when it expires. **Streamable HTTP (JSON mode)** β€” The server uses HTTP transport and returns JSON responses rather than Server-Sent Events (SSE). If you see errors like "Unexpected content type" or "Failed to open SSE stream", ensure the client uses JSON mode. **API key security** β€” Prefer setting the API key via environment variable or a secrets manager. When using mcp-remote with `--header X-Tango-API-Key: ...`, avoid committing the key to config; use a local env var or secret so the key is not logged or stored in plain text. ### Claude The [Tango connector](https://tango.dev/claude) in Anthropic's directory is the recommended path β€” one click, sign in with Tango, no API key to manage. See [Install from a directory](#install-from-a-directory) above. To supply your own API key instead of signing in with OAuth, configure Claude Desktop with the [remote-MCP JSON](#remote-mcp-http-recommended) above. ### ChatGPT Enable the [Tango app](https://tango.dev/chatgpt) from the ChatGPT app directory. Authentication is the same Tango OAuth sign-in; no API key required. To call the server from your own OpenAI integration instead, see [OpenAI Responses API](#openai-responses-api) below. ### OAuth flow When connecting over HTTP, you can authenticate with a **bearer token** instead of an API key. This is useful for clients that support OAuth or when you obtain access tokens from Tango's OAuth server. The Claude and ChatGPT directory listings run this flow for you β€” the steps below are for clients you wire up yourself. 1. **Obtain an access token** from the Tango OAuth server at [tango.makegov.com](https://tango.makegov.com). Use the authorization code or client credentials flow; supported grant types include `authorization_code`, `client_credentials`, and `refresh_token`. Required scope is typically `read`. 2. **Send the token on each request** via the `Authorization` header: `Authorization: Bearer `. 3. **Auth precedence** β€” The server resolves auth in this order: (1) `Authorization: Bearer` if present, (2) `X-Tango-API-Key` if present, (3) `TANGO_API_KEY` from the environment (stdio/local only). **OAuth discovery** β€” The server exposes standard discovery endpoints so clients can find the Tango authorization server and required scopes: - Authorization server metadata: `GET /.well-known/oauth-authorization-server` and `GET /mcp/.well-known/oauth-authorization-server` - Protected resource metadata: `GET /.well-known/oauth-protected-resource` These return JSON (issuer, `authorization_endpoint`, `token_endpoint`, `scopes_supported`, etc.). The default issuer is [https://tango.makegov.com](https://tango.makegov.com). ### OpenAI Responses API OpenAI's MCP integration requires a publicly accessible server. Use the hosted MCP endpoint `https://tango.dev/mcp` in your `tools` configuration. See the [OpenAI MCP documentation](https://platform.openai.com/docs/guides/tools-remote-mcp) for details. ## Available tools | Tool | Description | | ---- | ----------- | | `resolve` | Find entities, vehicles, organizations, contracts, opportunities, OTAs, OTIDVs, subawards, protests, IT Dashboard investments, NAICS / PSC / SIN codes by name or keyword. Use first when you have a string and need to discover what's in the data; returns identifiers and short previews for use with other tools. | | `search` | Search across 13 record types: `contract` (default), `idv`, `vehicle`, `ota`, `otidv`, `subaward`, `organization`, `protest`, `gsa_elibrary`, `lcat`, `itdashboard`, `grant`, and `budget_account` β€” or `all`. Filter by vendor, agency, NAICS, PSC, dates, keyword, and many other criteria. Set `include_summary=true` to profile a capped sample of the matches (see [below](#include_summary-is-a-sample-not-a-market-total)). | | `search_opportunities` | Search open opportunities and agency forecasts. Filter by agency, NAICS, PSC, set-aside type, response deadline, notice type, keyword, and other criteria. Type defaults to `opportunity`; pass `type="forecast"` for forecast data. | | `get_details` | Get detailed information for a single item by ID and type. Supported types: `entity`, `contract`, `idv`, `vehicle`, `opportunity`, `ota`, `otidv`, `organization`, `subaward`, `protest`, `sin`, `gsa_elibrary_contract`, `itdashboard`. Use after `search` or `resolve` to drill into a specific record. Optional `include_related=True` enriches the response (see "Enrichment matrix" below). IT Dashboard `business_case_html` content requires Business+. | | `fetch_api_docs` | Fetch curated, LLM-friendly markdown documentation for a single Tango resource. Sections: `budget_accounts`, `contracts`, `entities`, `forecasts`, `gsa-elibrary`, `idvs`, `itdashboard`, `lcats`, `metrics`, `opportunities`, `otas`, `otidvs`, `protests`, `resolve`, `response-shaping`, `subawards`, `vehicles`. | ### Enrichment matrix (`get_details(..., include_related=True)`) | Type | Adds when `include_related=True` | | --- | --- | | `entity` | Socioeconomic status + 10 most recent contracts | | `contract` | Full detail + subawards | | `idv` | Full detail + child awards + transactions + CALC labor rates | | `vehicle` | Full detail + awardees + task orders | | `opportunity` | Full detail (attachments, notice history, primary contact) | | `ota` / `otidv` | Full detail + child awards / OTAs + transactions | | `organization` | Detail + child organizations | | `protest` | Detail + dockets + related opportunities / contracts | | `sin` | Detail + GSA eLibrary contracts (Schedule holders) | | `gsa_elibrary_contract` | Detail (no further enrichment) | | `itdashboard` | Detail + nested CIO evaluation, contracts, projects, funding, performance metrics. The `business_case_html` HTML blob requires Business+ tier. | Enrichment failures degrade gracefully β€” if a related-data fetch fails, the main object is still returned with empty related blocks. ### `include_summary` is a sample, not a market total `search(..., include_summary=true)` returns a statistical profile β€” `total_obligated`, `top_vendors`, `set_aside_distribution`, `naics_distribution`, `org_distribution` β€” computed over **at most 250 matching records**. That is a hard cap, not a ceiling a narrow filter escapes: the server fetches up to 250 rows and aggregates those. When more records match, the response sets `is_capped_sample` and includes a `_note` naming how many of the total were analyzed. Two limits worth knowing before you use it: - **Don't report `total_obligated` as market size.** It is the sum over the sampled rows. Narrow the filters until the match count falls under the cap if you need the sample to be the whole population. - **The distributions are awarding-side.** `org_distribution` is keyed on `awarding_office`, so a summary cannot break spending down by *funding* organization even when you filtered on `funding_org`. For true full-population aggregates, computed server-side over every matching record: | You want | Use | | --- | --- | | One vendor's entire award history | `get_details(type="entity", fields="past_performance(summary,top_agencies)")` | | An organization's obligations, including its whole subtree | `search(type="organization", fields="fh_key,name,total_obligations,tree_obligations")` | | Appropriations-level totals | `search(type="budget_account")` β€” see [Budget](../api-reference/budget.md) | ## Resources The server also exposes static MCP resources. Clients that support resource fetching can pull curated reference content without a tool call: | URI | Content | | --- | --- | | `tango://guides/federal-procurement` | Overview guide: how federal procurement data fits together. | | `tango://guides/api-reference` | Quick reference: enums, sorting fields, response shaping, recipes. | | `tango://reference/set-asides` | Set-aside type codes and meanings. | | `tango://reference/protests` | Background on bid protests (GAO / SBA OHA). | | `tango://reference/naics/{code}` | NAICS code lookup. | | `tango://reference/psc/{code}` | PSC (Product / Service Code) lookup. | | `tango://reference/sin/{code}` | GSA MAS SIN lookup. | ## Configuration - **API key vs OAuth:** Send your Tango API key in the `X-Tango-API-Key` header, or use `Authorization: Bearer ` with an OAuth access token from [tango.makegov.com](https://tango.makegov.com). - **Endpoint:** The MCP endpoint is **`https://tango.dev/mcp`** (HTTP transport). `https://govcon.dev/mcp` reaches the same server and continues to work. - **Response format:** The hosted server returns responses in **TOON** (Token-Oriented Object Notation) by default β€” a compact serialization that is roughly 30–60% smaller than JSON for typical responses. To force standard JSON, set `TANGO_RESPONSE_FORMAT=json` (relevant when self-hosting; the hosted server returns TOON). ### Self-hosting / local environment variables If you run the server locally (e.g. via stdio for development), the following environment variables are recognized: | Variable | Purpose | | --- | --- | | `TANGO_API_KEY` | Default API key (used when no `X-Tango-API-Key` / `Authorization` header is supplied; stdio mode only). | | `TANGO_RESPONSE_FORMAT` | `json` to force JSON output. Default is TOON. | | `TRANSPORT` | `http` to switch from stdio to streamable-HTTP transport. | | `TANGO_TELEMETRY` | `1` to log per-tool duration / token counts / status to stderr as JSON. | | `TANGO_LOG_USER_FINGERPRINT` | `1` to log a stable hash of the API key (not the key itself) for correlation. | | `SENTRY_ENABLED` | `1` to enable optional Sentry error monitoring. | ## Notable behaviors The server includes several robustness features worth knowing about when integrating: - **Strict argument validation.** Unknown tool arguments are rejected with a structured error that lists the valid arg names β€” no silent drops. Pass `type` not `record_type`, etc. - **Zero-result hints.** When a search returns no results, the response includes a `_hint` with the active filters and broaden-query guidance β€” helpful for LLM agents that would otherwise guess randomly. - **Ordering-alias rewrite.** LLM-friendly sort field names like `expiring`, `date`, `value`, and `amount` are rewritten to API-valid values (`award_date`, `obligated`, `total_contract_value`). - **Parameter coercion.** Bare strings for array fields (`naics_codes`, `psc_codes`, `set_aside_types`) are wrapped automatically. `active` accepts `"true"` / `"false"`. `notice_type` accepts both code letters (`p`, `k`, `o`, `a`, `m`, `r`, `s`, `u`, `i`, `g`) and full names (`"Solicitation"`, `"Sources Sought"`, etc.). - **Circuit breaker.** After 3 transient upstream failures (502 / 503 / 504 / timeout) within 60 seconds, the server short-circuits with `UpstreamUnavailableError`. A probe is allowed every 10 seconds during the cooldown. - **Tier-aware errors.** Tier-gated endpoints (e.g. CALC labor rates) return a typed error with an upgrade hint rather than a raw HTTP exception. ## Troubleshooting **424 error from OpenAI** β€” OpenAI can only reach publicly accessible servers. Use the hosted endpoint `https://tango.dev/mcp`. **Empty results** β€” Verify your API key is valid. Check that the UEI, NAICS code, or other identifiers you are using exist in the Tango database. **502 Bad Gateway / "Failed to open SSE stream"** β€” The server uses HTTP transport and JSON responses, not SSE. If the client expects SSE, use a client that supports JSON mode. **403 when calling the server URL** β€” A proxy or firewall may be blocking the request to `https://tango.dev/mcp`. Ensure your client sends the API key or Bearer token as described above. **"Invalid API key or authentication required"** β€” When connecting to `https://tango.dev/mcp`, the server must receive either your Tango API key in the `X-Tango-API-Key` header or an OAuth bearer token in the `Authorization: Bearer ` header. Ensure your MCP client is configured to send one of these. ## Get help For API keys, account issues, or MCP connection problems: - **Email:** [support@makegov.com](mailto:support@makegov.com) - **Tango web interface:** [tango.dev](https://tango.dev) β€” sign in to manage your account and API keys. ## Privacy Data handling and privacy are described in our [Privacy policy](https://tango.dev/privacy). ## References - [Tango connector in Anthropic's directory](https://tango.dev/claude) β€” one-click install for Claude - [Tango app in the ChatGPT app directory](https://tango.dev/chatgpt) β€” one-click install for ChatGPT - `https://tango.dev/mcp` β€” Hosted Tango MCP server (HTTP transport). `https://govcon.dev/mcp` is an alias for the same server. - [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2025-11-25) - [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) β€” Interactive testing and debugging for MCP servers - [OpenAI MCP Documentation](https://platform.openai.com/docs/guides/tools-remote-mcp) - [Tango API](https://tango.dev) --- --- description: "Which official Tango SDK to use, Python or Node/TypeScript, and what both cover." tags: [sdk, reference] updated: 2026-09-21 --- # SDKs Idiomatic clients for the Tango API in your language of choice. | SDK | Status | Docs | | --- | ------ | ---- | | **Python** | Stable | [tango-python](python/index.md) | | **Node / TypeScript** | Stable | [tango-node](node/index.md) | Both SDKs cover the full API surface, handle pagination, share the API's response-shaping conventions, and include webhook signature verification. Their retry behavior differs: the Node client retries retryable failures by default, while the Python client makes one request per method call and exposes rate-limit details so your application can decide when to retry. ## Which one should I use? - **Python** if you're doing data work, scripting, or building backend services in Python. - **Node / TypeScript** if you're building a web app, serverless function, or anything in the JS/TS ecosystem. Choose by runtime rather than surface area; both clients expose the same Tango resources, but their language-specific transport and error-handling behavior is documented on each SDK's Client page. ## Next step Open your SDK's overview, install the package, and run its first-request example. Then use the language-neutral [API reference](../api-reference/index.md) for resource filters and the SDK's API reference for exact method names. ## More languages? Not on the roadmap yet. The OpenAPI schema at [tango.dev/api/](https://tango.dev/api/) is suitable for generating clients in other languages β€” open an issue if you want one we should support directly. --- # Tango Node SDK – API Reference This document provides the full API reference for the **Node.js / TypeScript** version of the Tango SDK. It is a translation of the Python SDK documentation, rewritten for JavaScript runtime semantics, async/await, and the TypeScript type system. ## Importing ```ts import { TangoClient, ShapeConfig } from "@makegov/tango-node"; // Models (optional) import type { Contract } from "@makegov/tango-node/models"; ``` All methods are async and return Promises. --- ## Agencies ### `listAgencies(options?)` List federal departments and subagencies. ```ts const resp = await client.listAgencies({ page: 1, limit: 25 }); ``` #### Parameters | Name | Type | Description | | ------- | -------- | ------------------------------------------- | | `page` | `number` | Page number (default 1). | | `limit` | `number` | Max results per page (default 25, max 100). | #### Returns (Agencies) `PaginatedResponse` --- ### `getAgency(code)` Fetch a single agency by its code. ```ts const agency = await client.getAgency("2000"); ``` Returns a shaped Agency object. Responses are materialized via the dynamic model pipeline (dates parsed, nested objects built). --- ## Contracts ### `listContracts(options)` Search and list contract records. ```ts const resp = await client.listContracts({ keyword: "cloud", naics_code: "541511", shape: ShapeConfig.CONTRACTS_MINIMAL, flat: true, }); ``` #### Search / Filter Parameters These mirror the Python SDK: | Filter | Maps to API param | | ---------------- | ----------------- | | `keyword` | `search` | | `naics_code` | `naics` | | `psc_code` | `psc` | | `recipient_name` | `recipient` | | `recipient_uei` | `uei` | | `set_aside_type` | `set_aside` | `key` is also a typed filter β€” pass a contract key (or several separated by `|`) to fetch specific records through the list endpoint. The same `key` filter exists on `listIdvs`, `listOtas`, and `listOtidvs`. `recipient_uei` (and `uei` on `listIdvs`, `listOtas` and `listOtidvs`) accepts several UEIs joined by `|`, matching awards to any of them, up to 500 (Tango API 5.11.0). The SDK passes the value through unchanged. `commercial_item_acquisition_procedures` filters by the FPDS commercial item acquisition procedures code (Tango API 5.10.0): `A` (commercial products/services), `B` (products or services pursuant to FAR 12.102(f)), `C` (services pursuant to FAR 12.102(g)), `D` (commercial procedures not used) or `E` (DoD Section 803 Commercial Solutions Opening). Codes are case-insensitive and pipe-separated for OR, e.g. `"A|E"`; an unknown or multi-character code matches nothing. It is also typed on `listIdvs`, `listIdvAwards` and `listIdvChildIdvs`, but the API does not offer it on OTAs or OT IDVs. **Obligations by fiscal year β€” `obligations_by_fiscal_year(fiscal_year, obligated)`** (Tango API 5.11.0): ```ts import type { FiscalYearObligation } from "@makegov/tango-node/models"; const resp = await client.listContracts({ piid: "SOME_PIID", shape: "key,piid,obligated,obligations_by_fiscal_year(fiscal_year,obligated)", }); for (const year of (resp.results[0].obligations_by_fiscal_year ?? []) as FiscalYearObligation[]) { console.log(year.fiscal_year, year.obligated); // number, decimal string } ``` - Sums the award's transactions per federal fiscal year (October 1 starts the next fiscal year), oldest year first, each rounded to cents. A de-obligation nets against its own year, so a year can be zero or negative. - Returned only when named: no default shape includes it. - The same expand works on `listIdvs()`, `listOtas()`, `listOtidvs()` and the `get*` methods. On IDVs and OT IDVs the API always sends `null`, because their transactions report a running lifetime total rather than each action's obligation. - The API also sends `null` for a contract or OTA with no dated transactions. On the shaped methods (`listContracts`, `getContract`, `listIdvs`, `getIdv` and the IDV child lists) the client reads a `null` nested list as `[]`, as it does for every nested list; `listOtas()` and `listOtidvs()` return the API's JSON as-is. Sorting: ```ts sort: "award_date", order: "desc" // -> ordering="-award_date" ``` Pagination + shaping options: ```ts shape: string, flat: boolean, flatLists: boolean, page: number, limit: number, cursor: string, // mutually exclusive with `page` β€” if provided, `page` is ignored ``` Contracts support both **page-based** and **cursor-based** pagination. Use `cursor` for deep pagination (faster and more stable on large result sets); use `page` for small offsets or when you need to jump to a specific page. `page` and `cursor` are mutually exclusive β€” if you pass `cursor`, the SDK ignores `page`. #### Returns (Contracts) `PaginatedResponse` materialized according to the requested shape. Date/datetime fields are parsed, decimals normalized to strings, nested recipients, agencies, and locations are objects. --- ## Vehicles Vehicles provide a solicitation-centric grouping of related IDVs. ### `listVehicles(options)` ```ts const resp = await client.listVehicles({ search: "GSA schedule", shape: ShapeConfig.VEHICLES_MINIMAL, page: 1, limit: 25, }); ``` Supported parameters: - `search` (vehicle-level full-text search) - `page`, `limit` (max 100) - `shape`, `flat`, `flatLists` Company counts (on both the list and detail defaults; neither is orderable or filterable): - `holder_count`: distinct companies holding one of the vehicle's IDVs. - `order_winner_count`: distinct companies that have won a task order under the vehicle. - `awardee_count`: deprecated alias of `order_winner_count` (same value), removed at the API's next major version. ### `getVehicle(uuid, options?)` ```ts const vehicle = await client.getVehicle("00000000-0000-0000-0000-000000000001", { shape: ShapeConfig.VEHICLES_COMPREHENSIVE, }); ``` Notes: - On vehicle detail, `search` filters expanded `awardees(...)` when included in your `shape` (it does not filter the vehicle itself). - When using `flat: true`, you can override the joiner with `joiner` (default `"."`). ### `listVehicleAwardees(uuid, options?)` ```ts const awardees = await client.listVehicleAwardees("00000000-0000-0000-0000-000000000001", { shape: ShapeConfig.VEHICLE_AWARDEES_MINIMAL, }); ``` --- ## IDVs IDVs (indefinite delivery vehicles) are the parent β€œvehicle award” records that can have child awards/orders under them. ### `listIdvs(options)` ```ts const idvs = await client.listIdvs({ limit: 25, cursor: null, shape: ShapeConfig.IDVS_MINIMAL, awarding_agency: "4700", }); ``` Notes: - This endpoint uses **keyset pagination** (`cursor` + `limit`) rather than `page`. ### `getIdv(key, options?)` ```ts const idv = await client.getIdv("SOME_IDV_KEY", { shape: ShapeConfig.IDVS_COMPREHENSIVE, }); ``` ### `listIdvAwards(key, options?)` Lists child awards (contracts) under an IDV. ```ts const awards = await client.listIdvAwards("SOME_IDV_KEY", { limit: 25 }); ``` ### `listIdvChildIdvs({ key, ...options })` ```ts const children = await client.listIdvChildIdvs({ key: "SOME_IDV_KEY", limit: 25 }); ``` ### `listIdvTransactions(key, options?)` ```ts const tx = await client.listIdvTransactions("SOME_IDV_KEY", { limit: 100 }); ``` --- ## Entities ### `listEntities(options)` ```ts const resp = await client.listEntities({ search: "Acme", shape: ShapeConfig.ENTITIES_MINIMAL, }); ``` Filters: - `search` - `cage` (CAGE code, typed alongside the existing `cage_code`) - any field names supported by the API ### `getEntity(uei, options?)` Fetch a single entity by UEI or CAGE. Returns a shaped entity object with nested addresses/fields based on the shape. --- ## Forecasts ### `listForecasts(options)` Forecast search, with optional shaping. `id` is a typed filter for fetching specific forecast records through the list endpoint. --- ## Opportunities ### `listOpportunities(options)` Search SAM.gov opportunities with shaping. `opportunity_id` is a typed filter for fetching specific opportunities through the list endpoint. `awarded` (boolean) filters by whether the opportunity has an award, either posted on it or linked to it from a separate award notice, and `awardee_uei` filters by the awardee's UEI (case-insensitive; OR several with `|`). Both search every opportunity rather than only active ones, and both require Tango API 5.5.0. **Attachment counts.** `meta(attachments_count,files_count,links_count)` counts an opportunity's attachments. An attachment's `type` is `file` (a document; only a file has extracted text) or `link` (a URL the notice lists). `files_count` and `links_count` count each, and `attachments_count` still counts every attachment, links included. An attachment of any other type counts only in the total, so `files_count + links_count` need not equal `attachments_count`. Both new counts are `null` until the opportunity has been counted, so read `null` as unknown, not zero. They require Tango API 5.9.0 and are not in the SDK's default shape; name them in `shape`. ```ts const page = await client.listOpportunities({ shape: "opportunity_id,title,meta(attachments_count,files_count,links_count)", }); ``` **Extraction status.** `attachments(extraction_status)` reports where text extraction stands for each attachment: `pending`, `extracting`, `completed`, `failed` or `unsupported`, so you can tell why `extracted_text` is missing (Tango API 5.11.0). It works on notices too, and like every attachment field it must be named, e.g. `shape: "opportunity_id,attachments(name,extracted_text,extraction_status)"`. --- ## Notices ### `listNotices(options)` **Attachment counts.** `file_count` and `link_count` sit beside `attachment_count` and follow the same rules as the opportunity counts above: files are documents, links are URLs the notice lists, `attachment_count` still counts every attachment, the two need not add up to it, and each is `null` (unknown, not zero) until the notice has been counted. They require Tango API 5.9.0; name them in `shape`, e.g. `shape: "notice_id,title,attachment_count,file_count,link_count"`. --- ## Grants ### `listGrants(options)` --- ## Organizations / Offices / Departments ### `listOrganizations(options?)` The canonical agency/department/office hierarchy. `level` filters by hierarchy depth: `1` = department, `2` = agency, `3` = sub-agency, and so on. ```ts const orgs = await client.listOrganizations({ level: 1, // 1 = department, 2 = agency, 3 = sub-agency, … include_inactive: false, search: "Defense", limit: 25, }); ``` ### `getOrganization(identifier)` ```ts const org = await client.getOrganization("ORG_KEY"); ``` ### `listOffices(options?)` ```ts const offices = await client.listOffices({ search: "acquisitions" }); ``` ### `getOffice(code)` ```ts const office = await client.getOffice("4732XX"); ``` ### `listDepartments(options?)` > **Deprecated.** Use `listOrganizations({ level: 1 })` instead. The standalone departments endpoint is retained for backward compatibility and will be removed in a future API version. ```ts const depts = await client.listDepartments({ page: 1, limit: 25 }); ``` ### `getDepartment(code)` ```ts const dept = await client.getDepartment("097"); ``` --- ## OTAs Other Transaction Agreements β€” non-FAR-based awards. ### `listOtas(options?)` Uses **keyset pagination** (`cursor` + `limit`). ```ts const otas = await client.listOtas({ limit: 25, awarding_agency: "4700" }); ``` ### `getOta(key)` ```ts const ota = await client.getOta("OTA_KEY"); ``` --- ## OTIDVs Other Transaction IDVs β€” umbrella OT agreements with child awards. ### `listOtidvs(options?)` Uses **keyset pagination** (`cursor` + `limit`). ```ts const otidvs = await client.listOtidvs({ limit: 25 }); ``` ### `getOtidv(key)` ```ts const otidv = await client.getOtidv("OTIDV_KEY"); ``` ### `listOtidvAwards(key, options?)` ```ts const awards = await client.listOtidvAwards("OTIDV_KEY", { limit: 25 }); ``` --- ## Subawards ### `listSubawards(options?)` ```ts const subs = await client.listSubawards({ prime_uei: "ABC123DEF456", limit: 25 }); ``` --- ## GSA eLibrary Contracts ### `listGsaElibraryContracts(options?)` ```ts const contracts = await client.listGsaElibraryContracts({ schedule: "MAS", limit: 25 }); ``` ### `getGsaElibraryContract(uuid, options?)` Fetch a single GSA eLibrary contract by UUID, with the standard `shape` / `flat` / `flatLists` / `joiner` options. Defaults to `ShapeConfig.GSA_ELIBRARY_CONTRACTS_MINIMAL` when no shape is passed. ```ts const contract = await client.getGsaElibraryContract("00000000-0000-0000-0000-000000000001", { shape: ShapeConfig.GSA_ELIBRARY_CONTRACTS_MINIMAL, }); ``` --- ## GSA eBuy Requests for quotes, proposals and information (RFQs, RFPs, RFIs) posted to GSA eBuy under GSA schedule contracts. Requires the Pro tier or above; below it the request endpoints return 403. eBuy results are scoped to the GSA schedule contracts linked to your account. A caller with no linked contract gets an **empty list, not an error** β€” call `getEbuyAccess()` to tell "no access" from "no matches". ### `listEbuyRequests(options?)` ```ts const requests = await client.listEbuyRequests({ sin: "54151S", status: "Open", close_date_after: "2026-10-01", limit: 25, }); ``` #### Parameters (GSA eBuy) | Name | Type | Description | | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `search` | `string` | Full-text search over title, description, reference number, request id and attachment text. Ranks by relevance unless `ordering` is given. | | `rfq_id` | `string` | eBuy request id, exact (e.g. `RFQ1835158`). | | `reference_number` | `string` | The buyer's own solicitation number; dashed and undashed spellings both match. | | `request_type` | `string` | `RFQ`, `RFP` or `RFI`. | | `status` | `string` | `Open` or `Cancelled` β€” frozen at the last-seen state (see below). | | `sin` | `string` | Special Item Number the request was posted under. | | `schedule` | `string` | GSA schedule the request was posted under. | | `buyer_agency` | `string` | Buying department as fed, free text. | | `agency` | `string` | Agency name, abbreviation or code, including every sub-agency and office beneath it (Tango API 5.3.0+). | | `contract_number` | `string` | Narrow to one of your own linked contracts. A contract you do not hold returns nothing rather than an error. | | `issue_date_after` / `_before` | `string` | `YYYY-MM-DD`, inclusive. | | `close_date_after` / `_before` | `string` | `YYYY-MM-DD`, inclusive. | | `ordering` | `string` | `issue_date` (default `-issue_date`), `close_date`, `last_seen`, or `modified`; prefix `-` for descending. | Every filter except `contract_number` and the date bounds accepts `|` for OR. The standard `page` / `limit` / `shape` / `flat` / `flatLists` / `joiner` options apply. The default list shape is `rfq_id,request_type,title,schedule,sin,status,buyer_name,buyer_agency,buyer_agency_code,reference_number,issue_date,close_date,attachment_count,link_count,last_seen`. Three properties of the data worth knowing: - **`status` is frozen at the last-seen state.** eBuy only carries currently-active requests, so a request that closes stops appearing rather than getting a final row. `Open` means "open the last time it was seen" β€” use `last_seen` for staleness. - **The contract number a request was posted under is never returned** in any payload. - **`buyer_agency_code`** and several buyer and contracting-officer fields are sparse on older requests. ### `getEbuyRequest(rfqId, options?)` ```ts const request = await client.getEbuyRequest("RFQ1835158"); for (const attachment of request.attachments ?? []) { console.log(attachment.doc_seq_num, attachment.doc_name, attachment.is_link); } ``` Returns an `EbuyRequestRecord`. The default shape is every field plus `organization(*)` (the buying office, in the same shape as other resources' awarding office) and `attachments(*)`. A request outside your contract scope throws `TangoNotFoundError`, the same as an id that does not exist. **Reading a document's text β€” `attachments(extracted_text)`** (Tango API 5.9.1+): ```ts const request = await client.getEbuyRequest("RFQ1835158", { shape: "rfq_id,attachments(doc_seq_num,doc_name,extracted_text)", }); for (const attachment of request.attachments ?? []) { if ("extracted_text" in attachment) console.log(attachment.doc_name, attachment.extracted_text); } ``` `extracted_text` is the text extracted from an attachment's document. Three behaviors to know: - **It must be named.** Ask for it alone or alongside other attachment fields. - **Neither the default detail shape nor `attachments(*)` carries it.** - **The key is absent rather than null** for an attachment with no text: a link, an empty scan, or a document not yet extracted. Check with `in` rather than for a nullish value. ### `getEbuyAttachmentUrl(rfqId, docSeqNum)` ```ts const url = await client.getEbuyAttachmentUrl("RFQ1835158", 3852759); const res = await fetch(url); ``` Returns a presigned download URL for one attachment without downloading it. The URL expires after about five minutes, so fetch it promptly rather than storing it. - An attachment with `is_link: true` is an external link, not a stored document: the call throws `TangoEbuyAttachmentLinkError`, whose `url` is the link target. - A document that has not been captured yet throws `TangoNotFoundError`. ### `getEbuyAccess()` ```ts const access = await client.getEbuyAccess(); // { enabled: false, reason: "no_contract_grant", contracts: [] } ``` Returns `{ enabled, reason, contracts }`. `reason` is `"tier_required"` below the Pro tier, `"no_contract_grant"` when no contract is linked to your account, and `null` when `enabled` is true; `tier_required` wins when both apply. `contracts` lists your own active grants, sorted. --- ## Protests ### `listProtests(options?)` Bid protests from GAO, the Court of Federal Claims (COFC) and SBA OHA. ```ts const protests = await client.listProtests({ source_system: "gao", limit: 25 }); ``` `naics_code` is a typed filter sent to the API verbatim (it is **not** remapped to `naics`, unlike the contracts alias). ### `getProtest(caseId)` ```ts const protest = await client.getProtest("CASE_UUID"); ``` Takes the case's `case_id` UUID, not a case number. To look a case up by number, list with `case_number` and read `case_id` off the result. --- ## Contract Appeals Contract Disputes Act decisions from the two boards of contract appeals β€” the CBCA (civilian) and the ASBCA (defense). These are disputes under an existing contract; a challenge to an award is a bid protest, which is the separate [Protests](#protests) resource. ### `listContractAppeals(options?)` ```ts const appeals = await client.listContractAppeals({ board: "asbca", decision_date_after: "2026-01-01", limit: 25, }); ``` #### Parameters (Contract Appeals) | Name | Type | Description | | --------------------------------- | --------- | -------------------------------------------------------------------------------------- | | `search` | `string` | Ranked full-text search across the decision. | | `board` | `string` | `cbca` or `asbca`. | | `docket` | `string` | Docket number, as the board publishes it. | | `appellant` | `string` | Appellant name. | | `judge` | `string` | Deciding judge. | | `decision_type` | `string` | Normalized decision type. | | `decision_date_after` / `_before` | `string` | ISO date bounds on the decision date. | | `listed` | `boolean` | Whether the decision is currently on the board's published listing. | | `document_id` | `string` | The board's own document identifier. | | `ordering` | `string` | `decision_date` (default `-decision_date`), `appellant`, `first_listed_at`, or `rank`. | `rank` ordering is only meaningful with a non-empty `search`. The standard `page` / `limit` / `shape` / `flat` / `flatLists` / `joiner` options apply. Without a `shape` the API returns a core subset of the decision, so name the rest explicitly when you need it. `decision_text` is served on the Enterprise tier only, and below it the key is **absent rather than null** β€” test for presence, not for a nullish value. ### `getContractAppeal(uuid, options?)` ```ts const appeal = await client.getContractAppeal("00000000-0000-0000-0000-000000000001", { shape: "uuid,board,docket_numbers,decision_date,appellant,judge,decision_text", }); ``` Returns a `ContractAppealRecord`. Every property on it is optional, for the same two reasons: an unshaped list carries only the core subset, and `decision_text` is tier-gated. --- ## Federal Register Federal Register documents: rules, proposed rules, notices and presidential documents published since 1994. A document is identified by `uuid`. `document_number` is not unique on its own: the Federal Register reused some numbers before 2016, so `document_number` can return more than one document. ### `listFederalRegisterDocuments(options?)` ```ts const documents = await client.listFederalRegisterDocuments({ type: "Proposed Rule", comments_open: true, agency: "EPA", limit: 25, }); for (const doc of documents.results) { console.log(doc.document_number, doc.publication_date, doc.title, doc.comments_close_on); } ``` #### Parameters (Federal Register) | Name | Type | Description | | ------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search` | `string` | Ranked full-text search over the title, abstract and action. Wrap in double quotes for a phrase. | | `document_number` | `string` | Exact FR document number, e.g. `2016-31922`. OR several with `\|`. | | `type` | `string` | `Notice`, `Rule`, `Proposed Rule`, `Presidential Document`, `Correction`, `Sunshine Act Document` or `Uncategorized Document` (case-insensitive). OR several with `\|`. An unknown type is an error, not an empty page. | | `agency` | `string` | A Tango agency name, abbreviation, code or organization key, e.g. `EPA`. Matches a document when any agency it lists falls within that organization, so a department includes its sub-agencies. OR several with `\|`. | | `fr_agency` | `string` | The Federal Register's own agency slug, e.g. `environmental-protection-agency`. OR several with `\|`. | | `publication_date_after` / `_before` | `string` | Publication date range (`YYYY-MM-DD`). | | `effective_on_after` / `_before` | `string` | Effective date range (`YYYY-MM-DD`). | | `comments_close_on_after` / `_before` | `string` | Comment-deadline range (`YYYY-MM-DD`). | | `comments_open` | `boolean` | `true` for documents whose comment period closes today or later, `false` for those already closed. Documents with no comment deadline match neither. | | `cfr_title` | `string \| number` | A CFR title number, e.g. `40`. | | `cfr_part` | `string \| number` | A CFR part number, e.g. `52`. Requires `cfr_title`, and both must match the same CFR reference, so `cfr_title: 40, cfr_part: 52` finds 40 CFR 52. | | `significant` | `boolean` | Significant under Executive Order 12866. | | `rin` | `string` | A Regulation Identifier Number, e.g. `2060-AV16`. OR several with `\|`. | | `executive_order_number` | `string \| number` | Exact executive order number. | | `ordering` | `string` | `publication_date` (default `-publication_date`), `effective_on`, `comments_close_on`, `document_number` or `rank`. | `rank` ordering requires a non-empty `search`. The standard `page` / `limit` / `shape` / `flat` / `flatLists` / `joiner` options apply, and the list defaults to `ShapeConfig.FEDERAL_REGISTER_MINIMAL`. Documents published before 2008 are mostly `Uncategorized Document`, so a `type` filter undercounts that era. ### `getFederalRegisterDocument(uuid, options?)` ```ts const document = await client.getFederalRegisterDocument("00000000-0000-0000-0000-000000000001", { shape: "uuid,document_number,title,full_text", }); ``` Takes the document's `uuid`, not its `document_number`. To look one up by number, use `listFederalRegisterDocuments({ document_number })`. Defaults to `ShapeConfig.FEDERAL_REGISTER_COMPREHENSIVE`. - `agencies`, `cfr_references`, `dockets` and `topics` are the Federal Register's own structures, served as published. `agencies` carries Federal Register agency slugs, not Tango organization keys. - `full_text`, the document's plain text, is available on this method only and only when named in `shape`. It can run to several MB, so neither default shape includes it. - `publication_date`, `effective_on`, `comments_close_on` and `signing_date` are parsed to `Date`. The `FederalRegisterDocument` interface in `@makegov/tango-node/models` lists every field. --- ## IT Dashboard ### `listItDashboard(options?)` ```ts const investments = await client.listItDashboard({ search: "cloud", limit: 25 }); ``` ### `getItDashboard(uii)` ```ts const investment = await client.getItDashboard("023-000001234"); ``` `listItDashboard` also accepts `previous_uii` as a typed filter, for tracing an investment across UII renumbering. `agency` takes a Tango agency name, abbreviation, code or organization key (e.g. `EPA`) and matches the whole organization, so a department includes its sub-agencies; OR several with `|`. It is available at every plan and requires Tango API 5.3.0. --- ## Budget Accounts OMB budget appendix accounts with lifecycle amounts (requested β†’ enacted β†’ apportioned β†’ obligated β†’ outlayed), derived ratios, and trends. ### `listBudgetAccounts(options?)` ```ts const accounts = await client.listBudgetAccounts({ fiscal_year: 2025, agency_code: "097", unobligated_balance__gte: 1_000_000_000, ordering: "-unobligated_balance", }); ``` `ListBudgetAccountsOptions` types the **full** filter surface of `/api/budget/accounts/` β€” every numeric lifecycle, ratio, and trend field exposes an exact / `__gte` / `__lte` triplet, and categorical filters carry `__in` / `__icontains` variants. The range filters use the API's **dunder wire names** (double underscore, e.g. `fiscal_year__gte`) β€” these are passed through verbatim. A representative sample: | Filter family | Example params | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Identity / categorical | `federal_account_symbol`, `fiscal_year`, `agency`, `agency_code__in`, `bureau_name__icontains`, `bea_category`, `account_category__in`, `subfunction_code`, `account_title__icontains` | | Lifecycle amounts | `requested_ba__gte`, `enacted_ba__lte`, `apportioned__gte`, `obligated_total__gte`, `outlayed_total__lte`, `unobligated_balance__gte` | | Contract / assistance breakdowns | `contract_obligated__gte`, `assistance_outlayed__lte`, `contract_share_of_obligated_capped__gte` | | Ratios | `obligated_to_apportioned_pct__gte`, `apportioned_to_enacted_pct_capped__lte`, `outlayed_to_obligated_pct__gte`, `unobligated_pct__gte` | | Trends | `enacted_ba_yoy_pct__gte`, `obligated_yoy_pct__lte`, `enacted_ba_5yr_cagr__gte`, `ba_growth_next_year_pct__gte`, `actual_vs_requested_contract__gte` | See `ListBudgetAccountsOptions` in `src/client.ts` for the complete list β€” every filter is a typed, autocompleted option. Any of the numeric fields is a valid `ordering` target (`ordering: "-unobligated_balance"` ranks by largest headroom first), and `search` covers account title, agency name, and bureau name. With no `ordering`, rows come back newest fiscal year first, then by `enacted_ba` descending, with accounts that have no `enacted_ba` last. **Data through period.** Each row carries `data_through_period`, the File A fiscal period (1–12) the account-year's figures run through, so the latest fiscal year is partial until it reaches 12. It is null when the row has no File A data. `data_through_period`, `data_through_period__gte`, `data_through_period__lte` and `data_through_period__isnull` filter on it; for example, `data_through_period__isnull: false` keeps only rows with File A data. **Account category.** Each row carries `account_category` (`"budgetary"` or `"credit_financing"` today; treat it as an open string), and `account_category` / `account_category__in` filter on it. For example, `account_category: "budgetary"` leaves out credit financing accounts. **Source anomalies.** Each row carries `source_anomalies`, a list typed as `BudgetSourceAnomaly[]` that is `[]` when the row is clean. An entry records a source-data inconsistency the API found and what it did: `action: "capped"` means a served value was clamped to its bound (`reported_value` is what the source said, `served_value` is what the row carries), and `action: "flagged"` means the value is served as reported and only annotated. `code` is an open string (`contract_exceeds_obligations`, `assistance_exceeds_obligations` and `contract_without_obligations` today), `affected_fields` names the fields the anomaly touches, and `source` points at the upstream rows behind it. Every property on an entry is optional. There is no filter on anomalies, so check the list client-side: ```ts import type { BudgetAccount } from "@makegov/tango-node/models"; const res = await client.listBudgetAccounts({ fiscal_year: 2025, account_category: "budgetary" }); const capped = (res.results as BudgetAccount[]).filter((row) => row.source_anomalies?.some((a) => a.action === "capped")); ``` **Legacy aliases.** Three pre-1.2 option names are kept and remapped to the params the API actually understands: `fiscal_year_gte` β†’ `fiscal_year__gte`, `fiscal_year_lte` β†’ `fiscal_year__lte`, and `account_title` β†’ `account_title__icontains`. An explicitly passed dunder param wins over its alias. ### `getBudgetAccount(id, options?)` ```ts const account = await client.getBudgetAccount("ACCOUNT_ID"); ``` ### `getBudgetAccountQuarters(id, options?)` / `getBudgetAccountRecipients(id, options?)` Quarterly lifecycle history and top recipients for one account. ```ts const quarters = await client.getBudgetAccountQuarters("ACCOUNT_ID"); const recipients = await client.getBudgetAccountRecipients("ACCOUNT_ID"); ``` --- ## DIBBS DLA DIBBS solicitations and awards: RFQs, RFPs, and award history. ### `listDibbsRfqs(options?)` / `getDibbsRfq(uuid, options?)` ```ts const rfqs = await client.listDibbsRfqs({ nsn: "5310-01-234-5678", open: true, shape: ShapeConfig.DIBBS_RFQS_MINIMAL, }); ``` Typed filters: `nsn`, `part_number`, `fsc`, `solicitation`, `purchase_request`, `organization`, `status_code`, `set_aside`, `open`, `quantity_min` / `quantity_max`, `issue_date_after` / `issue_date_before`, `return_by_date_after` / `return_by_date_before`, `search`, `ordering`. ### `listDibbsRfps(options?)` / `getDibbsRfp(uuid, options?)` ```ts const rfps = await client.listDibbsRfps({ open: true, limit: 25 }); ``` Typed filters: `nsn`, `part_number`, `fsc`, `solicitation`, `organization`, `buyer_code`, `open`, `issued_date_after` / `issued_date_before`, `closes_date_after` / `closes_date_before`, `search`, `ordering`. ### `listDibbsAwards(options?)` / `getDibbsAward(uuid, options?)` ```ts const awards = await client.listDibbsAwards({ awardee_cage: "1ABC2", limit: 25 }); ``` Typed filters: `award_number`, `delivery_order_number`, `solicitation`, `purchase_request`, `nsn`, `part_number`, `fsc`, `awardee_cage`, `entity`, `organization`, `total_contract_price_min` / `total_contract_price_max`, `award_date_after` / `award_date_before`, `posted_date_after` / `posted_date_before`, `search`, `ordering`. Two API behaviors worth knowing: - `is_open` is **derived at query time** from `return_by_date` (RFQs) / `closes_date` (RFPs) β€” filter with the `open` option rather than shaping on `is_open`. - DIBBS `total_contract_price` is the **order** total repeated on every line item β€” never sum it across rows; deduplicate on award + delivery-order number first. --- ## State & Local (SLED) β€” Beta State, local and education procurement β€” solicitations that never appear on SAM.gov because they were never federal. Coverage is partial and grows one jurisdiction at a time. This data does not join to the federal data: no UEI, no PIID, no agency-hierarchy key and no NAICS/PSC crosswalk. `organization(*)` here is three strings, not the federal 7-key office payload. ### `listSledOpportunities(options?)` / `getSledOpportunity(opportunityId, options?)` ```ts const open = await client.listSledOpportunities({ state: "TX", response_deadline_before: "2026-10-01", ordering: "response_deadline", }); ``` Typed filters: `state`, `jurisdiction`, `status`, `active`, `agency`, `solicitation_number`, `solicitation_type`, `has_documents`, `revision_kind`, `naics`, `nigp`, `unspsc`, `category`, `category_code`, `posted_after` / `posted_before`, `response_deadline_after` / `response_deadline_before`, `first_seen_after` / `first_seen_before`, `change_seen_after`, `modified_after` / `modified_before`, `platform`, `native_id`, `external_id`, `search`, `ordering`. **Two defaults to know before your first call:** - **Passing neither `status` nor `active` returns open solicitations only.** Only about a fifth of the corpus is open, and a portal drops a closed solicitation rather than restating it, so the API defaults the list to `status=open`. Pass an explicit `status` to page the whole corpus; `status: "open|unknown"` also reaches the standing rosters and dateless RFIs that `unknown` covers. `getSledOpportunity()` returns a solicitation whatever its status. - **`status` is Tango's answer, not the portal's.** It is derived from the portal's word, the deadline and the clock, and refreshed every fifteen minutes. The portal's own word is served as `source_status`, is frozen at last capture, and is not filterable β€” most of what it calls open already has a passed deadline. `?search=` is ranked over title, agency, identifiers, category labels and description, widened by the solicitations whose _attachment text_ matched. A row that matched on its description carries a `snippet` with the matching passage; a title-or-agency match honestly carries none. Attachment matching contributes ids only β€” a caller learns _that_ a document matched, never what it said. `category_codes` scheme tagging is mid-migration, so **`naics` matches only the small tagged share**. Use `category_code` to match a code under any scheme, including the untagged pre-migration strings. ```ts const row = await client.getSledOpportunity(id, { shape: "opportunity_id,title,status,meta(*),attachments(*),revisions(*)", }); ``` `meta.attachment_count` can be **lower** than `row.attachments.length`. Some portals auto-generate a cover sheet alongside the real documents; it is listed and flagged `is_generated_summary` but excluded from the count and from `has_documents`. The count answers "does this record hold its solicitation package"; the array answers "what files exist". `size_bytes` and `char_count` only mean something as a pair. **Reading a document body β€” `attachments(extracted_text)`:** ```ts const row = await client.getSledOpportunity(id, { shape: "opportunity_id,attachments(name,size_bytes,extracted_text)", }); ``` Requires a **Small plan or above** and Tango API 4.25.1+. Three rules: - **You have to name it.** `attachments(*)` does not carry the body and neither `ShapeConfig` default names it β€” the API only resolves it for a caller who asked, so a default would make every detail fetch pay for a document nobody wanted to read. - **The key is absent, not null**, whenever the text is not being served to you: below Small (withheld and named in `meta.upgrade_hints`), on a contested document, or where it could not be resolved. - **A contested document never returns text**, at any plan β€” its stored bytes disagree with what the record advertised. Searching document text and reading it are separate. `search` matches inside attachment text on **every plan** and returns no fragment of it; the body is a per-record read on Small and above. `raw(*)` needs a Small plan or above and is explicitly unstable: its shape varies by portal platform. ### `listSledOpportunityRevisions(opportunityId, options?)` ```ts const revisions = await client.listSledOpportunityRevisions(id, { kind: "deadline_change" }); ``` Typed filters: `kind`, `source_declared`, `observed_after` / `observed_before`. `observed_at` is the scrape that saw the change, not the date the agency made it. No state portal emits amendment notices, so `kind` is Tango's inference from the diff on about 95% of revisions, resolution is that state's crawl cadence, and history starts when Tango began reading the jurisdiction rather than when the solicitation was posted. Unlike the `revisions(*)` expand, this route serves `enrichment` rows β€” Tango's own detail fetch filling in coverage rather than an agency amendment. Pass `kind: "enrichment"` for only those. `changes` (the per-field before and after) needs a Small plan, which is why it is left out of `SLED_REVISIONS_MINIMAL`; `changed_fields` is in the default and available at every plan. ### `getSledCoverage()` ```ts const coverage = await client.getSledCoverage(); for (const row of coverage.states as Array>) { console.log(row.state, row.total_count, row.by_status, row.last_change_observed_at); } ``` **Call this before treating a per-state count as market size.** A thin result for a state is at least as likely to be a portal Tango does not read as a quiet market, and that is the ambiguity this endpoint exists to resolve. Every state row carries all five status buckets whether or not they have rows, so a total and two buckets never invite subtraction. Takes no parameters and is neither shaped nor paginated. ### `listSledForecasts(options?)` / `getSledForecast(forecastId, options?)` ```ts const forecasts = await client.listSledForecasts({ state: "MD", advertisement_after: "2026-10-01" }); ``` Typed filters: `state`, `agency`, `procurement_category`, `procurement_method`, `contract_number`, `incumbent_name`, `advertisement_after` / `advertisement_before`, `first_seen_after` / `first_seen_before`, `modified_after` / `modified_before`, `search`, `ordering`. - **Forecasts carry no liveness at all** β€” no deadline to have passed, so no `status`, no `active`, and no open-only default. Currency is the caller's call from `estimated_advertisement_date`. - `estimated_advertisement_date` is the **start of the published quarter**, not a posting date. `estimated_advertisement_raw` keeps the portal's own words (`"Q3 (Jan.-March 2027)"`), and a large share of rows publish no quarter at all. - `estimated_value(min,max,raw)` is parsed from a free-text award band at serve time. **A band naming one number is a floor, so `max` is null** β€” never read a missing `max` as an unbounded ceiling. - `incumbent_name` is published text, not a resolved Tango entity. --- ## Exclusions SAM.gov exclusion records (debarments, suspensions, and other ineligibility actions). ### `listExclusions(options?)` / `getExclusion(exclusionKey, options?)` ```ts const exclusions = await client.listExclusions({ active: true, classification_type: "Firm", shape: ShapeConfig.EXCLUSIONS_MINIMAL, }); ``` Typed filters: `uei`, `entity_uei`, `cage_code`, `npi`, `classification_type`, `exclusion_type`, `exclusion_program`, `excluding_agency_code`, `excluding_agency_name`, `agency`, `active`, `delisted`, `activate_date_after` / `activate_date_before`, `termination_date_after` / `termination_date_before`, `update_date_after` / `update_date_before`, `search`, `ordering`. `is_currently_excluded` is **derived at query time** β€” filter with `active: true` for records currently in effect rather than shaping on it. `agency` scopes by the excluding agency: it takes a Tango agency name, abbreviation, code or organization key and matches the whole organization, so a department includes its sub-agencies (Tango API 5.3.0). The `organization(...)` expand and `organization_id` are accepted in `shape`. --- ## SBIR / STTR SBIR/STTR topics and DoD DSIP solicitation cycles. ### `listSbirTopics(options?)` / `getSbirTopic(topicId, options?)` ```ts const topics = await client.listSbirTopics({ agency: "DOD", year: 2026, shape: ShapeConfig.SBIR_TOPICS_MINIMAL, }); ``` Typed filters: `topic_number`, `solicitation_number`, `agency`, `activity`, `year`, `doc_source`, `cycle_name` (exact DSIP solicitation cycle, e.g. `DOD_SBIR_2026_P1_CBZ`; Tango API 5.3.1), `open_date_after` / `open_date_before`, `close_date_after` / `close_date_before`, `release_date_after` / `release_date_before`, `search`, `ordering`. ### `listSbirSolicitations(options?)` / `getSbirSolicitation(solicitationId, options?)` ```ts const cycles = await client.listSbirSolicitations({ program: "SBIR", year: 2026 }); ``` Typed filters: `solicitation_number`, `solicitation_status`, `program`, `activity`, `cycle_name`, `out_of_cycle`, `year`, `start_date_after` / `start_date_before`, `end_date_after` / `end_date_before`, `search`, `ordering`. --- ## LCATs ### `listLcats(options)` Requires either `{ uei }` (entity LCATs) or `{ idvKey }` (IDV LCATs) β€” throws `TangoValidationError` if neither is provided. ```ts const lcats = await client.listLcats({ uei: "ABCDEF123456" }); // or: const lcats = await client.listLcats({ idvKey: "GS-00F-XXXX" }); ``` ### `listIdvLcats(key, options?)` Labor Categories (`/api/idvs/{key}/lcats/`) attached to an IDV. ```ts const lcats = await client.listIdvLcats("GS-00F-XXXX", { limit: 25 }); ``` --- ## Metrics ### `listMetrics(options)` List metrics for a NAICS code, PSC code, or entity. `ownerType`, `ownerId`, `months`, and `periodGrouping` are all required. ```ts const metrics = await client.listMetrics({ ownerType: "naics", ownerId: "541511", months: 12, periodGrouping: "month", }); ``` ### `getNaicsMetrics(code, months, periodGrouping)` ```ts const m = await client.getNaicsMetrics("541511", 12, "month"); ``` ### `getPscMetrics(code, months, periodGrouping)` ```ts const m = await client.getPscMetrics("D302", 12, "month"); ``` ### `getEntityMetrics(uei, months, periodGrouping)` ```ts const m = await client.getEntityMetrics("ABCDEF123456", 12, "month"); ``` --- ## Reference Lookups ### `listNaics(options?)` / `getNaics(code)` ```ts const naics = await client.listNaics({ search: "software" }); const code = await client.getNaics("541511"); ``` ### `listPsc(options?)` / `getPsc(code)` ```ts const psc = await client.listPsc({ has_awards: true }); const code = await client.getPsc("D302"); ``` `has_awards: true` restricts the list to PSC codes that actually appear on awards. ### `listMasSins(options?)` / `getMasSin(sin)` ```ts const sins = await client.listMasSins(); const sin = await client.getMasSin("54151S"); ``` ### `listAssistanceListings(options?)` / `getAssistanceListing(number)` ```ts const listings = await client.listAssistanceListings(); const listing = await client.getAssistanceListing("10.310"); ``` ### `listBusinessTypes(options?)` / `getBusinessType(code)` ```ts const types = await client.listBusinessTypes(); const bt = await client.getBusinessType("A6"); ``` --- ## Resolve / Validate ### `resolve(input)` Resolve a free-text name to ranked entity or organization candidates. ```ts const result = await client.resolve({ name: "Lockheed Martin", target_type: "entity" }); // result.candidates[0].display_name, result.count ``` Required fields: `name`, `target_type` (`"entity"` | `"organization"`). ### `validate(input)` Validate the format of a PIID, solicitation number, or UEI. ```ts const result = await client.validate({ type: "uei", value: "ABCDEF123456" }); ``` Required fields: `type` (`"piid"` | `"solicitation"` | `"uei"`), `value`. --- ## Entity Sub-resources ### `listEntityContracts(uei, options?)` ```ts const contracts = await client.listEntityContracts("ABCDEF123456", { limit: 25 }); ``` ### `listEntityIdvs(uei, options?)` / `listEntityOtas(uei, options?)` / `listEntityOtidvs(uei, options?)` ```ts const idvs = await client.listEntityIdvs("ABCDEF123456"); ``` ### `listEntitySubawards(uei, options?)` / `listEntityLcats(uei, options?)` ```ts const subawards = await client.listEntitySubawards("ABCDEF123456"); ``` --- ## Agency Sub-resources ### `listAgencyAwardingContracts(code, options?)` ```ts const contracts = await client.listAgencyAwardingContracts("4700", { limit: 25 }); ``` ### `listAgencyFundingContracts(code, options?)` ```ts const contracts = await client.listAgencyFundingContracts("4700", { limit: 25 }); ``` --- ## Opportunities (attachments) ### `searchOpportunityAttachments(options)` Semantic search over opportunity attachments. `q` is required. ```ts const results = await client.searchOpportunityAttachments({ q: "cybersecurity", topK: 10, // max results (optional) includeExtractedText: false, // include raw extracted text (optional) }); ``` | Name | Type | Description | | ---------------------- | --------- | -------------------------------------- | | `q` | `string` | **Required.** Search query. | | `topK` | `number` | Maximum number of results to return. | | `includeExtractedText` | `boolean` | Whether to include raw extracted text. | --- ## Async Iteration All list methods can be iterated page-by-page via the generic `iterate()` helper or the named convenience wrappers. ### `iterate(method, options?)` ```ts for await (const contract of client.iterate("listContracts", { awarding_agency: "9700" })) { console.log(contract.piid); } ``` Named wrappers: `iterateContracts`, `iterateEntities`, `iterateOpportunities`, `iterateNotices`, `iterateGrants`, `iterateForecasts`, `iterateIdvs`, `iterateVehicles`, `iterateDibbsRfqs`, `iterateDibbsRfps`, `iterateDibbsAwards`, `iterateExclusions`, `iterateSbirTopics`, `iterateSbirSolicitations`, `iterateSledOpportunities`, `iterateSledForecasts`. --- ## Utility ### `getVersion()` ```ts const v = await client.getVersion(); ``` ### `listApiKeys()` ```ts const keys = await client.listApiKeys(); ``` --- ## Webhooks (v2) Webhook APIs let **Large / Enterprise** users manage subscription filters for outbound Tango webhooks. ### `listWebhookEventTypes()` Discover supported `event_type` values. ```ts const info = await client.listWebhookEventTypes(); ``` ### Webhook endpoints In production, MakeGov provisions the initial endpoint for you. These methods are most useful for dev/self-service. ```ts const endpoints = await client.listWebhookEndpoints({ page: 1, limit: 25 }); const endpoint = await client.getWebhookEndpoint("ENDPOINT_UUID"); ``` `createWebhookEndpoint` accepts the canonical snake_case shape (`callback_url`, `is_active`, `name`) or the legacy camelCase aliases (`callbackUrl`, `isActive`). If `name` is not provided, the SDK falls back to the URL host. ```ts // Create (canonical snake_case) const created = await client.createWebhookEndpoint({ name: "Prod receiver", callback_url: "https://example.com/tango/webhooks", // is_active defaults to true on create }); // Legacy camelCase still works: const created2 = await client.createWebhookEndpoint({ callbackUrl: "https://example.com/tango/webhooks", isActive: true, }); // Update await client.updateWebhookEndpoint(created.id, { is_active: false }); // Delete await client.deleteWebhookEndpoint(created.id); ``` ### `testWebhookEndpoint(endpointId)` Send an immediate test webhook to a specific endpoint. `endpointId` is required. The SDK sends `{ endpoint: }` in the request body (canonical post-tango#2252 cleanup; the API also accepts `endpoint_id` as a deprecated alias). ```ts const result = await client.testWebhookEndpoint("ENDPOINT_UUID"); console.log(result.success, result.status_code); ``` ### `testWebhookDelivery(options?)` _(legacy alias)_ Legacy wrapper around `testWebhookEndpoint`. `endpointId` may be omitted, in which case the API auto-resolves the user's only endpoint (404 if 0, 400 if >1). Prefer `testWebhookEndpoint` for new code. ```ts const result = await client.testWebhookDelivery({ endpointId: "ENDPOINT_UUID" }); ``` ### `getWebhookSamplePayload(options?)` Fetch Tango-shaped sample deliveries. ```ts const sample = await client.getWebhookSamplePayload({ eventType: "alerts.contract.match" }); ``` ### Webhook Alerts The Alerts API is a filter-subscription convenience layer on top of subscriptions. The SDK uses cleaner field names than the underlying API: `name` (vs `subscription_name`), `filters` (vs `filter_definition`), and singular `query_type` values. ```ts // Create const alert = await client.createWebhookAlert({ name: "New IT cloud contracts", // vs subscription_name on the wire query_type: "contract", // SINGULAR β€” not "contracts" filters: { naics: "541511" }, // vs filter_definition on the wire frequency: "realtime", // realtime | daily | weekly | custom cron_expression: undefined, // required if frequency === "custom" }); // List const alerts = await client.listWebhookAlerts({ page: 1, pageSize: 25 }); // Get / Update / Delete const got = await client.getWebhookAlert("ALERT_UUID"); await client.updateWebhookAlert("ALERT_UUID", { name: "Updated name" }); await client.deleteWebhookAlert("ALERT_UUID"); ``` Notes: - `name` and `query_type` are required on create. `query_type` is **singular** (e.g. `"contract"`, not `"contracts"`). - Only `name`, `frequency`, `cronExpression`, and `isActive` are writable via `updateWebhookAlert` β€” `query_type` and `filters` are read-only after creation. ### Deliveries / redelivery The API does not currently expose a public `/api/webhooks/deliveries/` or redelivery endpoint. Use: - `testWebhookEndpoint(endpointId)` for connectivity checks - `getWebhookSamplePayload()` for building handlers + alert payloads ### Receiving webhooks (signature verification) Every delivery includes an HMAC signature header: - `X-Tango-Signature: sha256=` Use the SDK's `verifySignature` helper β€” **do not hand-roll HMAC**. Verify against the **raw request body bytes** (not a re-serialized parsed body). Arg order is `(body, header, secret)`. ```ts import { verifySignature } from "@makegov/tango-node"; // Express β€” use express.raw() to get the body as a Buffer before JSON parsing app.post("/tango/webhooks", express.raw({ type: "application/json" }), (req, res) => { const rawBody = req.body; // Buffer const signatureHeader = req.headers["x-tango-signature"]; if (!verifySignature(rawBody, signatureHeader, process.env.TANGO_WEBHOOK_SECRET)) { return res.status(401).json({ error: "invalid_signature" }); } const payload = JSON.parse(rawBody.toString("utf8")); // ... handle payload.events ... res.json({ ok: true }); }); ``` `verifySignature` signature: ```ts function verifySignature(body: string | Buffer, header: string | null | undefined, secret: string): boolean; ``` Returns `false` for missing, malformed, or mismatched headers β€” never throws on mismatch. Uses `timingSafeEqual` internally. See [`WEBHOOKS.md` Β§ Signature verification](webhooks.md#signature-verification-in-your-handler) for Fastify and framework-agnostic examples. --- ## Error Types All thrown by async methods: - `TangoAPIError` - `TangoAuthError` - `TangoNotFoundError` - `TangoRateLimitError` - `TangoTimeoutError` - `TangoValidationError` - `TangoEbuyAttachmentLinkError` (a `TangoValidationError` with a `url`) - `ShapeError` - `ShapeParseError` - `ShapeValidationError` - `TypeGenerationError` - `ModelInstantiationError` ### Structured validation details on `TangoValidationError` When the API rejects a request with a structured 400 payload (shape errors especially), `TangoValidationError` exposes it without any hand-parsing of `responseData`: - `err.issues` β€” the API's issue entries, e.g. `[{ path: "tradeoff_process", reason: "unknown_field" }]`; an empty array when the response carried no structured issues. - `err.availableFields` β€” the endpoint's valid field set when the API includes one, else `null`. ```ts try { await client.listContracts({ shape: "key,tradeoff_process" }); } catch (err) { if (err instanceof TangoValidationError) { for (const issue of err.issues) console.error(issue.path, issue.reason); console.error("valid fields:", err.availableFields); } } ``` --- ## Pagination All list endpoints return: ```ts interface PaginatedResponse { count: number; countType: "exact" | "approximate" | null; next: string | null; previous: string | null; pageMetadata: Record | null; meta: Record | null; agencyWarnings: string[]; unresolvedAgencyTokens: Record; resolvedAgencies: Record>>; cursor: string | null; results: T[]; } ``` You can follow `next` / `previous` manually, pass `cursor` back on keyset-paginated endpoints, or use the `iterate*` helpers. `countType` says whether `count` is `"exact"` or `"approximate"`, read from the API's `X-Results-CountType` header on every list method; it is `null` when the API does not send it. Past 1,000 matches the contract, IDV, opportunity and notice lists may return a query-planner estimate as `count`, which can be well off; this is how to tell the two apart. It is taken from each response itself, so concurrent calls on one client cannot see each other's value the way `client.lastResponseHeaders` can. ### Response `meta` and agency-filter diagnostics `meta` carries any response-level metadata the API attached to the page β€” currently agency-filter resolution diagnostics. Three parsed views are always present (empty rather than throwing when `meta` is absent or malformed): - `agencyWarnings` β€” human-readable notes about agency tokens that were dropped or matched loosely; a non-empty list means part of your filter did not apply, so a small or empty `results` is not evidence that no such records exist. - `unresolvedAgencyTokens` β€” tokens that matched no organization, keyed by filter name; check this to fail loudly in a pipeline instead of trusting a silently-narrowed result set. - `resolvedAgencies` β€” the organizations each token actually resolved to, keyed by filter name; agency resolution is fuzzy, so checking the resolved `name` is the only way to catch a token matching an agency you did not intend. ```ts const resp = await client.listContracts({ awarding_agency: "Navvy" }); if (resp.agencyWarnings.length > 0) { console.warn(resp.agencyWarnings); console.warn("unresolved:", resp.unresolvedAgencyTokens); console.warn("resolved to:", resp.resolvedAgencies); } ``` Each entry of `meta.resolved_filters[]` that resolved also says how its token matched, in `matched_by` (Tango API 5.9.0+): - `key` β€” an organization UUID. - `code` β€” a 3-digit CGAC or 4-digit FPDS code. - `name` β€” the organization's name, including a department's everyday name, a spelling variant or a rename. - `alias` β€” an abbreviation or the organization's own alias. - `fuzzy` β€” a looser text match, worth checking against the resolved `name`. An entry that did not resolve has no `matched_by`. `meta` is typed `Record`, so narrow it before reading: ```ts type ResolvedEntry = { token: string; matched_by?: string; resolved: { name: string } | null }; const filters = (resp.meta?.resolved_filters ?? {}) as Record; for (const entry of filters.awarding_agency ?? []) { if (entry.matched_by === "fuzzy") { console.warn(`${entry.token} loosely matched ${entry.resolved?.name}`); } } ``` --- # Changelog All notable changes to `@makegov/tango-node` will be documented in this file. This project follows [Semantic Versioning](https://semver.org/). ## [Unreleased] ## [1.5.0] - 2026-10-29 ### Added - **`fsc` filter on `listDibbsRfqs()`, `listDibbsRfps()` and `listDibbsAwards()`** (Tango API 5.13.0). Filters by Federal Supply Class, the first four digits of the 13-digit NSN (NSN `6515012345678` is FSC `6515`). Each value must be exactly four digits, and several are OR'd with `|`, e.g. `"6515|6530"`; any other value makes the API return a 400. It combines with every other filter, `nsn` and `part_number` included. ### Changed - The vendored API contract now tracks Tango API 5.13.0. Its new financial-assistance award endpoints are not yet in the SDK and are recorded as known gaps in both conformance baselines. ## [1.4.1] - 2026-10-19 ### Changed - Dev-dependency security update: vitest and @vitest/coverage-v8 move to 4.1.12, which also brings @vitest/mocker to its patched release. The published package is unaffected; its only runtime dependency remains `commander`. ### Fixed - **`rateLimitInfo.limitType` now says which limit a 429 hit.** It only read an `X-RateLimit-Type` header the API never sends, so it was always `null`. On a 429 it now reads the rate's name from the API's detail (`Rate limit exceeded for daily. Please try again in 16 hours, 58 minutes.`) and reports `"daily"` or `"burst"`, matching tango-python's `limit_type`; a per-endpoint premium daily budget reports `"daily"`. It is `null` when the detail names neither, and an `X-RateLimit-Type` header still wins if one is sent. `TangoRateLimitError` gains the same `limitType`, plus `detail` with the API's message. ## [1.4.0] - 2026-10-19 ### Added - **`obligations_by_fiscal_year(fiscal_year, obligated)` shape expand on contracts, IDVs, OTAs and OT IDVs** (Tango API 5.11.0; parity with tango-python). Returns the award's obligations per federal fiscal year, oldest first, each rounded to cents. The new `FiscalYearObligation` model type and schema carry `fiscal_year` as an integer and `obligated` as a decimal, which the shaped response normalizes to a string like every money field. The API always sends `null` on IDVs and OT IDVs, whose transactions report a running lifetime total; the shaped contract and IDV methods read a `null` nested list as `[]`, as they do for every nested list. - **`attachments(extraction_status)` shape field on opportunities and notices** (Tango API 5.11.0; parity with tango-python). Reports `pending`, `extracting`, `completed`, `failed` or `unsupported` for each attachment, so you can tell why `extracted_text` is missing. `OpportunityAttachment` gains the field, typed as an open string. - **`commercial_item_acquisition_procedures` filter on `listContracts()` and `listIdvs()`** (Tango API 5.10.0; parity with tango-python), and on `listIdvAwards()` and `listIdvChildIdvs()`, which share those options. Filters by the FPDS commercial item acquisition procedures code: `A` (commercial products/services), `B` (products or services pursuant to FAR 12.102(f)), `C` (services pursuant to FAR 12.102(g)), `D` (commercial procedures not used) or `E` (DoD Section 803 Commercial Solutions Opening). Codes are case-insensitive and pipe-separated for OR, e.g. `"A|E"`; an unknown or multi-character code matches nothing. The API does not offer it on OTAs or OT IDVs, so `listOtas()` and `listOtidvs()` do not type it. - **`PaginatedResponse.countType`** (parity with tango-python). `"exact"` or `"approximate"`, read from the API's `X-Results-CountType` header on every list method (`null` when the API doesn't send it). Past 1,000 matches the contract, IDV, opportunity and notice lists may return a query-planner estimate as `count`, which can be well off; this is how a caller tells the two apart. It is taken from each response itself, so concurrent calls on one client can't see each other's value the way `lastResponseHeaders` can. - **Attachment file and link counts on opportunities and notices** (Tango API 5.9.0; parity with tango-python). Opportunities accept `meta(files_count,links_count)` beside `meta(attachments_count)`, and notices accept `file_count` and `link_count` beside `attachment_count`. An attachment's `type` is `file` (a document; only a file has extracted text) or `link` (a URL the notice lists). The new fields count each, and the existing total still counts every attachment, links included. An attachment of any other type counts only in the total, so files plus links need not equal it. The new fields are `null` until a record has been counted, so read `null` as unknown, not zero. `Opportunity` gains a typed `meta` (the new `OpportunityMeta`), `Notice` gains the three counts, and `docs/API_REFERENCE.md` documents the rules. The SDK's default shapes are unchanged, so name the fields in `shape`. - **Federal Register documents** (Tango API 5.3.0; parity with tango-python). `listFederalRegisterDocuments(options)` and `getFederalRegisterDocument(uuid, options)` over `/api/federal_register/`, plus a `FederalRegisterDocument` model interface, a registered shape schema, and the `FEDERAL_REGISTER_MINIMAL` / `FEDERAL_REGISTER_COMPREHENSIVE` defaults. These are the rules, proposed rules, notices and presidential documents published in the Federal Register since 1994. All seventeen of the API's filters are typed options on `ListFederalRegisterDocumentsOptions`, including `comments_open`, `cfr_title` / `cfr_part`, `rin`, and both `agency` (a Tango organization, including its sub-agencies) and `fr_agency` (the Federal Register's own agency slug). `getFederalRegisterDocument()` takes the document's `uuid`, not its `document_number`, because a document number is not unique on its own: the Federal Register reused some before 2016. Look a document up by number with `listFederalRegisterDocuments({ document_number })`. `full_text` is available on the detail method only when named in `shape`, and neither default shape includes it, since it can run to several MB. `ordering: "rank"` requires a non-empty `search`. Documents published before 2008 are mostly typed `Uncategorized Document`, so a `type` filter undercounts that era. - **Award fields on opportunities and notices** (Tango API 5.5.0; parity with tango-python). `ListOpportunitiesOptions` types the `awarded` and `awardee_uei` filters, both of which search every opportunity rather than only active ones. Opportunity shapes accept `awarded`, `award_count`, `award_date`, `award_amount`, `awardee`, `awardee_uei`, `solicitation_opportunity_id` and an `awards(...)` expand (a list, with `award_number`, `award_date`, `award_amount`, `awardee`, `awardee_uei`, `notice_id`, `opportunity_id`); notice shapes accept `award_date`, `award_amount`, `awardee` and `awardee_uei`. - **`agency` filter on `listBudgetAccounts()`, `listExclusions()` and `listItDashboard()`** (Tango API 5.3.0; parity with tango-python). It takes a Tango agency name, abbreviation, code or organization key (e.g. `EPA`) and matches the whole organization, so a department includes its sub-agencies; OR several with `|`. On exclusions it scopes by the excluding agency. On IT Dashboard it is available at every plan. - **`cycle_name` filter on `listSbirTopics()`** (Tango API 5.3.1), an exact match on the DSIP solicitation cycle such as `DOD_SBIR_2026_P1_CBZ`. SBIR topic shapes accept `cycle_name`. - **Budget account `source_anomalies` and `account_category`** (Tango API 5.7.0). `BudgetAccount` gains `account_category` (`"budgetary"` or `"credit_financing"` today, typed as an open string) and `source_anomalies`, a list that is `[]` when the row is clean. Each entry is a new `BudgetSourceAnomaly` (with `BudgetSourceAnomalySource` and `BudgetSourceAnomalyRow` for its upstream rows), and every property on it is optional. `action` is `"capped"` when a served value was clamped to its bound and `"flagged"` when it is served as reported; `code` is an open string. `ListBudgetAccountsOptions` types the new `account_category` and `account_category__in` filters. There is no anomaly filter. The default ordering now puts accounts with a null `enacted_ba` last, which is documented on the options interface and in `docs/API_REFERENCE.md`. - **Budget account `data_through_period`** (Tango API 5.8.0). `BudgetAccount` gains `data_through_period`, the File A fiscal period (1–12) an account-year's figures run through, so the latest fiscal year is partial until it reaches 12; it is null when the row has no File A data. `ListBudgetAccountsOptions` types the `data_through_period`, `data_through_period__gte`, `data_through_period__lte` and `data_through_period__isnull` filters, sent verbatim under their dunder names. - **Shapes accept the fields the API added through 5.9.0.** The `organization(...)` expand on budget accounts, exclusions, SBIR topics and SBIR solicitations (with `organization_id` on the first two); `account_category`, `data_through_period` and `source_anomalies` on budget accounts; and `holder_count` and `order_winner_count` on vehicles. The SDK rejected these client-side before. Default shapes are unchanged. - **`matched_by` on agency-filter diagnostics** (Tango API 5.9.0; parity with tango-python). Each entry of `PaginatedResponse.meta.resolved_filters[]` that resolved now says how its token matched: `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match, worth checking against the resolved name). An entry that did not resolve has no `matched_by`. `meta` is passed through as the API sends it, so no code change was needed to receive the field; it is now documented on the interface and in `docs/API_REFERENCE.md` and pinned by a test. `agencyWarnings`, `unresolvedAgencyTokens` and `resolvedAgencies` are unchanged. - **GSA eBuy requests** (Tango API 5.1.0). Four methods: `listEbuyRequests(options)` over `/api/ebuy/requests/`, `getEbuyRequest(rfqId, options)`, `getEbuyAttachmentUrl(rfqId, docSeqNum)` and `getEbuyAccess()`. Every filter the API accepts is a typed option on `ListEbuyRequestsOptions` (`search`, `rfq_id`, `reference_number`, `request_type`, `status`, `sin`, `schedule`, `buyer_agency`, `agency`, `contract_number`, the `issue_date_*` and `close_date_*` bounds, `ordering`; `agency` needs Tango API 5.3.0), with new `EbuyRequestRecord`, `EbuyAttachmentRecord` and `EbuyAccess` types and registered `EbuyRequest` / `EbuyAttachment` shape schemas. Results are scoped to the GSA schedule contracts linked to the caller's account, and an account with none gets an empty list rather than an error; `getEbuyAccess()` reports `enabled`, a `reason` (`tier_required` or `no_contract_grant`) and the caller's own `contracts`. `status` is frozen at the last-seen state, so `Open` means "open the last time it was seen" β€” `last_seen` is the staleness signal. `getEbuyAttachmentUrl()` returns the short-lived presigned URL the download endpoint redirects to, without following it. An attachment that is an external link throws the new `TangoEbuyAttachmentLinkError`, a `TangoValidationError` whose `url` is the link target. The HTTP client gained `getRedirectLocation()` to support it. `attachments(extracted_text)` returns the text extracted from an attachment's document (Tango API 5.9.1). The field joins `EbuyAttachmentRecord` and the `EbuyAttachment` shape schema. It must be named: the default detail shape and `attachments(*)` do not carry it. The key is absent rather than null for a link, an empty scan, or a document not yet extracted. - **Vehicle company counts** (Tango API 5.8.0). `Vehicle` gains `holder_count` (distinct companies holding one of the vehicle's IDVs) and `order_winner_count` (distinct companies that have won a task order under it), and both join the `VEHICLES_MINIMAL` and `VEHICLES_COMPREHENSIVE` defaults next to `awardee_count`, so `listVehicles()` and `getVehicle()` return them without a custom `shape`. Neither is orderable or filterable. - **Boards-of-contract-appeals decisions** (Tango API 4.26.0). `listContractAppeals(options)` and `getContractAppeal(uuid, options)` over `/api/contract_appeals/`, with every filter the API accepts declared as a typed option on `ListContractAppealsOptions` (`search`, `board`, `docket`, `appellant`, `judge`, `decision_type`, the `decision_date_after` / `_before` pair, `listed`, `document_id`, `ordering`), the new `ContractAppealRecord` return type, and a registered `ContractAppeal` shape schema so the typed shape API resolves the resource's fields. These are Contract Disputes Act decisions from the CBCA (civilian) and the ASBCA (defense) β€” a dispute under an existing contract, not a challenge to an award. Bid protests remain the separate `listProtests()` resource, and the two do not overlap. Two properties are documented on the record type and in `docs/API_REFERENCE.md`. An unshaped list returns only a **core subset** of the decision, so every property on `ContractAppealRecord` is optional and anything past the subset has to be named in a `shape`. And `decision_text` is **Enterprise-only, with the key absent rather than null** below that tier β€” a caller checks for presence, not for a nullish value. - **`attachments(extracted_text)` β€” SLED document bodies on the Small plan and above** (Tango API 4.25.1; parity with tango-python). The leaf joins `SledAttachmentPayload` and the explicit shape schema, and the contract was re-vendored so it validates instead of being rejected client-side. Three properties are documented on the interface and in `docs/API_REFERENCE.md`: the leaf must be **named** (neither `ShapeConfig` default includes it, and `attachments(*)` does not carry it, because the API only resolves the body for a caller who asked); the **key is absent rather than null** when the text is not being served; and a **contested document never returns text at any plan**. Searching document text stays ungated on every plan and returns no fragment of it. - **State, local and education (SLED) procurement support** (Tango API 4.25.0; parity with tango-python). Six methods over the new `/api/sled/` namespace: `listSledOpportunities`/`getSledOpportunity`, `listSledOpportunityRevisions`, `getSledCoverage`, `listSledForecasts`/`getSledForecast`, plus `iterateSledOpportunities` / `iterateSledForecasts` and their `IterableListMethod` entries. New model interfaces `SledOpportunity`, `SledOpportunityRevision`, `SledForecast` and the six nested payload types; explicit shape schemas for all of them; five `ShapeConfig` defaults. Every one of the API's 27 solicitation filters and 13 forecast filters is a typed option. Four behaviors are documented on the options interfaces because each misleads a caller who assumes federal semantics. **Passing neither `status` nor `active` returns open solicitations only** β€” that default is the API's, and the SDK deliberately does not synthesize a `status` param, since doing so would make `active: false` unreachable (pinned by a test). **`status` is Tango-derived and refreshed every fifteen minutes**; the portal's own word is served as `source_status`, is frozen at last capture, and is not a liveness filter. **Category scheme tagging is mid-migration**, so `naics` matches only the small tagged share and `category_code` is the escape hatch. And **`meta.attachment_count` can be lower than `attachments.length`**, because an auto-generated portal cover sheet is listed and flagged `is_generated_summary` but excluded from the count. `SLED_REVISIONS_MINIMAL` omits `changes` on purpose: the per-field before/after needs a Small plan, so naming it by default would 403 a Free caller. - **Fourteen nested sub-resource routes now mapped in the conformance gate.** `agencies_contracts_awarding`, `agencies_contracts_funding`, `contracts_subawards`, `entities_contracts`, `entities_idvs`, `entities_lcats`, `entities_otas`, `entities_otidvs`, `entities_subawards`, `idvs_awards`, `idvs_idvs`, `idvs_lcats`, `otidvs_awards` and `vehicles_orders` all have SDK methods and are published by the newer contract for the first time; unmapped, each was a hard conformance error. Mapping them turns those into the honest finding, which is that most of their options interfaces accept filters through an index signature rather than declaring them. ### Changed - Re-vendored `contracts/filter_shape_contract.json` for Tango API 5.11.0 and regenerated the overlay. - Dev-dependency security update via `npm audit fix`: js-yaml, brace-expansion and source-map-js move to their patched releases. The published package is unaffected; its only runtime dependency remains `commander`. - Documented that `recipient_uei` on `listContracts()` (and `uei` on `listIdvs()`, `listOtas()` and `listOtidvs()`) accepts several UEIs joined by `|`, up to 500 (Tango API 5.11.0); the SDK already passed the value through unchanged. - Re-vendored the contract for Tango API 5.9.0 (51 resources) and regenerated the overlay: 385 fields across 28 containers, 76 nested schemas. `contracts/observed_shape_types.json` is re-vendored from tango-python as well, so the new fields carry the types the API returns (`awards` is a list, `awarded` a boolean, `data_through_period` an integer) instead of types guessed from their names. - Re-vendored `contracts/filter_shape_contract.json` (schema_version 2, 48 resources) and regenerated `src/shapes/generatedOverlay.ts` from it β€” 359 fields across 25 containers, 73 nested schemas. - Re-vendored the contract for Tango API 5.1.0 and regenerated the overlay, which now merges a model's expand when two resources embed it instead of letting the narrower copy win. - Wrapping eBuy maps `ebuy/requests` in the conformance gate and removes it from both coverage baselines. - Baselined 14 reverse-shape-coverage gaps in `contracts/shape_coverage_baseline.json`, matching tango-python. All 14 are the nested sub-resource routes above, which reuse the parent resource's model rather than carrying one of their own; none is SLED, and none is a regression β€” they became visible only with the re-vendored contract. ### Deprecated - `Vehicle.awardee_count` is deprecated in favor of `order_winner_count`, which carries the same value. The API keeps serving it as an alias until its next major version. ### Fixed - **API errors now carry the server's reason** (parity with tango-python). A 403 or other non-2xx response the SDK had no dedicated error class for threw `TangoAPIError("API request failed with status 403")`, so a caller refused for a G2X-only shape field or a plan-gated filter couldn't tell why without digging into `responseData`. The message now ends with the API's own explanation (`API request failed with status 403: G2X shape fields are not allowed for your account.`), and the parsed body stays on `responseData`. Non-JSON bodies, such as a proxy's 502 page, keep the old message. - **`attachments(name,doc_role,doc_role_alt)` no longer throws `ShapeValidationError`** on `getOpportunity`, `listOpportunities`, `getNotice` and `listNotices`; the API serves both fields on the Pro plan and above when they are named. New `OpportunityAttachment` and `AttachmentDocRole` types cover the six roles and are used on `Opportunity` and `Notice`. - **SLED solicitations accept `delisted_at` and `meta(jurisdiction_declared)`**, which were rejected client-side. `SledOpportunity` and `SledMetaPayload` carry the new fields, and `status_reason` now documents `delisted`. - **`ProtestRecord` types `agency` and `protester` as the strings the API returns**, and gains `title`, `docket_url`, `decision_url`, `organization`, `dockets` and `decisions`. The never-served `docket` property is deprecated in favor of `dockets`. - **`getProtest` takes the case's `case_id` UUID**, which is all the route accepts; a case number returns 404. The parameter is renamed `caseId` and the docs say how to look a case up by number, and `listProtests` is documented as covering GAO, COFC and SBA OHA. ### Documentation - `docs/API_REFERENCE.md` covers `obligations_by_fiscal_year`, `commercial_item_acquisition_procedures`, pipe-joined UEIs, `attachments(extraction_status)` and `countType`. `docs/WEBHOOKS.md` notes that `alerts.federal_register.match` and `alerts.ebuy_request.match` are alertable, with `query_type: "federal_register"` and `"ebuy_request"`. - New **Federal Register** section in `docs/API_REFERENCE.md` with both methods and the full filter table, and both new constants in the `docs/SHAPES.md` preset table. `README.md`'s method list gained both methods. - New **GSA eBuy** section in `docs/API_REFERENCE.md` covering all four methods, the full filter table, and the data caveats (the frozen `status`, the empty-list-not-error scoping, the short-lived attachment URL, the named-only `attachments(extracted_text)`). `README.md`'s method and error lists gained the new methods and error. - New **Contract Appeals** section in `docs/API_REFERENCE.md` covering both methods, the full filter table, and the two properties that catch people out (the core-subset default and the tier-gated, absent-rather-than-null `decision_text`). `README.md`'s method list gained both methods. - New **State & Local (SLED) β€” Beta** section in `docs/API_REFERENCE.md` covering all six methods, both defaults that surprise people, and the new `ShapeConfig` constants. - `docs/WEBHOOKS.md` troubleshooting gained the date-lapse rule and its one exception. An exclusion or a DIBBS solicitation reaching its date fires nothing, because open/closed is derived at query time β€” but `alerts.sled_opportunity.match` **does** fire on a closing, since SLED liveness is a stored column a fifteen-minute sweep writes. ## [1.3.0] - 2026-08-14 ### Changed - **Node.js 20 is now the minimum supported version** (`engines.node >= 20`); the CI matrix moves from 18/20/22 to 20/22/24. Node 18 has been end-of-life since April 2025, and the security-patched test toolchain below requires 20+. Nothing in the published code changed β€” existing installs on Node 18 keep working, but they are no longer tested or supported. - Dev-dependency security upgrade clearing all six open Dependabot alerts (vitest 2.1.9 β†’ 4.x, @vitest/coverage-v8 to match, tsx to the esbuild-0.28 line β€” the published package is unaffected, its only runtime dependency remains `commander`). One test-only fix for vitest 4's stricter mocks: constructable mocks now use regular-function implementations. ## [1.2.0] - 2026-08-14 ### Added - **DIBBS, exclusions, and SBIR/STTR endpoint support** (parity with tango-python v1.3.0). Six endpoint families had no SDK support at all β€” no models, no methods. Added `listDibbsRfqs`/`getDibbsRfq`, `listDibbsRfps`/`getDibbsRfp`, `listDibbsAwards`/`getDibbsAward`, `listExclusions`/`getExclusion`, `listSbirTopics`/`getSbirTopic`, and `listSbirSolicitations`/`getSbirSolicitation`, with every filter param in the API contract exposed as a typed option, explicit shape schemas (including the nested organization/awardee/topic/document expands), `ShapeConfig` defaults, and async iterators (`iterateDibbsRfqs`, `iterateDibbsRfps`, `iterateDibbsAwards`, `iterateExclusions`, `iterateSbirTopics`, `iterateSbirSolicitations`, plus the matching `IterableListMethod` entries for the generic `iterate()`). New model interfaces: `DibbsRfq`, `DibbsRfp`, `DibbsAward`, `Exclusion`, `SbirTopic`, `SbirSolicitation`. Two API behaviors are worth knowing. `is_open` (DIBBS) and `is_currently_excluded` (exclusions) are derived at query time, so filter with the `open` / `active` options rather than shaping on those fields. And DIBBS `total_contract_price` is the _order_ total repeated on every line item β€” never sum it across rows; deduplicate on award + delivery-order number first. - **Full typed filter surface on `listBudgetAccounts`** (parity with tango-python and the API contract). `ListBudgetAccountsOptions` now declares every `budget/accounts` filter param β€” the exact / `__gte` / `__lte` triplet for all 26 numeric lifecycle, ratio, and trend fields (`requested_ba`, `enacted_ba`, `apportioned`, `obligated_total`, `outlayed_total`, `unobligated_balance`, the contract/assistance breakdowns, the `*_pct` / `*_capped` ratios, YoY + 5-year-CAGR trends, and `actual_vs_requested_contract`), plus the `__in` / `__icontains` variants of the categorical filters (`federal_account_symbol`, `fiscal_year`, `agency_code`, `bureau_name`, `bea_category`, `subfunction_code`, `account_title__icontains`). - `getGsaElibraryContract(uuid, options)` for `/api/gsa_elibrary_contracts/{uuid}/` (parity with tango-python), with the standard `shape` / `flat` / `flatLists` / `joiner` options and the `GSA_ELIBRARY_CONTRACTS_MINIMAL` default shape. - Typed filter options that previously worked only through the index-signature escape hatch: `key` on `listContracts` / `listIdvs` / `listOtas` / `listOtidvs`, `cage` on `listEntities`, `id` on `listForecasts`, `opportunity_id` on `listOpportunities`, `previous_uii` on `listItDashboard`, `naics_code` on `listProtests` (sent verbatim, not remapped to `naics`), and `has_awards` on `listPsc`. The filter-shape conformance gate now reports zero index-signature warnings. - **Generated shape-coverage overlay** (parity with tango-python v1.4.0): `src/shapes/generatedOverlay.ts`, machine-generated by the new `scripts/generate-shape-overlay.ts` from the vendored contract plus `contracts/observed_shape_types.json` (live-API type observations vendored from tango-python). `SchemaRegistry` merges the overlay over the curated explicit schemas, so the typed shape API now accepts every field and expand the API returns β€” including entity `relationships(type, source)`, previously-unmapped models (`Naics`, `PSC`, `MasSin`, `BudgetAccount`, `AssistanceListing`, `BusinessType`), and all the code/description expands that were flattened to scalars. The reverse shape-coverage gate now reports **zero** gaps and `contracts/shape_coverage_baseline.json` is empty (416 β†’ 0). - **Agency-filter diagnostics on `PaginatedResponse`** (parity with tango-python v1.5.0). Every list method now surfaces the API's `meta` payload, plus three parsed views: `agencyWarnings` (human-readable notes about dropped or loosely-matched agency tokens), `unresolvedAgencyTokens` (tokens that matched no organization, keyed by filter name), and `resolvedAgencies` (the organizations each token actually resolved to β€” the only way to catch a token fuzzy-matching an agency you did not intend). All three are total: absent or malformed `meta` yields empty values, never a throw. On the `PaginatedResponse` type, `meta` and the three parsed views are declared as optional properties β€” responses built by the client always populate them, but existing code that constructs the type without them keeps compiling. - **Structured shape errors on `TangoValidationError`** (parity with tango-python's `.issues` / `.available_fields`): new `issues` and `availableFields` getters expose the API's structured 400 payload β€” entries like `{"path": "tradeoff_process", "reason": "unknown_field"}` and the endpoint's valid field set β€” instead of leaving callers to parse `responseData` by hand. - Vendored the canonical API filter/shape contract at `contracts/filter_shape_contract.json` (API 4.22.0), so conformance checking is fully offline β€” no token, no sibling checkout. - New reverse shape-coverage gate `scripts/check-shape-coverage.ts` (npm script `check-shape-coverage`): walks every resource's shape tree in the vendored contract against the SDK's explicit schema registry and fails on any field or expand the SDK does not capture, unless recorded in `contracts/shape_coverage_baseline.json` as tracked backlog. - Accepted-gaps baselines: `contracts/conformance_baseline.json` (missing filters + unimplemented resources) and `contracts/shape_coverage_baseline.json` (known shape-coverage gaps). Baselined gaps report as warnings; anything new is an error. - **Recorded integration test layer** (parity with tango-python's VCR-cassette suite): a record/replay harness (`tests/integration/harness.ts`) around the SDK's injectable `fetchImpl`, with JSON cassettes in `tests/cassettes/` recorded against the live API. Default runs replay offline β€” a missing cassette is a hard failure so drift is loud, while an absent cassettes directory (a fork without the corpus) skips the suite with a warning. `TANGO_REFRESH_CASSETTES=true` re-records serially against the live API; `TANGO_USE_LIVE_API=true` bypasses cassettes. Cassettes never store request headers, keep only an allowlisted response-header subset, and the recorder throws rather than serialize API-key material anywhere in an interaction (asserted by unit tests in `tests/unit/integration-harness.test.ts`). - Per-resource integration tests (`tests/integration/*.test.ts`, 44 tests / 44 cassettes) covering contracts (including cursor pagination and shaping), entities, IDVs, vehicles, opportunities, notices, grants, forecasts, agencies + organizations, protests, budget accounts (fiscal-year range round-trip), DIBBS, exclusions, SBIR, NAICS/PSC reference data, subawards, and edge cases (404, invalid ordering, empty result page). - **Env-gated production smoke suite** (`tests/production/smoke.test.ts`, the node port of tango-python's `tests/production/`): runs only with `TANGO_LIVE_TESTS=true` plus `TANGO_API_KEY`, asserting light live-API invariants (pagination shape, shaping, rate-limit header parsing). Excluded from default runs and CI by `vitest.config.ts`. ### Changed - Both conformance baselines shrank with the new resources: `dibbs/*`, `exclusions`, and `sbir/*` left `unimplemented_resources` in `contracts/conformance_baseline.json`, and their `unmapped_resource` entries left `contracts/shape_coverage_baseline.json` (422 β†’ 416 known gaps, then 416 β†’ 0 with the generated overlay above). - `scripts/check-filter-shape-conformance.ts` now defaults to the vendored contract instead of a checked-out tango API repo (`TANGO_CONTRACT_PATH` or `--manifest` still point it at one), covers every resource in the 4.22.0 contract in its resource map, and treats an unimplemented resource as an error unless baselined. - Removed the dead legacy `.eslintrc.cjs` β€” the flat `eslint.config.js` has been the operative ESLint config since the flat-config migration, and the leftover file only invited divergent edits. ### Fixed - The six new list methods (`listDibbsRfqs`, `listDibbsRfps`, `listDibbsAwards`, `listExclusions`, `listSbirTopics`, `listSbirSolicitations`) leaked a caller-supplied `joiner` to the server as a bare query param and ignored it when unflattening `flat: true` responses (always unflattening on the default `.`). `joiner` is now threaded the same way as `listIdvs`: sent only alongside `flat=true`, and used as the unflatten separator. - `listBudgetAccounts`: the `fiscal_year_gte`, `fiscal_year_lte`, and `account_title` options were sent verbatim, which the API silently ignores. They are kept as legacy aliases and now remapped to the forms the API understands (`fiscal_year__gte`, `fiscal_year__lte`, `account_title__icontains`); an explicitly passed dunder param wins over its alias. - Docs: removed the stale `getIdvSummary` / `listIdvSummaryAwards` sections from `README.md` and `docs/API_REFERENCE.md` β€” those methods were removed from the SDK in 1.1.0. Documented the full new surface (DIBBS/exclusions/SBIR, budget accounts and their filter surface, `getGsaElibraryContract`, the newly typed filters, `PaginatedResponse` meta diagnostics, structured `TangoValidationError` details), completed the `ShapeConfig` preset table in `docs/SHAPES.md`, and rewrote the maintainer half of `docs/DEVELOPERS.md` around the conformance gates and the cassette record/replay workflow (the old text still claimed the SDK had no cassette mechanism). ### CI - `package-lock.json` is now committed, and the CI + publish workflows install with `npm ci --ignore-scripts` instead of `npm install` β€” installs are reproducible from the lockfile instead of re-resolving dependency ranges on every run. - The test job's Node 20 leg runs the suite once with `--coverage` (instead of a second full pass), the default `npx vitest run` now includes the integration suite replayed offline from the committed cassettes, and both setup-node steps cache the npm store off the committed lockfile. No coverage fail-under gate, matching tango-python. - The `conformance` job is now a hard gate that runs both conformance directions offline against the vendored contract on every PR β€” it no longer needs `TANGO_API_REPO_ACCESS_TOKEN` and no longer skips silently without it. When the token is configured, both checks additionally run as hard gates against the fresh contract at makegov/tango HEAD, with a re-vendor warning when the vendored copy has drifted. - The `conformance` job also regenerates `src/shapes/generatedOverlay.ts` and fails on any diff, so a contract or curated-schema change that alters generator output can't land without a regenerated overlay. `scripts/generate-shape-overlay.ts` honors the same `TANGO_CONTRACT_PATH` / `--contract` override as the two check scripts. ## [1.1.0] - 2026-05-29 ### Changed (breaking) - Removed `getIdvSummary` and `listIdvSummaryAwards`. These called `/api/idvs/{id}/summary/` and `/api/idvs/{id}/summary/awards/`, which have never existed in the Tango API (no OpenAPI backing), so no consumer could have been using them successfully. Use `getIdv` + `listIdvAwards` instead. ### Fixed - `Contract` interface: removed dead fields (`id`, `award_id`, `recipient_name`, `award_amount`, `awarding_agency`, `funding_agency`) and added the real API fields from `ContractListSerializer` (`key`, `piid`, `obligated`, `total_contract_value`, `base_and_exercised_options_value`, `awarding_office`, `funding_office`, `naics_code`, `psc_code`, `set_aside`, `solicitation_identifier`, `parent_award`, `legislative_mandates`, `subawards_summary`, `place_of_performance`). All fields optional (the endpoint is shape-on-demand). The deprecated fields remain declared (marked `@deprecated`) for one minor cycle and will be removed in `2.0.0`. New exported types: `OrganizationOfficePayload`, `PlaceOfPerformance`, `SubawardsSummary`, `LegislativeMandates`, `ParentAwardReference`, `EntityBasic`. - `listContracts`: no longer sends `page=1` to the cursor-only `/api/contracts/` endpoint. When no cursor is supplied, neither `page` nor `cursor` is sent and the API returns the first page by default. The stale code comment claiming page-based pagination support has been corrected. - Shape validation: registered the `ContractOrIDVCompetition` nested schema (alias of `Competition`) so nested selections like `competition(extent_competed,number_of_offers_received)` on contract / IDV shapes validate instead of raising a shape-validation error. ### Added - Budget accounts surface (tango v4.6.8): `listBudgetAccounts`, `getBudgetAccount`, `getBudgetAccountQuarters`, `getBudgetAccountRecipients`. New exported `BudgetAccount` interface and `ListBudgetAccountsOptions`. - Singleton detail GETs: `getContract`, `getContractSubawards`, `getContractTransactions`, `getForecast`, `getGrant`, `getNotice`, `getOpportunity`, `getSubaward`. - `getEntityBudgetFlows(uei)` for `/api/entities/{uei}/budget-flows/`. - `listVehicleOrders(uuid, options)` for `/api/vehicles/{uuid}/orders/` (parity with Python). - `grantId` filter on `listGrants` (camelCase alias mapped to the `grant_id` API param; `grant_id` also accepted directly). ### CI - Added `ci.yml` PR + push-to-main gate (lint, typecheck, build, test on Node 18/20/22). The filter/shape conformance check is a separate job that skips cleanly until a `TANGO_API_REPO_ACCESS_TOKEN` secret for the private manifest repo is configured, at which point it becomes a hard gate. - Gave the webhooks real-HTTP-server round-trip tests an explicit 20s timeout (the default 5s was tight on the slower Node 18 CI runtime). ## [1.0.0] - 2026-05-13 First stable release. `tango-node` is now at **full feature parity** with both the Tango API and `tango-python` for the surface that remains after the subject-based webhook removal (see "Removed" below). Every read method and every endpoint/alert/signing helper available on `tango_python.TangoClient` has an idiomatic camelCase counterpart on `TangoClient`, the SDK's docs are auto-published to `docs.makegov.com/sdks/node/` via the composer pipeline (makegov/docs#15 / makegov/docs#16), and from `1.x` on we'll only ship breaking changes on a major bump. ### Changed (breaking) - **`createWebhookEndpoint({ name, ... })`** β€” `name` is now required. Previously the SDK silently fell back to the callback URL's host when `name` was omitted, which masked the server's `unique(user, name)` constraint until the second duplicate endpoint. Raising client-side gives a clearer error and matches `tango-python` 1.0.0's behavior. - **`createWebhookAlert({ filters, ... })`** β€” `filters` is now validated as a non-empty plain object. Previously `{}` and arrays passed the check; the error message claimed "non-empty object" but didn't enforce it. Matches the server-side validation. ### Fixed - `tests/unit/client.iterate.test.ts` β€” corrected the comment above the first `page` assertion; previous text claimed the first call should NOT carry a page, but the assertion (correctly) expects `page=1` since `listContracts` defaults to it. - `docs/DEVELOPERS.md` β€” `listContracts({ offset: 25 })` example replaced with `{ page: 2 }` and "manual offset tracking" β†’ "manual page/cursor tracking" (the method has never accepted `offset`). - `CHANGELOG.md` β€” corrected "4 new unit test files" to "5"; the parenthesized list always contained 5 paths. - Lint cleanup ahead of the npm publish β€” 44 redundant `as AnyRecord` / `as ` type-assertion casts dropped across `src/` (`@typescript-eslint/no-unnecessary-type-assertion` fires under the newer plugin minor that CI resolves). `src/webhooks/receiver.ts`: dropped the unused `AddressInfo` import, simplified `Delivery.bodyJson: unknown | null` β†’ `unknown` (the latter already includes `null`), and restructured `WebhookReceiver.run()` to avoid `const receiver = this` (replaced with arrow-function closures over `getUrl`/`getDeliveries`/`stop`). No behavior change β€” tests still pass 220/220. - `eslint.config.js` β€” disabled the core `no-undef` rule for TS files. TypeScript itself does undefined-symbol checking with knowledge of TS-only types (`AsyncDisposable`, `Disposable`, etc.); the core rule double-fires and false-flags those. Matches the typescript-eslint upstream guidance. ### Internal - Pinned `devDependencies` to exact versions (dropped `^` from `package.json`). The previous unpinned ranges + gitignored `package-lock.json` meant CI re-resolved deps on every run and could pick up minor versions with stricter behavior that local installs hadn't seen yet β€” that's how the lint mismatch above slipped past local checks. ### Docs - **README** updated for the docs-review sweep: - Added `TangoTimeoutError` to the documented error class list (it has been exported from `src/errors.ts` since v0.4 but the README omitted it). - Replaced the "_(Coming Soon!)_" marker on the docs link with the live `https://docs.makegov.com/sdks/node/` URL. - Rewrote the "Comprehensive API Coverage" feature bullet β€” the old enumeration listed fewer than half of the actually-implemented domains. New bullet points at the canonical "API Methods" section for the full surface. - New `docs/CLIENT.md` β€” `TangoClient` constructor reference, environment variables, full retry/backoff semantics (including `Retry-After` handling), error-handling patterns, `fetchImpl` injection, and staging/local targeting. Ported from `docs.makegov.com/sdks/node/client.md` ahead of the docs-site auto-pull cutover (makegov/docs#15 / makegov/docs#16). - `docs/API_REFERENCE.md` enriched with notes from the docs-site `methods.md` that hadn't been folded in yet: `listContracts` page/cursor mutual exclusion, `getIdvSummary` / `listIdvSummaryAwards` deprecation (server returns 404), `listIdvLcats` clarification, `listOrganizations` `level` semantics, `createWebhookEndpoint` snake_case canonical vs camelCase legacy aliases (`name` is required either way per the 1.0.0 change above), `testWebhookEndpoint` post-#2252 cleanup (`{ endpoint: }` is canonical), and `createWebhookAlert` field-rename notes (`name` vs `subscription_name`, `filters` vs `filter_definition`, singular `query_type`, update-writable field list). ### CI - New `.github/workflows/docs-dispatch.yml` β€” fires on push to `main` when `docs/**`, `README.md`, or `CHANGELOG.md` changes and dispatches `external_updated` at `makegov/docs` so the public docs site rebuilds with the latest SDK content. Required for the makegov/docs#15 auto-pull pipeline. ### Parity closure β€” all previously-tracked gaps addressed Every gap surfaced in the May 2026 parity audit is now closed: #### Typed filter `Options` interfaces - `listForecasts`, `listOpportunities`, `listNotices`, `listGrants` β€” previously `ListOptionsBase & Record` with zero typed filters; now ship full `Options` interfaces (`ListForecastsOptions`, `ListOpportunitiesOptions`, `ListNoticesOptions`, `ListGrantsOptions`) enumerating every filter kwarg from the Python signatures. `ListNoticesOptions` deliberately omits `ordering` (server rejects it). - `ListContractsOptions` expanded to enumerate all 27+ Python kwargs (`award_date*`, `awarding_agency`, `funding_agency`, `obligated_gte/lte`, `pop_*`, `expiring_*`, `keyword`/`recipient_name`/`recipient_uei`/`set_aside_type`/`naics_code`/`psc_code` aliases, `sort`+`order`β†’`ordering`, etc.). - `ListEntitiesOptions` expanded with the 12 Python kwargs (`cage_code`, `naics`, `name`, `psc`, `purpose_of_registration_code`, `socioeconomic`, `state`, `total_awards_obligated_gte/lte`, `uei`, `zip_code`). - `ListVehiclesOptions` expanded with all 21 filter kwargs (`vehicle_type`, `type_of_idc`, `contract_type`, `who_can_use`, `total_obligated_min/max`, etc.). - `ListIdvsOptions` expanded with the full IDV filter surface. - `ListOtasOptions` / `ListOtidvsOptions` expanded with the missing `_gte`/`_lte` ranges (`award_date_gte/lte`, `fiscal_year_gte/lte`, `expiring_gte/lte`, `pop_start_date_gte/lte`, `pop_end_date_gte/lte`). - `ListAgenciesOptions` added (was inline `{ page?, limit? }`). All `Options` interfaces keep a `[key: string]: unknown` index signature for forward-compatibility with new server-side filters that haven't been ported yet β€” typed fields give autocomplete and typo-protection on known filters; unknown fields still pass through. #### `ShapeConfig` preset parity Added: `PROTESTS_MINIMAL`, `OTAS_MINIMAL`, `OTIDVS_MINIMAL`, `SUBAWARDS_MINIMAL`, `GSA_ELIBRARY_CONTRACTS_MINIMAL`, `ORGANIZATIONS_MINIMAL`, `VEHICLE_ORDERS_MINIMAL`, `ITDASHBOARD_INVESTMENTS_MINIMAL`, `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE`. Updated to match Python field lists: `ENTITIES_COMPREHENSIVE` (now uses `federal_obligations(*)` expansion), `VEHICLES_MINIMAL` (extended to mirror Python's larger field list), `VEHICLES_COMPREHENSIVE` (dropped `competition_details(*)` per SDK v0.6.0; added `program_acronym`, `is_synthetic_solicitation`, `metrics(*)`, organization expansion). #### Explicit schemas Added 11 schemas + registry entries: `ORGANIZATION_OFFICE_SCHEMA`, `VEHICLE_METRICS_SCHEMA`, `ORGANIZATION_SCHEMA`, `OTA_SCHEMA`, `OTIDV_SCHEMA`, `SUBAWARD_SCHEMA`, `PROTEST_DOCKET_SCHEMA`, `PROTEST_SCHEMA`, `GSA_ELIBRARY_IDV_REF_SCHEMA`, `GSA_ELIBRARY_CONTRACT_SCHEMA`, `ITDASHBOARD_INVESTMENT_SCHEMA`. Wired into the `EXPLICIT_SCHEMAS` registry under canonical model names. Also extended `VEHICLE_SCHEMA` with the fields the new `VEHICLES_*` presets reference: `is_synthetic_solicitation`, `program_acronym`, `organization` (expandable to `OrganizationOffice`), `metrics` (expandable to `VehicleMetrics`), `idv_count`, `total_obligated`, `latest_award_date`, `opportunity_id`, `description`. #### Typed return models - `client.resolve(input)` β†’ `Promise` with typed `ResolveCandidate[]` (was `Promise<{ candidates: AnyRecord[]; count: number }>`). - `client.validate(input)` β†’ `Promise` (was `Promise`). - `client.getAgency(code)` β†’ `Promise` (was `Promise`). - `client.getProtest(caseNumber)` β†’ `Promise` with typed `docket`, `resolved_*`, etc. All new types exported from package root. #### Observability β€” `rateLimitInfo` + `lastResponseHeaders` Two new instance properties on `TangoClient` mirroring Python's `rate_limit_info` / `last_response_headers`: ```typescript await client.listContracts({ limit: 5 }); console.log(client.rateLimitInfo); // { remaining: 98, limit: 100, resetIn: 60, retryAfter: null, limitType: "per_minute" } console.log(client.lastResponseHeaders?.["x-request-id"]); ``` Both `null` until the first request completes; populated after every successful request. `HttpClient` parses `X-RateLimit-{Remaining,Limit,Reset,Type}` + `Retry-After` headers into a `RateLimitInfo` snapshot. #### `listContracts` cursor pagination (non-breaking) `ListContractsOptions` now accepts `cursor` alongside `page`. When `cursor` is supplied, the request omits `page` and uses keyset pagination (Python parity); otherwise falls back to page-based. `PaginatedResponse` gained a `cursor` field auto-extracted from `next` so callers can `client.listContracts({ cursor: resp.cursor })` for the next page without parsing the URL themselves. #### `WebhookReceiver` framework New `src/webhooks/receiver.ts`. `WebhookReceiver` dataclass-style class with `start()`, `stop()`, `url`, `deliveries`, `onDelivery` callback, optional `forwardTo` mirror, history cap, signature verification (via existing `verifySignature`). Two run patterns shipped: - `await using rx = await new WebhookReceiver(opts).run();` (modern, `Symbol.asyncDispose`). - `await WebhookReceiver.withRunning(opts, async (rx) => { ... });` (portable callback scope). Pure `node:http` + native `fetch` β€” no new dependencies. #### Webhook simulator New `src/webhooks/simulate.ts`. `sign(payload, secret)` returns a `SignedRequest` (body bytes, signature header value, content-type). `deliver({ targetUrl, payload, secret, ... })` signs and POSTs via native `fetch` with `AbortSignal.timeout()`. Includes a `stableStringify` helper that matches Python's `json.dumps(sort_keys=True, separators=(",", ":"))` byte-for-byte so signatures are reproducible across languages. #### Webhook CLI β€” `tango-node webhooks` New `bin/tango-node` (entry in `src/bin/tango-node.ts`) backed by `commander`. Subcommands: `listen`, `simulate`, `trigger`, `fetch-sample`, `list-event-types`, `endpoints {list, get, create, delete}` β€” mirroring the Python `tango webhooks` CLI. New runtime dep: `commander@^12.1.0`. #### Conformance gate New `scripts/check-filter-shape-conformance.ts` + `npm run check-conformance` script. Walks `src/client.ts` with the TypeScript compiler AST, extracts each `list*` method's `Options` interface, and validates against the canonical manifest at `tango/contracts/filter_shape_contract.json`. JSON output + exit codes match the Python conformance script. Current state: **0 errors, 0 warnings** β€” parity verified. #### Test coverage Net **+74 tests** across the new work (220 total now passing, up from 146 pre-audit): - ShapeConfig preset parity (`config.shapes.parity`) - Explicit schema parity (`shapes.schema.parity`, 12 tests) - WebhookReceiver lifecycle, signature paths, forwarding, history cap, `withRunning` + `Symbol.asyncDispose` (`webhooks/receiver`, 21 tests) - Webhook simulator stable-stringify, sign-verify round-trip, deliver against a real `http.createServer`, timeout (`webhooks/simulate`, 17 tests) - CLI subcommand wiring (`webhooks/cli`, 7 tests) - Conformance script (`scripts/conformance`, 5 tests) - Observability + cursor pagination + typed return models (`client.observability`, 11 tests) ### Internal - `tsx` added as a devDependency to run the new conformance script. - `HttpClient` constructor body unchanged; just adds two readonly fields (`lastResponseHeaders`, `rateLimitInfo`) populated on every successful response. ### Removed - **Subject-based webhook subscriptions** are gone. The Tango API is dropping the `/api/webhooks/subscriptions/` surface for subject delivery (see [makegov/tango#2267](https://github.com/makegov/tango/issues/2267)); `tango-node` mirrors that here. Removed methods: `listWebhookSubscriptions`, `getWebhookSubscription`, `createWebhookSubscription`, `updateWebhookSubscription`, `deleteWebhookSubscription`. Removed types: `WebhookSubscription`, `WebhookSubscriptionCreateInput`, `WebhookSubscriptionUpdateInput`, `WebhookSubscriptionPayload`, `WebhookSubscriptionPayloadRecord`, `WebhookSubjectTypeDefinition`, `WebhookSampleSubject`, `ListWebhookSubscriptionsOptions`. `WebhookEventTypesResponse` no longer carries `subject_types` / `subject_type_definitions`; `WebhookEventType` no longer carries `default_subject_type`; sample-payload responses no longer carry `sample_subjects` / `sample_subscription_requests`. Use `createWebhookAlert` (filter-based delivery via `/api/webhooks/alerts/`) β€” that's the only remaining subscription path. SemVer-major (`0.3.0` β†’ `0.4.0`). ### Added #### API parity β€” read methods - **Lookups**: `listNaics`, `getNaics`, `listPsc`, `getPsc`, `listMasSins`, `getMasSin`, `listAssistanceListings`, `getAssistanceListing`, `listOrganizations`, `getOrganization`, `listOffices`, `getOffice`, `listDepartments` (`@deprecated` JSDoc), `getDepartment`, `getBusinessType`. - **Awards completeness**: `listOtas`, `getOta`, `listOtidvs`, `getOtidv`, `listOtidvAwards`, `listSubawards`, `listGsaElibraryContracts`, `listLcats` (accepts `{ uei }` or `{ idvKey }`). - **Other resources**: `listProtests`, `getProtest`, `listItDashboard`, `getItDashboard`, `listMetrics` (parameterized over `ownerType` since the API exposes metrics only under owner-scoped paths). - **Utility endpoints**: `resolve(input)` (POST `/api/resolve/` β€” returns `{ candidates, count }`), `validate(input)` (POST `/api/validate/`). #### API parity β€” typed wrappers for Python's `get_*_metrics` helpers - `getEntityMetrics(uei, months, periodGrouping)` - `getNaicsMetrics(code, months, periodGrouping)` - `getPscMetrics(code, months, periodGrouping)` #### API parity β€” entity, IDV, and agency sub-resources - `listEntityContracts`, `listEntityIdvs`, `listEntityOtas`, `listEntityOtidvs`, `listEntitySubawards`, `listEntityLcats` - `listIdvLcats(key, options?)` β€” typed sibling of the generic `listLcats({ idvKey })` - `listAgencyAwardingContracts`, `listAgencyFundingContracts` #### Webhook write API - Endpoints: `createWebhookEndpoint` (now `name` is first-class; defaults to URL host if omitted), `updateWebhookEndpoint`, `deleteWebhookEndpoint`. `testWebhookEndpoint(endpointId)` is the canonical method; `testWebhookDelivery` is kept as an auto-resolving variant (omit `endpointId` to let the API pick the sole endpoint). - Alerts (filter-subscription API): `listWebhookAlerts`, `getWebhookAlert`, `createWebhookAlert`, `updateWebhookAlert`, `deleteWebhookAlert`. `WebhookAlertCreateInput` now has an optional `endpoint` field β€” required for multi-endpoint accounts, optional for single-endpoint accounts (the API auto-resolves). Server support landed in [makegov/tango#2256](https://github.com/makegov/tango/issues/2256). New typed input interfaces exported from the package root: `WebhookEndpointCreateInput`, `WebhookEndpointUpdateInput`, `WebhookAlertCreateInput`, `WebhookAlert`, plus options types for the new sub-resources. #### Webhook signature helpers (parity with `tango_python.webhooks.signing`) - `verifySignature(body, header, secret)` β€” constant-time HMAC-SHA256 verification. Accepts `"sha256="` and bare-hex forms. Returns `boolean`, never throws. - `generateSignature(body, secret)` β€” emits `"sha256="` matching the dispatcher format. - `parseSignatureHeader(header)` β€” returns `{ algorithm, signature } | null` for cleaner branching in receivers. All exported from the package root; receivers don't need to instantiate `TangoClient`. #### Async iterator pagination For convenience, list methods now have async-iterator wrappers that handle `next` / `cursor` for you: ```typescript for await (const contract of client.iterateContracts({ awarding_agency: "9700" })) { console.log(contract.piid, contract.total_contract_value); } ``` Typed iterators: `iterateContracts`, `iterateEntities`, `iterateOpportunities`, `iterateNotices`, `iterateGrants`, `iterateForecasts`, `iterateIdvs`, `iterateVehicles`. Iteration is sequential (no concurrent requests) to respect API rate limits. #### Retry with exponential backoff `HttpClient` now automatically retries failed requests: - Retries on 5xx, 408 (Request Timeout), 429 (Too Many Requests), network errors, and client-side timeouts. - Does **not** retry on other 4xx β€” those surface as the appropriate `Tango*` error immediately. - Exponential backoff: base `retryBackoffMs` (default 250ms), doubled per attempt, capped at 10s. - Honors `Retry-After` headers (delta-seconds and HTTP-date) on 429/503. #### Constructor surface - `retries` (default `3`) and `retryBackoffMs` (default `250`) options on `TangoClientOptions`. Set `retries: 0` to disable. - `timeout` accepted as a shorthand alias for `timeoutMs` (both in ms; `timeoutMs` wins if both are supplied). #### Environment variable fallback - `TANGO_BASE_URL` env var is now read when `baseUrl` is not passed to the constructor β€” parity with `TANGO_API_KEY`. #### Misc - `searchOpportunityAttachments`, `getVersion`, `listApiKeys` round out parity with the Python SDK's introspection / search surface. - Shape generator now accepts `naics(code,description)` / `psc(code,description)` as canonical expands on Contract, Opportunity, Notice, Forecast, and Vehicle (IDV already had them). Mirrors `makegov/tango#2259`. (refs `makegov/tango#2265`) ### Changed - `createWebhookEndpoint` and related write methods accept the canonical Tango API payload shape in addition to the previous camelCase wrappers β€” see the new typed input interfaces. - `testWebhookEndpoint` / `testWebhookDelivery` now send the canonical `{ endpoint }` body key instead of the deprecated `{ endpoint_id }` (server still accepts both as aliases). Tracks [makegov/tango#2252](https://github.com/makegov/tango/issues/2252). - `ListSubawardsOptions.ordering` narrowed from `string` to the literal union `"last_modified_date" | "-last_modified_date"`, matching the server-side enum (no other values are accepted; others 400). Tracks [makegov/tango#2254](https://github.com/makegov/tango/issues/2254). - Shape generator rewrites legacy `naics_code(...)` / `psc_code(...)` expand spellings to canonical `naics(...)` / `psc(...)` before validation, matching the server's `_EXPAND_ALIASES` map. Scalar `naics_code` / `psc_code` (no parens) is untouched and still returns the raw column value. (refs `makegov/tango#2265`, `makegov/tango#2259`) ### Fixed - `ShapeConfig.IDVS_COMPREHENSIVE` no longer includes `base_and_exercised_options_value`, which is not a valid IDV shape field β€” the API was returning `400 Invalid shape` on this preset. Now aligned with `tango_python.IDVS_COMPREHENSIVE`. Also reconciled `recipient.cage_code` β†’ `recipient.cage` to match the Python preset exactly. - `createWebhookAlert` now plumbs an explicit `endpoint` UUID through to the API. Multi-endpoint accounts can now create alerts directly instead of relying on the server's single-endpoint auto-resolution. Tracks [makegov/tango#2256](https://github.com/makegov/tango/issues/2256). - **`Subaward` schema matches the server's `SubawardSerializer`.** The previous `SUBAWARD_SCHEMA` (ported from the broken Python schema) declared two fields the server has never exposed (`id`, `amount`) and was missing every real field β€” including `piid`, `key`, `awarding_office` / `funding_office` / `place_of_performance` / `subaward_details` / `fsrs_details` / `highly_compensated_officers` / `usaspending_permalink`, and the denormalized `prime_awardee_*` / `recipient_*` lookup columns. Shape strings that referenced any real field (e.g. `shape: "piid"`) would fail client-side validation with `unknown_field`. `SUBAWARD_SCHEMA` is now derived directly from `awards.serializers.subawards.SubawardSerializer` and the resource's runtime `available_fields`. New nested schemas `SubawardDetails`, `FsrsDetails`, `SubawardPlaceOfPerformance`, and `HighlyCompensatedOfficer` are registered so the corresponding shape expansions validate end-to-end. ### Internal - Live smoke harnesses at `scripts/smoke-{reads,writes,extras,parity}.ts` exercise every new method against a running Tango instance. All four require `TANGO_API_KEY` in the environment (hard-fail if unset β€” no fallback). - 5 new unit test files (`tests/unit/{client.parity,client.iterate,client.baseurl,webhooks.signing,config.shapes}.test.ts`) added; total suite is now 16 files / 111 tests / 82% line coverage. - ESM build (`tsc -p tsconfig.json`) clean. ## [0.3.0] - 2026-02-09 ### Added - Vehicles endpoints: `listVehicles`, `getVehicle`, and `listVehicleAwardees` (supports shaping + flattening). (refs `makegov/tango#1327`) - IDV endpoints: `listIdvs`, `getIdv`, `listIdvAwards`, `listIdvChildIdvs`, `listIdvTransactions`, `getIdvSummary`, `listIdvSummaryAwards`. (refs `makegov/tango#1327`) - Webhooks v2 client support: event type discovery, subscription CRUD, endpoint management, test delivery, and sample payload helpers. (refs `makegov/tango#1275`) ### Changed - HTTP client now supports PATCH/PUT/DELETE for non-GET endpoints. - `joiner` is now respected when unflattening `flat=true` responses on supported endpoints. ## [0.1.0] - 2025-11-21 - Initial Node.js port of the Tango Python SDK. - Basic project scaffolding for client, models, and shapes. - ESM + TypeScript build configuration. ## [0.1.4] - 2025-11-21 - Added tests and cleaned up formatting and structure of SDK. --- # Client Configuration `TangoClient` is the entry point for every API call. This guide covers the constructor, environment variables, retry semantics, error handling, and how to plug in a custom `fetch`. For per-method signatures, see [`API_REFERENCE.md`](api-reference.md). For webhook receivers, see [`WEBHOOKS.md`](webhooks.md). For response shaping, see [`SHAPES.md`](shapes.md). ## Constructor ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY, // optional if TANGO_API_KEY is set in env baseUrl: "https://tango.makegov.com", // default timeoutMs: 30_000, // default retries: 3, // default retryBackoffMs: 250, // default }); ``` ### Options | Option | Type | Default | Description | | --- | --- | --- | --- | | `apiKey` | `string` | reads `TANGO_API_KEY` env | Tango API key. Sent as `X-API-KEY` header. | | `baseUrl` | `string` | `https://tango.makegov.com` | API base URL. Override for staging/local. | | `timeoutMs` | `number` | `30000` | Per-request timeout in milliseconds. Aborts with `TangoTimeoutError`. | | `timeout` | `number` | β€” | Ergonomic shorthand for `timeoutMs` (also in ms). If both are supplied, `timeoutMs` wins. | | `retries` | `number` | `3` | Number of retry attempts on retryable failures. Set to `0` to disable. Total attempts = `retries + 1`. | | `retryBackoffMs` | `number` | `250` | Initial backoff between retries (ms). Doubles each retry, capped at 10s. | | `fetchImpl` | `typeof fetch` | global `fetch` | Custom fetch implementation. Useful for proxies, instrumentation, or runtimes without a global fetch. | ### Environment variables | Env var | Purpose | | --- | --- | | `TANGO_API_KEY` | Default API key when `apiKey` is not passed to the constructor. | | `TANGO_BASE_URL` | Default base URL when `baseUrl` is not passed. Falls through to `https://tango.makegov.com` if neither is set. | ## Retry semantics The client retries failed requests automatically. A request is retried when: - The HTTP status is `5xx` (any server error), - The status is `408` (Request Timeout) or `429` (Too Many Requests), - Or the request fails at the network layer (DNS, connection refused, fetch network error, abort due to client-side timeout). Other `4xx` statuses (`400`, `401`, `403`, `404`, …) are **not** retried β€” they're surfaced as the appropriate `Tango*` error immediately. ### Backoff math - First retry: `retryBackoffMs` (default 250ms) - Second retry: `retryBackoffMs * 2` - Third retry: `retryBackoffMs * 4` - Each wait is capped at **10 seconds**. If the response includes a `Retry-After` header (typical on `429` and `503`), the client honors that value instead of computing its own backoff: - A delta-seconds value (`Retry-After: 5`) β†’ waits 5 seconds. - An HTTP-date value (`Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`) β†’ waits until that time. - The honored wait is still capped at 10 seconds. To disable retries entirely (e.g. for smoke tests or one-shot scripts where you'd rather see the raw failure): ```typescript const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY, retries: 0, }); ``` ## Error handling All Tango errors extend `TangoAPIError`. Import them from the package root: ```typescript import { TangoClient, TangoAPIError, TangoAuthError, TangoNotFoundError, TangoValidationError, TangoRateLimitError, TangoTimeoutError, } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); try { const entity = await client.getEntity("ABCDEF123456"); console.log(entity); } catch (err) { if (err instanceof TangoNotFoundError) { console.warn("No such entity"); } else if (err instanceof TangoValidationError) { console.error("Bad request:", err.message, err.responseData); } else if (err instanceof TangoAuthError) { console.error("Check your API key"); } else if (err instanceof TangoRateLimitError) { // The client already retried `retries` times before giving up. console.error("Rate limited; back off harder"); } else if (err instanceof TangoTimeoutError) { console.error("Request timed out; consider raising timeoutMs"); } else if (err instanceof TangoAPIError) { console.error("API error:", err.statusCode, err.message); } else { throw err; } } ``` Every `TangoAPIError` carries: - `message: string` β€” human-readable; for 400s, the SDK extracts the first `detail` / `message` / `error` / field-error from the response body when present. - `statusCode?: number` β€” HTTP status (or `408` for client-side timeouts). - `responseData?: unknown` β€” parsed JSON body of the error response (when the server returned JSON). The client also throws `TangoAPIError` when an HTTP 200 response body contains `{ "error": "..." }` β€” the Tango API occasionally signals errors in 200 payloads. ## Custom `fetch` Pass a custom `fetchImpl` to instrument requests, route through a proxy, or run in a non-Node runtime: ```typescript import { TangoClient } from "@makegov/tango-node"; const tracedFetch: typeof fetch = async (input, init) => { const start = Date.now(); const res = await fetch(input, init); console.log(`${init?.method ?? "GET"} ${input} β†’ ${res.status} (${Date.now() - start}ms)`); return res; }; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY, fetchImpl: tracedFetch, }); ``` ## Targeting staging or local Point `baseUrl` at the host you want: ```typescript const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY, baseUrl: "http://localhost:8000", }); ``` The trailing slash on `baseUrl` is optional; the client normalizes it. --- # Tango Node SDK – Dynamic Models Guide This document explains how the **Node.js dynamic shaping system** works. It is a full translation of the Python `DEVELOPERS.md` shaping guide. --- ## Overview Tango’s dynamic modeling allows you to: - Request _exactly the fields you want_ - Validate the shape string against Tango’s schemas - Generate a typed model descriptor at runtime - Materialize shaped objects using correct: - date parsing - datetime parsing - decimal handling - list vs scalar logic - nested structure --- ## Components ### ShapeParser Parses shape strings into a `ShapeSpec`. ```ts import { ShapeParser } from "@makegov/tango-node/shapes"; const parser = new ShapeParser(); const spec = parser.parse("key,piid,recipient(display_name)"); ``` ### SchemaRegistry Holds the field schemas for all models. ```ts import { SchemaRegistry } from "@makegov/tango-node/shapes"; const registry = new SchemaRegistry(); registry.getField("Contract", "award_date"); ``` ### TypeGenerator Builds a `GeneratedModel` descriptor from `(baseModel, shapeSpec)`. ```ts import { TypeGenerator } from "@makegov/tango-node/shapes"; const gen = new TypeGenerator(); const model = gen.generateModelDescriptor("Contract", spec); ``` ### ModelFactory Takes a descriptor + raw API JSON and produces typed shaped objects. The TangoClient now uses this pipeline automatically after fetching data. ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const contracts = await client.listContracts({ shape: "key,award_date,recipient(display_name)", }); // contracts.results are materialized via ModelFactory: // - date/datetime parsed to Date // - decimals normalized to string // - nested structures enforced ``` --- ## Example: Full Shaping Pipeline (manual) ```ts const parser = new ShapeParser(); const spec = parser.parse("key,award_date,recipient(display_name)"); const gen = new TypeGenerator(); const descriptor = gen.generateModelDescriptor("Contract", spec); const factory = new ModelFactory(); const shaped = factory.createOne("Contract", spec, { key: "C-1", award_date: "2024-01-15", recipient: { display_name: "Acme" }, }); ``` `shaped` becomes: ```ts { key: "C-1", award_date: Date("2024-01-15"), recipient: { display_name: "Acme" } } ``` --- ## Type Safety Node SDK enforces shape correctness at runtime and guarantees nested structures. The client materializes responses through ModelFactory, so the shape schema is applied automatically. TypeScript interfaces are not codegenerated per shape at build time; the SDK exports lightweight model interfaces in `@makegov/tango-node/models` for convenience. --- ## Caching TypeGenerator caches descriptors with FIFO eviction. ShapeParser also caches parse results. --- ## Nested Models If a field is nested in the schema (e.g. `"recipient"` β†’ `RecipientProfile`), the generator recursively builds the nested descriptor. --- --- # Tango Node.js SDK [![npm](https://img.shields.io/npm/v/@makegov/tango-node.svg)](https://www.npmjs.com/package/@makegov/tango-node) [![Node.js Version](https://img.shields.io/node/v/@makegov/tango-node.svg)](https://www.npmjs.com/package/@makegov/tango-node) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) A modern Node.js SDK for the [Tango API](https://tango.makegov.com), featuring dynamic response shaping, strong TypeScript types, and full coverage of the core Tango endpoints. > This is the Node.js/TypeScript port of the official Tango Python SDK. ## Features - **Dynamic Response Shaping** – Ask Tango for exactly the fields you want using a simple shape syntax. - **Type-Safe by Design** – Shape strings are validated against Tango schemas and mapped to generated TypeScript types. - **Full Tango API surface** – Awards (contracts, IDVs, OTAs, OTIDVs, subawards, vehicles, GSA eLibrary), opportunities + notices, forecasts, grants, protests, IT Dashboard, budget accounts, exclusions, SBIR/STTR, DIBBS, entities (with sub-resources), agencies/organizations/offices/departments, lookups (NAICS, PSC, MAS SINs, assistance listings, business types), metrics, resolve/validate, webhooks. See `## API Methods` below for the full list. - **Flexible Data Access** – Plain JavaScript objects backed by runtime validation and parsing, materialized via the dynamic model pipeline. - **Modern Node.js** – Built for Node.js 20+ with native `fetch` and ESM-first design. - **Tested Against the Real API** – Integration tests (mirroring the Python SDK) keep behavior aligned. ## Installation **Requirements:** Node.js 20 or higher. ```bash npm install @makegov/tango-node # or yarn add @makegov/tango-node # or pnpm add @makegov/tango-node ``` ## Quick Start ### Initialize the client ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY, // baseUrl: "https://tango.makegov.com", // default }); ``` ### List agencies ```ts const agencies = await client.listAgencies(); for (const agency of agencies.results) { console.log(agency.code, agency.name); } ``` ### Get a specific agency ```ts const treasury = await client.getAgency("2000"); // Treasury console.log(treasury.name, treasury.department?.name); ``` ### Search contracts with a minimal shape ```ts import { TangoClient, ShapeConfig } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const contracts = await client.listContracts({ shape: ShapeConfig.CONTRACTS_MINIMAL, keyword: "cloud services", awarding_agency: "4700", fiscal_year: 2024, limit: 10, }); // Each contract is shaped according to CONTRACTS_MINIMAL for (const c of contracts.results) { console.log(c.piid, c.award_date, c.recipient.display_name); } ``` ### Get a fully-shaped entity ```ts import { TangoClient, ShapeConfig } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const entity = await client.getEntity("ABC123DEF456", { shape: ShapeConfig.ENTITIES_COMPREHENSIVE, }); console.log(entity.uei, entity.legal_business_name, entity.primary_naics); ``` ## Authentication The Node.js SDK uses the same model as the Python one: you can either pass the API key directly or read it from `TANGO_API_KEY`. ### With API key ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: "your-api-key-here", }); ``` ### From environment variable (`TANGO_API_KEY`) ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient(); // If apiKey is omitted, the client will look for process.env.TANGO_API_KEY ``` ## Core Concepts ### Dynamic Response Shaping Response shaping is the core feature of Tango. Instead of always receiving huge objects with every field, you describe the fields you want with a compact shape string: ```ts const contracts = await client.listContracts({ shape: "key,piid,award_date,recipient(display_name),total_contract_value", keyword: "software", limit: 5, }); ``` **Shapes:** - Reduce payload size (often massively). - Keep responses focused on what your app actually uses. - Drive type safety – the SDK maps the shape to a TypeScript type. **The Node.js SDK includes:** - A **shape parser** that validates shape strings. - A **schema registry** that knows what fields exist on each resource. - A **type generator** and **model factory** that convert raw API JSON into strongly-typed objects. ### Flat vs nested responses By default, nested fields are returned as nested objects: ```ts // shape: "key,piid,recipient(display_name,uei)"; // contract.recipient.display_name; contract.recipient.uei; ``` You can request a "flat" representation that uses dotted keys and then unflattens into nested objects on the client: ```ts const contracts = await client.listContracts({ shape: ShapeConfig.CONTRACTS_MINIMAL, flat: true, }); ``` The Node.js SDK mirrors the Python client's behavior for `shape`, `flat`, and `flat_lists`. ## API Methods The Node.js client mirrors the Python SDK's high-level API. Selected highlights: **Agencies / Offices / Organizations / Departments** - `listAgencies(options)` / `getAgency(code)` - `listOffices(options)` / `getOffice(code)` - `listOrganizations(options)` / `getOrganization(identifier)` - `listDepartments(options)` / `getDepartment(code)` **Contracts / IDVs / OTAs / OTIDVs / Subawards** - `listContracts(options)` / `getContract(key, options)` / `getContractSubawards(key, options)` / `getContractTransactions(key, options)` - `listIdvs(options)` / `getIdv(key, options)` - `listIdvAwards(key, options)` / `listIdvChildIdvs({key, ...options})` / `listIdvTransactions(key, options)` - `listOtas(options)` / `getOta(key)` / `listOtidvs(options)` / `getOtidv(key)` / `listOtidvAwards(key, options)` - `listSubawards(options)` / `getSubaward(key)` **Vehicles** - `listVehicles(options)` / `getVehicle(uuid, options)` / `listVehicleAwardees(uuid, options)` / `listVehicleOrders(uuid, options)` **Entities** - `listEntities(options)` / `getEntity(ueiOrCage, options)` - `listEntityContracts(uei, options)` / `listEntityIdvs(uei, options)` / `listEntityOtas(uei, options)` - `listEntityOtidvs(uei, options)` / `listEntitySubawards(uei, options)` / `listEntityLcats(uei, options)` - `getEntityMetrics(uei, months, periodGrouping)` / `getEntityBudgetFlows(uei)` **Forecasts / Opportunities / Notices / Grants** - `listForecasts(options)` / `listOpportunities(options)` / `listNotices(options)` / `listGrants(options)` - `getForecast(id, options)` / `getOpportunity(opportunityId, options)` / `getNotice(noticeId, options)` / `getGrant(grantId, options)` - `searchOpportunityAttachments(options)` **GSA eLibrary / GSA eBuy / Protests / Contract Appeals / Federal Register / IT Dashboard / LCATs** - `listGsaElibraryContracts(options)` / `getGsaElibraryContract(uuid, options)` - `listEbuyRequests(options)` / `getEbuyRequest(rfqId, options)` / `getEbuyAttachmentUrl(rfqId, docSeqNum)` / `getEbuyAccess()` - `listProtests(options)` / `getProtest(caseId)` - `listContractAppeals(options)` / `getContractAppeal(uuid, options)` - `listFederalRegisterDocuments(options)` / `getFederalRegisterDocument(uuid, options)` - `listItDashboard(options)` / `getItDashboard(uii)` - `listLcats(options)` / `listIdvLcats(key, options)` **Budget Accounts** - `listBudgetAccounts(options)` / `getBudgetAccount(id, options)` - `getBudgetAccountQuarters(id, options)` / `getBudgetAccountRecipients(id, options)` **Exclusions / SBIR / DIBBS** - `listExclusions(options)` / `getExclusion(exclusionKey, options)` - `listSbirTopics(options)` / `getSbirTopic(topicId, options)` - `listSbirSolicitations(options)` / `getSbirSolicitation(solicitationId, options)` - `listDibbsRfqs(options)` / `getDibbsRfq(uuid, options)` - `listDibbsRfps(options)` / `getDibbsRfp(uuid, options)` - `listDibbsAwards(options)` / `getDibbsAward(uuid, options)` **Reference / Lookups** - `listBusinessTypes(options)` / `getBusinessType(code)` - `listNaics(options)` / `getNaics(code)` / `getNaicsMetrics(code, months, periodGrouping)` - `listPsc(options)` / `getPsc(code)` / `getPscMetrics(code, months, periodGrouping)` - `listMasSins(options)` / `getMasSin(sin)` - `listAssistanceListings(options)` / `getAssistanceListing(number)` - `listMetrics(options)` / `listAgencyAwardingContracts(code, options)` / `listAgencyFundingContracts(code, options)` **Resolve / Validate** - `resolve(input)` β€” resolve a free-text name to ranked entity/org candidates - `validate(input)` β€” validate a PIID, solicitation number, or UEI **Webhooks** - `listWebhookEventTypes()` - `listWebhookEndpoints(options)` / `getWebhookEndpoint(id)` - `createWebhookEndpoint(...)` / `updateWebhookEndpoint(id, patch)` / `deleteWebhookEndpoint(id)` - `testWebhookEndpoint(endpointId)` (preferred) / `testWebhookDelivery(options?)` (legacy alias) - `getWebhookSamplePayload(options?)` - `listWebhookAlerts(options)` / `getWebhookAlert(id)` / `createWebhookAlert(input)` - `updateWebhookAlert(id, patch)` / `deleteWebhookAlert(id)` **Async iteration helpers** - `iterate(method, options)` β€” generic async iterator over any supported list method - `iterateContracts` / `iterateEntities` / `iterateOpportunities` / `iterateNotices` - `iterateGrants` / `iterateForecasts` / `iterateIdvs` / `iterateVehicles` - `iterateDibbsRfqs` / `iterateDibbsRfps` / `iterateDibbsAwards` - `iterateExclusions` / `iterateSbirTopics` / `iterateSbirSolicitations` **Utility** - `getVersion()` / `listApiKeys()` See [docs/API_REFERENCE.md](api-reference.md) for full signatures and parameters. All list methods return a paginated response: ```ts interface PaginatedResponse { count: number; next: string | null; previous: string | null; pageMetadata: Record | null; meta: Record | null; agencyWarnings: string[]; unresolvedAgencyTokens: Record; resolvedAgencies: Record>>; cursor: string | null; results: T[]; } ``` `meta` surfaces response-level metadata from the API, and the three `agency*` fields are parsed views of its agency-filter diagnostics β€” see [API Reference Β§ Pagination](api-reference.md#pagination) for how to use them to catch silently-narrowed agency filters. `cursor` is extracted from `next` on keyset-paginated endpoints so you can pass it straight back as the next request's `cursor` option. ## Error Handling Errors are surfaced as typed exceptions, aligned with the Python SDK: - `TangoAPIError` – Base error for unexpected issues. - `TangoAuthError` – Authentication problems (e.g., invalid API key, 401). - `TangoNotFoundError` – Resource not found (404). - `TangoValidationError` – Invalid request parameters (400). Exposes the API's structured 400 payload via `issues` and `availableFields` (see the [API Reference](api-reference.md#error-types)). - `TangoEbuyAttachmentLinkError` – A `TangoValidationError` subclass thrown by `getEbuyAttachmentUrl()` when the attachment is an external link; its `url` is the link target. - `TangoRateLimitError` – Rate limit exceeded (429). - `TangoTimeoutError` – Request exceeded the configured `timeoutMs`. Shape-related errors: - `ShapeError` - `ShapeValidationError` - `ShapeParseError` - `TypeGenerationError` - `ModelInstantiationError` Use them in your code: ```ts import { TangoClient, TangoAPIError, TangoValidationError } from "@makegov/tango-node"; try { const resp = await client.listContracts({ keyword: "cloud", limit: 5 }); } catch (err) { if (err instanceof TangoValidationError) { console.error("Bad request:", err.message); } else if (err instanceof TangoAPIError) { console.error("Tango API error:", err.message); } else { console.error("Unexpected error:", err); } } ``` ## Project Structure ```text tango-node/ β”œβ”€β”€ src/ # Source TypeScript β”‚ β”œβ”€β”€ client.ts # TangoClient implementation β”‚ β”œβ”€β”€ config.ts # Default base URL + shape presets β”‚ β”œβ”€β”€ errors.ts # Error classes (API, auth, validation, etc.) β”‚ β”œβ”€β”€ index.ts # Public API exports β”‚ β”œβ”€β”€ types.ts # Shared types (options, PaginatedResponse) β”‚ β”œβ”€β”€ models/ # Lightweight model interfaces (Contract, Entity, etc.) β”‚ β”œβ”€β”€ shapes/ # Shape system (parser, generator, factory) β”‚ β”‚ β”œβ”€β”€ explicitSchemas.ts # Predefined schemas for resources β”‚ β”‚ β”œβ”€β”€ generatedOverlay.ts # Machine-generated schema overlay (see scripts/) β”‚ β”‚ β”œβ”€β”€ factory.ts # Instantiate typed models from data β”‚ β”‚ β”œβ”€β”€ generator.ts # Type generation from shape specs β”‚ β”‚ β”œβ”€β”€ index.ts # Shapes exports β”‚ β”‚ β”œβ”€β”€ parser.ts # Shape string parser β”‚ β”‚ β”œβ”€β”€ schema.ts # Schema registry + validation β”‚ β”‚ β”œβ”€β”€ schemaTypes.ts # Schema data structures β”‚ β”‚ └── types.ts # Shape spec types β”‚ β”œβ”€β”€ utils/ # Helpers β”‚ β”‚ β”œβ”€β”€ dates.ts # Date/time parsing utilities β”‚ β”‚ β”œβ”€β”€ http.ts # HTTP client wrapper β”‚ β”‚ β”œβ”€β”€ number.ts # Numeric parsing/formatting β”‚ β”‚ └── unflatten.ts # Unflatten dotted-key responses β”‚ └── webhooks/ # Signing, receiver, simulator, CLI β”œβ”€β”€ contracts/ # Vendored API contract + conformance baselines β”œβ”€β”€ scripts/ # Conformance gates, overlay generator, live smoke scripts β”œβ”€β”€ docs/ # Documentation β”‚ β”œβ”€β”€ API_REFERENCE.md β”‚ β”œβ”€β”€ CLIENT.md β”‚ β”œβ”€β”€ DEVELOPERS.md β”‚ β”œβ”€β”€ DYNAMIC_MODELS.md β”‚ β”œβ”€β”€ SHAPES.md β”‚ └── WEBHOOKS.md β”œβ”€β”€ tests/ # Test suite (Vitest) β”‚ β”œβ”€β”€ unit/ # Offline unit tests (fetchImpl mocks) β”‚ β”œβ”€β”€ integration/ # Cassette-replayed integration tests β”‚ β”œβ”€β”€ cassettes/ # Recorded API interactions (JSON) β”‚ β”œβ”€β”€ production/ # Env-gated live smoke suite (TANGO_LIVE_TESTS) β”‚ β”œβ”€β”€ scripts/ # Tests for the conformance gates β”‚ └── webhooks/ # Receiver / simulator / CLI tests β”œβ”€β”€ dist/ # Build output (compiled JS + d.ts) from `npm run build` β”œβ”€β”€ eslint.config.js # ESLint flat config β”œβ”€β”€ .prettierrc # Prettier config β”œβ”€β”€ package.json # Package metadata/scripts β”œβ”€β”€ tsconfig.json # TypeScript config β”œβ”€β”€ README.md # Usage docs β”œβ”€β”€ CHANGELOG.md # Version history └── LICENSE # MIT license ``` ## Development After cloning the repo: ```bash npm install npm run build npm test ``` Useful scripts: - `npm run build` – Compile TypeScript to `dist/`. - `npm test` – Run unit and integration tests (integration replays committed cassettes offline). - `npm run coverage` – Get test coverage report. - `npm run lint` – Run ESLint. - `npm run format` – Run Prettier. - `npm run typecheck` – TS type checking without emit. - `npm run check-conformance` – SDK filters/shapes vs the vendored API contract. - `npm run check-shape-coverage` – Reverse gate: every contract shape field is captured by the SDK. - `npm run generate-shape-overlay` – Regenerate `src/shapes/generatedOverlay.ts` from the vendored contract. - `npm run vendor-contract -- PATH` – Re-vendor `contracts/filter_shape_contract.json` from an upstream copy, keeping only what the SDK consumes. See [docs/DEVELOPERS.md](https://github.com/makegov/tango-node/blob/main/docs/DEVELOPERS.md) for the conformance architecture and the cassette record/replay workflow. ## Requirements - Node.js 20 or higher. - A valid [Tango API key](https://tango.makegov.com/). ## Documentation - [API Reference](api-reference.md) - Detailed API documentation - [Shape System Guide](shapes.md) - Comprehensive guide to response shaping - [Dynamic Models Guide](dynamic-models.md) - How the dynamic shaping system works. ## License MIT License - see [LICENSE](https://github.com/makegov/tango-node/blob/main/LICENSE) for details. ## Support For questions, issues, or feature requests: - **Email**: [tango@makegov.com](mailto:tango@makegov.com) - **Issues**: [GitHub Issues](https://github.com/makegov/tango-node/issues) - **Documentation**: [https://docs.makegov.com/sdks/node/](https://docs.makegov.com/sdks/node/) ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Run tests (`npm run test`) 4. Commit your changes (`git commit -m 'Add amazing feature'`) 5. Push to the branch (`git push origin feature/amazing-feature`) 6. Open a Pull Request --- # Tango Node SDK – Shaping Guide A complete translation of the Python SHAPES.md document for Node. --- ## Why Shapes? Tango resources can have hundreds of fields. Shapes let you request: - Only what you need - In nested form - With aliases - With wildcards - With flattening options --- ## Shape Grammar ``` shape := field_list field_list := field ("," field)* field := field_name [alias] [nested] field_name := identifier | "*" alias := "::" identifier nested := "(" field_list ")" identifier := [a-zA-Z_][a-zA-Z0-9_]* ``` --- ## Examples ### Simple ```ts shape: "key,piid,award_date"; ``` ### Nested ```ts shape: "recipient(display_name,uei)"; ``` ### Aliases ```ts shape: "recipient::vendor(display_name)"; ``` ### Wildcard ```ts shape: "*"; ``` ### Wildcard nested ```ts shape: "recipient(*)"; ``` --- ## ShapeConfig Presets The SDK ships with a `ShapeConfig` object of ready-made shape strings for common patterns. Import from the main entry point: ```ts import { TangoClient, ShapeConfig } from "@makegov/tango-node"; ``` | Constant | Intended use | | --------------------------------------------------- | --------------------------- | | `ShapeConfig.CONTRACTS_MINIMAL` | `listContracts()` | | `ShapeConfig.ENTITIES_MINIMAL` | `listEntities()` | | `ShapeConfig.ENTITIES_COMPREHENSIVE` | `getEntity()` | | `ShapeConfig.FORECASTS_MINIMAL` | `listForecasts()` | | `ShapeConfig.OPPORTUNITIES_MINIMAL` | `listOpportunities()` | | `ShapeConfig.NOTICES_MINIMAL` | `listNotices()` | | `ShapeConfig.PROTESTS_MINIMAL` | `listProtests()` | | `ShapeConfig.GRANTS_MINIMAL` | `listGrants()` | | `ShapeConfig.IDVS_MINIMAL` | `listIdvs()` | | `ShapeConfig.IDVS_COMPREHENSIVE` | `getIdv()` | | `ShapeConfig.VEHICLES_MINIMAL` | `listVehicles()` | | `ShapeConfig.VEHICLES_COMPREHENSIVE` | `getVehicle()` | | `ShapeConfig.VEHICLE_AWARDEES_MINIMAL` | `listVehicleAwardees()` | | `ShapeConfig.VEHICLE_ORDERS_MINIMAL` | `listVehicleOrders()` | | `ShapeConfig.ORGANIZATIONS_MINIMAL` | `listOrganizations()` | | `ShapeConfig.OTAS_MINIMAL` | `listOtas()` | | `ShapeConfig.OTIDVS_MINIMAL` | `listOtidvs()` | | `ShapeConfig.SUBAWARDS_MINIMAL` | `listSubawards()` | | `ShapeConfig.GSA_ELIBRARY_CONTRACTS_MINIMAL` | `listGsaElibraryContracts()` / `getGsaElibraryContract()` | | `ShapeConfig.ITDASHBOARD_INVESTMENTS_MINIMAL` | `listItDashboard()` | | `ShapeConfig.ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` | `getItDashboard()` | | `ShapeConfig.DIBBS_RFQS_MINIMAL` | `listDibbsRfqs()` | | `ShapeConfig.DIBBS_RFPS_MINIMAL` | `listDibbsRfps()` | | `ShapeConfig.DIBBS_AWARDS_MINIMAL` | `listDibbsAwards()` | | `ShapeConfig.EXCLUSIONS_MINIMAL` | `listExclusions()` | | `ShapeConfig.SBIR_TOPICS_MINIMAL` | `listSbirTopics()` | | `ShapeConfig.SBIR_SOLICITATIONS_MINIMAL` | `listSbirSolicitations()` | | `ShapeConfig.FEDERAL_REGISTER_MINIMAL` | `listFederalRegisterDocuments()` | | `ShapeConfig.FEDERAL_REGISTER_COMPREHENSIVE` | `getFederalRegisterDocument()` | These are plain strings β€” you can use them directly or as a starting point: ```ts const contracts = await client.listContracts({ shape: ShapeConfig.CONTRACTS_MINIMAL, limit: 10, }); ``` --- ## Flat Responses ```ts shape: ShapeConfig.CONTRACTS_MINIMAL, flat: true ``` When `flat: true` is passed, the Tango API returns dotted key names instead of nested objects. The SDK automatically unflattens them back into nested objects on the client side: ```ts // API returns: { "recipient.display_name": "Acme" } // SDK unflattens to: { recipient: { display_name: "Acme" } } ``` You can override the separator character (default `"."`) with the `joiner` option. --- ## Validation ShapeParser enforces syntax. TypeGenerator enforces semantic model rules (existence of fields, nested models). --- ## Performance Tips - Use minimal shapes in production. - Avoid full-wildcard unless you need all fields. - Prefer shallow nested shapes for large nested structures. --- # Webhooks Guide This guide covers everything `@makegov/tango-node` provides for **building, testing, and operating webhook integrations against the Tango API**: signing helpers, signature verification, and management commands for endpoints and alerts. If you only need the SDK method signatures, see [`API_REFERENCE.md` Β§ Webhooks](api-reference.md#webhooks-v2). For the API-level contract (signing scheme, event taxonomy, retry behavior), see the [Tango Webhooks Partner Guide](https://docs.makegov.com/webhooks-user-guide/). > **Breaking change in v0.4.0**: subject-based webhook subscriptions have been removed. Use the [Alerts API](#alerts-filter-subscription-api) for filter-based delivery. Mirrors [makegov/tango#2267](https://github.com/makegov/tango/issues/2267). --- ## Contents - [Install](#install) - [Concepts in 60 seconds](#concepts-in-60-seconds) - [Quickstart: zero to receiving](#quickstart-zero-to-receiving) - [Programmatic use](#programmatic-use) - [Signature verification in your handler](#signature-verification-in-your-handler) - [Generating signatures (for testing)](#generating-signatures-for-testing) - [Parsing the signature header](#parsing-the-signature-header) - [Webhook write API](#webhook-write-api) - [Endpoints](#endpoints) - [Alerts (filter-subscription API)](#alerts-filter-subscription-api) - [Event types and sample payloads](#event-types-and-sample-payloads) - [Test delivery](#test-delivery) - [Common workflows](#common-workflows) - [Troubleshooting](#troubleshooting) --- ## Install ```bash npm install @makegov/tango-node # or yarn add @makegov/tango-node # or pnpm add @makegov/tango-node ``` The signing helpers and full webhook write API are included in the default install β€” no extras needed. ```ts import { TangoClient, generateSignature, verifySignature, parseSignatureHeader, SIGNATURE_HEADER, SIGNATURE_PREFIX } from "@makegov/tango-node"; ``` --- ## Concepts in 60 seconds Tango webhooks have three pieces of state: | Concept | What it is | Tango term | | ------------ | ----------------------------------------------------------------------- | -------------------- | | **Endpoint** | The URL Tango POSTs to, plus a generated signing secret | `WebhookEndpoint` | | **Alert** | A saved query-filter that fires deliveries when matching records appear | `WebhookAlert` | | **Delivery** | A single signed POST Tango makes when a matching event fires | (the request itself) | A typical setup: 1. **Create an endpoint** with the public URL of your handler. Tango returns a `secret` β€” save it; it's used to sign every delivery. 2. **Create one or more alerts** describing the records your handler cares about (e.g. new IT-services contracts). 3. **Tango POSTs** to your endpoint when matching records appear. The body is JSON; the header `X-Tango-Signature: sha256=` is the HMAC-SHA256 of the raw body bytes keyed by your endpoint's secret. 4. **Your handler verifies the signature**, parses the body, and acts on it. --- ## Quickstart: zero to receiving Assumes you have a `TANGO_API_KEY` and want to receive webhooks for new IT-services contracts. ### 1. See what you can subscribe to ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const info = await client.listWebhookEventTypes(); console.log(info.event_types); // [{ event_type: "alerts.contract.match", description: "...", schema_version: 1 }, ...] ``` The list is served by the API, so the SDK hardcodes no event types and a new one needs no SDK release. `alerts.federal_register.match` and `alerts.ebuy_request.match` are among them, so `createWebhookAlert({ query_type: "federal_register", ... })` and `query_type: "ebuy_request"` work. ### 2. See what a payload looks like ```ts const sample = await client.getWebhookSamplePayload({ eventType: "alerts.contract.match" }); console.log(JSON.stringify(sample, null, 2)); ``` Fetches the canonical JSON shape Tango will deliver for that event type. No alert needed. ### 3. Register your endpoint and alert When you're ready for end-to-end testing, expose your local handler via a tunnel (`ngrok http 3000`, `cloudflared tunnel`, etc.) and register that public URL with Tango: ```ts // Endpoint names are unique per user. Tango returns a secret β€” save it. const endpoint = await client.createWebhookEndpoint({ callbackUrl: "https://.ngrok.io/tango/webhooks", name: "dev", }); console.log("Secret:", endpoint.secret); // save this! // Create an alert β€” fires when matching records appear const alert = await client.createWebhookAlert({ name: "New IT cloud contracts", query_type: "contract", // singular β€” required filters: { naics: "541511" }, // any /api/contracts/ filter }); ``` ### 4. Force a test delivery ```ts const result = await client.testWebhookEndpoint(endpoint.id); console.log(result.success, result.status_code); ``` You should see a signed delivery hit your handler with the `X-Tango-Signature` header generated by Tango. --- ## Programmatic use ### Signature verification in your handler `verifySignature` is the only function you need in production. It takes `(body, header, secret)` β€” note the arg order. Call it on the **raw request body bytes** β€” not on a re-serialized parsed body. The HMAC is computed over the exact bytes Tango sent; reformatting or reordering keys breaks it. ```ts import { verifySignature } from "@makegov/tango-node"; // Express example app.post("/tango/webhooks", express.raw({ type: "application/json" }), (req, res) => { const rawBody = req.body; // Buffer β€” express.raw() gives you bytes const signatureHeader = req.headers["x-tango-signature"]; if (!verifySignature(rawBody, signatureHeader, process.env.TANGO_WEBHOOK_SECRET)) { return res.status(401).json({ error: "invalid_signature" }); } const payload = JSON.parse(rawBody.toString("utf8")); // ... act on payload.events ... res.json({ ok: true }); }); ``` `verifySignature` signature: ```ts function verifySignature(body: string | Buffer, header: string | null | undefined, secret: string): boolean; ``` - Returns `false` for missing, empty, malformed, or mismatched headers β€” never throws on mismatch. - Uses `timingSafeEqual` from `node:crypto` internally. - Accepts both the canonical `sha256=` header form and a bare hex string (legacy compatibility). **Fastify example:** ```ts import { verifySignature } from "@makegov/tango-node"; fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (req, body, done) => { done(null, body); }); fastify.post("/tango/webhooks", async (request, reply) => { const rawBody = request.body as Buffer; const signatureHeader = request.headers["x-tango-signature"] as string | undefined; if (!verifySignature(rawBody, signatureHeader ?? null, process.env.TANGO_WEBHOOK_SECRET!)) { reply.code(401).send({ error: "invalid_signature" }); return; } const payload = JSON.parse(rawBody.toString("utf8")); // ... handle payload ... reply.send({ ok: true }); }); ``` ### Generating signatures (for testing) `generateSignature` produces the exact header value Tango sends. Use it in tests to sign synthetic payloads before POSTing to your handler. ```ts import { generateSignature, SIGNATURE_HEADER } from "@makegov/tango-node"; const body = Buffer.from( JSON.stringify({ event_type: "alerts.entity.match", alert_id: "alert_123", query_type: "entity", filters: { uei: "ABC123" }, matches: { new: [], modified: [], new_count: 0, modified_count: 0 }, checked_at: "2024-01-01T00:00:00Z", }), ); const signatureHeader = generateSignature(body, "test_secret"); // β†’ "sha256=" // Drive your handler directly (e.g. in a test): const response = await fetch("http://localhost:3000/tango/webhooks", { method: "POST", headers: { "Content-Type": "application/json", [SIGNATURE_HEADER]: signatureHeader, }, body, }); ``` `generateSignature` signature: ```ts function generateSignature(body: string | Buffer, secret: string): string; // Returns: "sha256=" ``` The return value is always the prefixed form `sha256=` β€” pass it directly as the `X-Tango-Signature` header value. ### Parsing the signature header `parseSignatureHeader` breaks a raw `X-Tango-Signature` header value into its component parts. Mainly useful for debugging or building custom verification logic. ```ts import { parseSignatureHeader } from "@makegov/tango-node"; const parsed = parseSignatureHeader("sha256=abc123def456"); // β†’ { algorithm: "sha256", signature: "abc123def456" } const bad = parseSignatureHeader("sha256="); // β†’ null (empty digest) const missing = parseSignatureHeader(null); // β†’ null ``` Returns `null` for absent, empty, or malformed values (non-hex digest, empty digest). Never throws. --- ## Webhook write API All methods are on `TangoClient`. They're async and return Promises. Webhook APIs require **Large / Enterprise** tier access. ### Endpoints An endpoint is the URL Tango POSTs to, paired with a signing secret. ```ts const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); // List const list = await client.listWebhookEndpoints({ page: 1, limit: 25 }); // Get one const endpoint = await client.getWebhookEndpoint("ENDPOINT_UUID"); // Create β€” `name` is required and must be unique per user; save the returned `secret` const created = await client.createWebhookEndpoint({ callbackUrl: "https://example.com/tango/webhooks", name: "Production handler", isActive: true, // default true }); console.log("Secret:", created.secret); // only returned on create β€” save it // Update await client.updateWebhookEndpoint(created.id, { isActive: false }); // Delete await client.deleteWebhookEndpoint(created.id); ``` `createWebhookEndpoint` also accepts the snake_case canonical API form directly (`callback_url`, `is_active`). CamelCase is preferred for new code. **`WebhookEndpoint` shape:** ```ts interface WebhookEndpoint { id: string; name: string; callback_url: string; secret?: string; // present on create response only is_active: boolean; created_at: string; updated_at: string; } ``` ### Alerts (filter-subscription API) Alerts are the SDK's interface for telling Tango "deliver me records matching this filter." Subject-based subscriptions (match by event type + specific subject IDs) were removed in v0.4.0 β€” alerts are now the only way to subscribe. ```ts // Create const alert = await client.createWebhookAlert({ name: "New IT cloud contracts", query_type: "contract", // singular β€” required filters: { naics: "541511" }, // required, non-empty frequency: "daily", // optional }); // List const alerts = await client.listWebhookAlerts({ page: 1, pageSize: 25 }); // Get const alert = await client.getWebhookAlert("ALERT_UUID"); // Update await client.updateWebhookAlert("ALERT_UUID", { name: "Updated name" }); // Delete await client.deleteWebhookAlert("ALERT_UUID"); ``` **`WebhookAlert` shape:** ```ts interface WebhookAlert { alert_id: string; name: string; query_type: string; filters: Record; frequency: string; cron_expression: string | null; status: "active" | "paused"; created_at: string; last_checked_at: string | null; match_count: number; } ``` ### Event types and sample payloads ```ts // List all supported event types const info = await client.listWebhookEventTypes(); // info.event_types β†’ [{ event_type, description, schema_version }] // Fetch a canonical sample payload for one event type const sample = await client.getWebhookSamplePayload({ eventType: "alerts.contract.match" }); // Or fetch sample payloads for all event types at once const all = await client.getWebhookSamplePayload(); ``` `getWebhookSamplePayload` wraps `GET /api/webhooks/endpoints/sample-payload/`. When `eventType` is omitted, returns all event types. The response includes a `signature_header` field showing what the `X-Tango-Signature` header will look like β€” useful for understanding the wire format. ### Test delivery Force Tango to POST a real test delivery to a registered endpoint: ```ts const result = await client.testWebhookEndpoint("ENDPOINT_UUID"); console.log(result.success); // boolean console.log(result.status_code); // HTTP code Tango got from your endpoint console.log(result.response_time_ms); console.log(result.message); console.log(result.error); // set on failure ``` **`WebhookTestDeliveryResult` shape:** ```ts interface WebhookTestDeliveryResult { success: boolean; status_code?: number; response_time_ms?: number; endpoint_url?: string; message?: string; error?: string; response_body?: string; test_payload?: Record; } ``` `testWebhookDelivery(options?)` is a legacy alias that accepts `{ endpointId?: string }`. If `endpointId` is omitted, the API auto-resolves the caller's only endpoint (404 if none, 400 if multiple). Prefer `testWebhookEndpoint` for new code. --- ## Common workflows ### "Set me up to receive contract-match alerts from scratch" ```ts import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); // 1. Confirm available event types const { event_types } = await client.listWebhookEventTypes(); console.log(event_types.map((e) => e.event_type)); // 2. Create endpoint β€” expose your handler via ngrok/cloudflared first const endpoint = await client.createWebhookEndpoint({ callbackUrl: "https://.ngrok.io/tango/webhooks", }); // Save endpoint.secret β€” you need it to verify incoming deliveries process.env.TANGO_WEBHOOK_SECRET = endpoint.secret!; // 3. Create an alert β€” fires when matching records appear await client.createWebhookAlert({ name: "New IT cloud contracts", query_type: "contract", filters: { naics: "541511" }, }); // 4. Force a test delivery to verify your handler is reachable const result = await client.testWebhookEndpoint(endpoint.id); console.log("Delivery success:", result.success, "Status:", result.status_code); ``` ### "Verify a Tango delivery in any HTTP framework" ```ts import { verifySignature } from "@makegov/tango-node"; // The pattern is the same in Express, Fastify, Hono, Next.js API routes, etc.: // 1. Get raw body bytes BEFORE any JSON parsing middleware // 2. Get the X-Tango-Signature header // 3. Call verifySignature(rawBody, header, secret) function handleTangoWebhook(rawBody: Buffer, signatureHeader: string | undefined) { if (!verifySignature(rawBody, signatureHeader ?? null, process.env.TANGO_WEBHOOK_SECRET!)) { throw new Error("invalid_signature"); } return JSON.parse(rawBody.toString("utf8")); } ``` ### "Test my handler in a unit test (no network)" Use `generateSignature` to sign synthetic payloads and POST them directly to your handler β€” no Tango account or live endpoint needed: ```ts import { generateSignature, SIGNATURE_HEADER } from "@makegov/tango-node"; const secret = "test_secret"; const payload = { timestamp: "2024-01-01T00:00:00Z", events: [{ event_type: "alerts.contract.match", record: { piid: "ABC123" } }], }; const rawBody = Buffer.from(JSON.stringify(payload)); const sig = generateSignature(rawBody, secret); // Drive your handler directly β€” e.g. with supertest or a test fetch: const res = await request(app).post("/tango/webhooks").set("Content-Type", "application/json").set(SIGNATURE_HEADER, sig).send(rawBody); expect(res.status).toBe(200); ``` ### "Inspect what bytes Tango actually sends" ```ts const sample = await client.getWebhookSamplePayload({ eventType: "alerts.contract.match" }); // sample.signature_header shows the X-Tango-Signature format // sample.sample_delivery shows the exact JSON body shape console.log(JSON.stringify(sample.sample_delivery, null, 2)); ``` --- ## Troubleshooting **Signature always fails.** Verify on raw bytes, not on a re-serialized parsed body. The HMAC is over exact bytes; reformatting whitespace or reordering keys breaks it. Most frameworks expose the raw body separately from a parsed JSON shortcut β€” use the raw one. In Express, use `express.raw({ type: "application/json" })` before your route handler. **`verifySignature` returns `false` even with the right secret.** Check argument order: it's `(body, header, secret)` β€” the header is second, secret is third. This differs from some other webhook libraries. **`createWebhookEndpoint` returns 400 or "endpoint already exists".** Endpoint names are unique per user β€” if you've already created one with that `name`, either pick a different name or use `listWebhookEndpoints()` to find the existing one and reuse its ID. **`createWebhookAlert` throws `TangoValidationError: query_type is required`.** The `query_type` field is singular β€” `"contract"`, not `"contracts"`. **An alert never fires when a record just reaches its date β€” except `sled_opportunity`.** An exclusion passing its termination date, or a DIBBS RFQ/RFP passing its close date, emits nothing: open/closed and in-force are derived at query time, so no stored row changes. Poll `listExclusions({ active: true })` / `listDibbsRfqs({ open: true })` if you need to observe expiry. `sled_opportunity` is the one exception. A state solicitation's liveness is a stored `status` column Tango recomputes every fifteen minutes rather than deriving per request, so a deadline passing **is** a write and `alerts.sled_opportunity.match` can follow it. There is no `sled_forecast` query type β€” a forecast has no deadline, so nothing transitions β€” and SLED revisions and attachments are not separately alertable: subscribe to `sled_opportunity` and filter on `change_seen_after` or `revision_kind`. **`testWebhookEndpoint` returns `success: false`.** Tango reached your endpoint but got a non-2xx response. Check `result.status_code` and `result.response_body` in the result, then look at your handler's logs. **`getWebhookSamplePayload` throws with 401.** Set `TANGO_API_KEY` (or pass `apiKey` to `TangoClient`). This endpoint requires authentication. **`listWebhookAlerts` returns an empty array unexpectedly.** Check your API key β€” alerts are scoped to the authenticated user. Also confirm the endpoint UUID associated with your alerts matches your current endpoint (alerts pointing at a deleted endpoint aren't automatically cleaned up). --- # API Reference Complete reference for all Tango Python SDK methods and functionality. ## Table of Contents - [Client Initialization](#client-initialization) - [Agencies](#agencies) - [Offices](#offices) - [Organizations](#organizations) - [Contracts](#contracts) - [IDVs](#idvs) - [OTAs](#otas) - [OTIDVs](#otidvs) - [Subawards](#subawards) - [Vehicles](#vehicles) - [Entities](#entities) - [Forecasts](#forecasts) - [Opportunities](#opportunities) - [Notices](#notices) - [State \& Local (SLED)](#state--local-sled) - [Grants](#grants) - [GSA eLibrary Contracts](#gsa-elibrary-contracts) - [Protests](#protests) - [Contract Appeals](#contract-appeals) - [Federal Register](#federal-register) - [GSA eBuy](#gsa-ebuy) - [Budget](#budget) - [Business Types](#business-types) - [NAICS](#naics) - [Webhooks](#webhooks) - [Response Objects](#response-objects) - [ShapeConfig (predefined shapes)](#shapeconfig-predefined-shapes) - [Error Handling](#error-handling) ## Client Initialization ### TangoClient Initialize the Tango API client. ```python from tango import TangoClient # With API key client = TangoClient(api_key="your-api-key") # From environment variable (TANGO_API_KEY) client = TangoClient() # Custom base URL (for testing or different environments) client = TangoClient(api_key="your-api-key", base_url="https://custom.api.url") ``` **Parameters:** - `api_key` (str, optional): Your Tango API key. If not provided, will load from `TANGO_API_KEY` environment variable. - `base_url` (str, optional): Base URL for the API. Defaults to `https://tango.makegov.com`. --- ## Agencies Government agencies that award contracts and manage programs. ### list_agencies() List all federal agencies. ```python agencies = client.list_agencies(page=1, limit=25) ``` **Parameters:** - `page` (int): Page number (default: 1) - `limit` (int): Results per page (default: 25, max: 100) - `search` (str, optional): Search term to filter agencies by name **Returns:** [PaginatedResponse](#paginatedresponse) with `Agency` dataclass objects **Example:** ```python agencies = client.list_agencies(limit=10) print(f"Found {agencies.count} total agencies") for agency in agencies.results: print(f"{agency.code}: {agency.name}") ``` ### get_agency() Get a specific agency by code. ```python agency = client.get_agency("GSA") ``` **Parameters:** - `code` (str): Agency identifier. Accepts CGAC ("097"), FPDS code ("4712"), short code ("GSA"), abbreviation, or canonical name. See [Federal agency hierarchy](https://docs.makegov.com/api-reference/concepts/federal-agency-hierarchy/) for code semantics. **Returns:** `Agency` dataclass with agency details **Example:** ```python gsa = client.get_agency("GSA") print(f"Name: {gsa.name}") print(f"Abbreviation: {gsa.abbreviation or 'N/A'}") if gsa.department: print(f"Department: {gsa.department.name}") ``` **Agency Fields:** - `code` - Agency code - `name` - Full agency name - `abbreviation` - Short name - `department` - Parent department (if applicable) --- ## Offices Federal agency offices. ### list_offices() List offices with optional search. ```python offices = client.list_offices(page=1, limit=25, search="acquisitions") ``` **Parameters:** - `page` (int): Page number (default: 1) - `limit` (int): Results per page (default: 25, max: 100) - `search` (str, optional): Search term **Returns:** [PaginatedResponse](#paginatedresponse) with office dictionaries ### get_office() Get a specific office by code. ```python office = client.get_office(code="4732XX") ``` **Parameters:** - `code` (str): Office code **Returns:** Dictionary with office details --- ## Organizations Federal organizations (hierarchical agency structure). ### list_organizations() List organizations with filtering and shaping. ```python organizations = client.list_organizations( page=1, limit=25, shape=ShapeConfig.ORGANIZATIONS_MINIMAL, # Filter parameters cgac=None, include_inactive=None, level=None, parent=None, search=None, type=None, ) ``` **Parameters:** - `page` (int): Page number (default: 1) - `limit` (int): Results per page (default: 25, max: 100) - `shape` (str, optional): Response shape string - `flat` (bool): Flatten nested objects (default: False) - `flat_lists` (bool): Flatten arrays with indexed keys (default: False) **Filter Parameters:** - `cgac` - Filter by CGAC code - `include_inactive` - Include inactive organizations - `level` - Filter by organization level - `parent` - Filter by parent organization - `search` - Search term - `type` - Filter by organization type **Returns:** [PaginatedResponse](#paginatedresponse) with organization dictionaries ### get_organization() Get a specific organization by fh_key. ```python org = client.get_organization(fh_key="ORG_KEY", shape=ShapeConfig.ORGANIZATIONS_MINIMAL) ``` **Parameters:** - `fh_key` (str): Organization key - `shape` (str, optional): Response shape string - `flat` (bool): Flatten nested objects (default: False) - `flat_lists` (bool): Flatten arrays with indexed keys (default: False) **Returns:** Dictionary with organization details --- ## Contracts Federal contract awards and procurement data. ### list_contracts() Search and filter contracts with extensive options. ```python contracts = client.list_contracts( cursor=None, # keyset pagination token (not page number) limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) # Text search keyword=None, # Mapped to 'search' API param # Date filters award_date_gte=None, award_date_lte=None, pop_start_date_gte=None, pop_start_date_lte=None, pop_end_date_gte=None, pop_end_date_lte=None, expiring_gte=None, expiring_lte=None, # Party filters awarding_agency=None, funding_agency=None, recipient_name=None, # Mapped to 'recipient' API param recipient_uei=None, # Mapped to 'uei' API param # Classification naics_code=None, # Mapped to 'naics' API param psc_code=None, # Mapped to 'psc' API param set_aside_type=None, # Mapped to 'set_aside' API param commercial_item_acquisition_procedures=None, # FPDS code A-E, e.g. "A|E" # Type filters fiscal_year=None, fiscal_year_gte=None, fiscal_year_lte=None, award_type=None, # Identifiers piid=None, solicitation_identifier=None, # Sorting sort=None, # Combined with 'order' into 'ordering' API param order=None, # 'asc' or 'desc' ) ``` **Common Parameters:** - `cursor` (str, optional): Keyset pagination token from `response.next` (contracts use keyset pagination, not page numbers) - `limit` (int): Results per page (max: 100) - `shape` (str): Fields to return (see [Shaping Guide](shapes.md)) - `flat` (bool): Flatten nested objects to dot-notation keys - `flat_lists` (bool): Flatten arrays with indexed keys - `exact` (bool, keyword-only): Ask for an exact `count` (see [Exact counts](#exact-counts)) **Filter Parameters:** **Text Search:** - `keyword` - Search contract descriptions (automatically mapped to API's 'search' parameter) **Date Filters:** - `award_date_gte` - Awarded on or after date (YYYY-MM-DD) - `award_date_lte` - Awarded on or before date (YYYY-MM-DD) - `pop_start_date_gte` - Period of performance start date β‰₯ - `pop_start_date_lte` - Period of performance start date ≀ - `pop_end_date_gte` - Period of performance end date β‰₯ - `pop_end_date_lte` - Period of performance end date ≀ - `expiring_gte` - Expiring on or after date - `expiring_lte` - Expiring on or before date **Party Filters:** - `awarding_agency` - Agency code (e.g., "4700" for GSA) - `funding_agency` - Funding agency code - `recipient_name` - Vendor/recipient name (mapped to 'recipient' API param) - `recipient_uei` - Vendor UEI (mapped to 'uei' API param). Several UEIs joined by `|` match awards to any of them, up to 500 (Tango API 5.11.0). **Classification:** - `naics_code` - NAICS industry code (mapped to 'naics' API param) - `psc_code` - Product/Service code (mapped to 'psc' API param) - `set_aside_type` - Set-aside type (mapped to 'set_aside' API param) - `commercial_item_acquisition_procedures` - FPDS commercial item acquisition procedures code, case-insensitive: `A` (commercial products/services), `B` (products or services pursuant to FAR 12.102(f)), `C` (services pursuant to FAR 12.102(g)), `D` (commercial procedures not used) or `E` (DoD Section 803 Commercial Solutions Opening). Multi-value OR via `|`, e.g. `"A|E"`. An unknown or multi-character code matches nothing. **Type Filters:** - `fiscal_year` - Federal fiscal year (exact match) - `fiscal_year_gte` - Fiscal year β‰₯ - `fiscal_year_lte` - Fiscal year ≀ - `award_type` - Award type code **Identifiers:** - `piid` - Procurement Instrument Identifier (exact match) - `solicitation_identifier` - Solicitation ID **Sorting:** - `sort` - Field to sort by (e.g., "award_date", "obligated") - `order` - Sort order: "asc" or "desc" (default: "asc") **Returns:** [PaginatedResponse](#paginatedresponse) with contract dictionaries **Examples:** ```python # Basic search contracts = client.list_contracts(limit=10) # Filter by agency contracts = client.list_contracts( awarding_agency="4700", # GSA agency code limit=50 ) # Text search contracts = client.list_contracts( keyword="software development", limit=50 ) # Date range contracts = client.list_contracts( award_date_gte="2023-01-01", award_date_lte="2023-12-31", limit=100 ) # Expiring contracts contracts = client.list_contracts( expiring_gte="2025-01-01", expiring_lte="2025-12-31", limit=50 ) # Multiple filters contracts = client.list_contracts( keyword="IT services", awarding_agency="4700", # GSA fiscal_year=2024, naics_code="541511", limit=100 ) # With shaping for performance contracts = client.list_contracts( shape="key,piid,recipient(display_name),total_contract_value,award_date", awarding_agency="4700", fiscal_year=2024, limit=100 ) # Sorting results contracts = client.list_contracts( sort="award_date", order="desc", limit=100 ) ``` **Common Contract Fields:** - `key` - Unique identifier - `piid` - Procurement Instrument Identifier - `description` - Contract description - `award_date` - Date awarded - `fiscal_year` - Fiscal year - `total_contract_value` - Total value - `total_obligated` - Total obligated amount - `recipient` - Vendor information (nested) - `awarding_agency` - Awarding agency (nested) - `funding_agency` - Funding agency (nested) - `naics` - Industry classification (nested) - `psc` - Product/service code (nested) - `place_of_performance` - Location (nested) **Obligations by fiscal year β€” `obligations_by_fiscal_year(fiscal_year, obligated)`** (Tango API 5.11.0): ```python contracts = client.list_contracts( shape="key,piid,obligated,obligations_by_fiscal_year(fiscal_year,obligated)", piid="SOME_PIID", ) for year in contracts.results[0]["obligations_by_fiscal_year"] or []: print(year["fiscal_year"], year["obligated"]) # int, Decimal ``` - Sums the award's transactions per federal fiscal year (October 1 starts the next fiscal year), oldest year first, each rounded to cents. A de-obligation nets against its own year, so a year can be zero or negative. - Returned only when named: no default shape includes it. - The same expand works on `list_otas()`, `list_idvs()`, `list_otidvs()` and the `get_*` methods. On IDVs and OTIDVs it is always `None`, because their transactions report a running lifetime total rather than each action's obligation. - `None` on a contract or OTA with no dated transactions. --- ## OTAs Other Transaction Agreements β€” non-FAR-based awards. ### list_otas() List OTAs with keyset pagination, filtering, and shaping. ```python otas = client.list_otas( limit=25, cursor=None, shape=ShapeConfig.OTAS_MINIMAL, # Filter parameters (all optional) award_date=None, award_date_gte=None, award_date_lte=None, awarding_agency=None, expiring_gte=None, expiring_lte=None, fiscal_year=None, fiscal_year_gte=None, fiscal_year_lte=None, funding_agency=None, ordering=None, piid=None, pop_end_date_gte=None, pop_end_date_lte=None, pop_start_date_gte=None, pop_start_date_lte=None, psc=None, recipient=None, search=None, uei=None, ) ``` **Notes:** - Uses **keyset pagination** (`cursor` + `limit`) rather than page numbers. - Filter parameters mirror those on `list_contracts`, except `commercial_item_acquisition_procedures`, which the API does not offer on OTAs or OTIDVs. **Returns:** [PaginatedResponse](#paginatedresponse) with OTA dictionaries ### get_ota() ```python ota = client.get_ota("OTA_KEY", shape=ShapeConfig.OTAS_MINIMAL) ``` --- ## OTIDVs Other Transaction IDVs β€” umbrella OT agreements that can have child awards. ### list_otidvs() List OTIDVs with keyset pagination, filtering, and shaping. ```python otidvs = client.list_otidvs( limit=25, cursor=None, shape=ShapeConfig.OTIDVS_MINIMAL, # Same filter parameters as list_otas() ) ``` **Notes:** - Uses **keyset pagination** (`cursor` + `limit`) rather than page numbers. - Filter parameters are identical to `list_otas()`. **Returns:** [PaginatedResponse](#paginatedresponse) with OTIDV dictionaries ### get_otidv() ```python otidv = client.get_otidv("OTIDV_KEY", shape=ShapeConfig.OTIDVS_MINIMAL) ``` --- ## Subawards Subcontract and subaward data under prime awards. ### list_subawards() List subawards with filtering and shaping. ```python subawards = client.list_subawards( page=1, limit=25, shape=ShapeConfig.SUBAWARDS_MINIMAL, # Filter parameters (all optional) award_key=None, awarding_agency=None, fiscal_year=None, fiscal_year_gte=None, fiscal_year_lte=None, funding_agency=None, prime_uei=None, recipient=None, sub_uei=None, ) ``` **Filter Parameters:** - `award_key` - Filter by prime award key - `awarding_agency` - Filter by awarding agency code - `fiscal_year` - Exact fiscal year - `fiscal_year_gte` / `fiscal_year_lte` - Fiscal year range - `funding_agency` - Filter by funding agency code - `prime_uei` - Filter by prime awardee UEI - `recipient` - Search by subrecipient name - `sub_uei` - Filter by subrecipient UEI **Returns:** [PaginatedResponse](#paginatedresponse) with subaward dictionaries --- ## Vehicles Vehicles provide a solicitation-centric way to discover groups of related IDVs and (optionally) expand into the underlying awards via shaping. ### list_vehicles() List vehicles with optional vehicle-level full-text search and ordering. ```python vehicles = client.list_vehicles( page=1, limit=25, search="GSA schedule", ordering="-vehicle_obligations", shape=ShapeConfig.VEHICLES_MINIMAL, flat=False, flat_lists=False, ) ``` **Parameters:** - `page` (int): Page number (default: 1) - `limit` (int): Results per page (default: 25, max: 100) - `search` (str, optional): Vehicle-level search term - `ordering` (str, optional): Server-side sort. Allowed: `vehicle_obligations`, `latest_award_date`. Prefix with `-` for descending. - `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLES_MINIMAL`) - `flat` (bool): Flatten nested objects in shaped response - `flat_lists` (bool): Flatten arrays using indexed keys - `joiner` (str): Joiner used when `flat=True` (default: `"."`) **Returns:** [PaginatedResponse](#paginatedresponse) with vehicle dictionaries ### get_vehicle() Get a single vehicle by UUID. ```python vehicle = client.get_vehicle( uuid="00000000-0000-0000-0000-000000000001", shape=ShapeConfig.VEHICLES_COMPREHENSIVE, ) ``` **Notes:** - On the vehicle detail endpoint, `search` filters **expanded awardees** when your `shape` includes `awardees(...)` (it does not filter the vehicle itself). ### list_vehicle_awardees() List the IDV awardees for a vehicle. ```python awardees = client.list_vehicle_awardees( uuid="00000000-0000-0000-0000-000000000001", shape=ShapeConfig.VEHICLE_AWARDEES_MINIMAL, ) ``` ### list_vehicle_orders() List task orders under a vehicle's IDVs (`/api/vehicles/{uuid}/orders/`). Optimized for fast pagination over large vehicles. ```python orders = client.list_vehicle_orders( uuid="00000000-0000-0000-0000-000000000001", limit=25, ordering="-obligated", shape=ShapeConfig.VEHICLE_ORDERS_MINIMAL, ) ``` **Parameters:** - `uuid` (str): Vehicle UUID - `page` (int): Page number (default: 1) - `limit` (int): Results per page (default: 25, max: 100) - `ordering` (str, optional): Server-side sort. Allowed: `award_date` (default), `obligated`, `total_contract_value`. Prefix with `-` for descending. - `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLE_ORDERS_MINIMAL`) - `flat`, `flat_lists`, `joiner`: as on other vehicles methods **Returns:** [PaginatedResponse](#paginatedresponse) with order (Contract) dictionaries ### Vehicle response fields The post-cutover (May 2026) vehicle response includes these top-level fields, all addressable via the `shape` parameter: | Field | Type | Notes | | ----- | ---- | ----- | | `uuid` | str | Stable identifier. | | `solicitation_identifier` | str | Solicitation shared by underlying IDVs. | | `is_synthetic_solicitation` | bool | `True` for GWAC orphans recovered via `ACRO:` prefix. | | `agency_id` | str | From IDV award-key suffix. | | `program_acronym` | str \| None | New post-cutover field. | | `organization_id` | str \| None | Awarding organization. | | `organization` | dict \| None | Live awarding-org snapshot `{organization_id, office_code, office_name, agency_code, agency_name, department_code, department_name}`. Selected as a leaf field (`shape=...,organization`); not currently sub-selectable. | | `vehicle_type`, `who_can_use`, `type_of_idc`, `contract_type` | dict \| None | Returned as `{code, description}`. | | `description` | str \| None | Common text across IDV descriptions. | | `descriptions` | list[str] \| None | Distinct IDV descriptions. | | `idv_count`, `order_count` | int \| None | Denormalized rollups. | | `holder_count` | int \| None | Distinct companies holding one of the vehicle's IDVs. | | `order_winner_count` | int \| None | Distinct companies that have won a task order under the vehicle. | | `awardee_count` | int \| None | **Deprecated.** Same value as `order_winner_count`; use that instead. Removed at the next major API version. | | `total_obligated`, `vehicle_obligations`, `vehicle_contracts_value` | Decimal \| None | Denormalized rollups. | | `award_date`, `latest_award_date`, `last_date_to_order` | date \| None | | | `solicitation_title`, `solicitation_description`, `solicitation_date`, `opportunity_id` | str / date / None | From SAM.gov via the linked Opportunity. | | `naics_code`, `psc_code`, `set_aside`, `fiscal_year` | int / str / None | | ### Vehicle shape expansions - `awardees(...)` β€” underlying IDV awards. Supports nested `orders(...)`. - `metrics(*)` β€” bundled computed metrics: `avg_offers_received`, `award_concentration_hhi`, `order_concentration_hhi`, `competed_rate`, `using_agency_count`, `avg_order_value`, `max_order_value`, `top_recipient_share`, `recent_obligations_24mo`, `recent_orders_24mo`, `days_since_last_order`, `obligation_to_ceiling_ratio`. Defaults included in `ShapeConfig.VEHICLES_COMPREHENSIVE`. - `organization` β€” live awarding-org snapshot (selected as a leaf field; not sub-selectable). ### Deprecated shape fields The following fields and expansions are still served by the API (recomputed at request time from the underlying IDVs) but the API now returns a `Deprecation: true` response header for them. They will be removed in a future tango API release. - `agency_details` (top-level field and `agency_details(*)` expansion) - `competition_details` (top-level field and `competition_details(*)` expansion) - `opportunity(*)` expansion (use the new top-level `solicitation_*` and `opportunity_id` fields instead) If you pass any of these in `shape=...`, the SDK will emit a Python `DeprecationWarning`. The default shapes (`VEHICLES_MINIMAL`, `VEHICLES_COMPREHENSIVE`) no longer include them. --- ## IDVs IDVs (indefinite delivery vehicles) are the parent β€œvehicle award” records that can have child awards/orders under them. ### list_idvs() ```python idvs = client.list_idvs( limit=25, cursor=None, shape=ShapeConfig.IDVS_MINIMAL, awarding_agency="4700", commercial_item_acquisition_procedures="E", # DoD Section 803 CSO ) ``` Notes: - This endpoint uses **keyset pagination** (`cursor` + `limit`) rather than page numbers. - `commercial_item_acquisition_procedures` takes the same FPDS codes `A`–`E` as on `list_contracts()`, with `|` for OR. - `exact=True` (keyword-only) asks for an exact `count` (see [Exact counts](#exact-counts)). ### get_idv() ```python idv = client.get_idv("SOME_IDV_KEY", shape=ShapeConfig.IDVS_COMPREHENSIVE) ``` ### list_idv_awards() Lists child awards (contracts) under an IDV. ```python awards = client.list_idv_awards("SOME_IDV_KEY", limit=25) ``` ### list_idv_child_idvs() Lists child IDVs under an IDV. ```python children = client.list_idv_child_idvs("SOME_IDV_KEY", limit=25) ``` ### list_idv_transactions() ```python tx = client.list_idv_transactions("SOME_IDV_KEY", limit=100) ``` --- ## Entities Vendors, recipients, and organizations doing business with the government. ### list_entities() List and search for entities (vendors/recipients). ```python entities = client.list_entities( page=1, limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) search=None, cage_code=None, naics=None, name=None, psc=None, purpose_of_registration_code=None, socioeconomic=None, state=None, total_awards_obligated_gte=None, total_awards_obligated_lte=None, uei=None, zip_code=None, ) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page - `shape` (str): Fields to return - `flat` (bool): Flatten nested objects - `flat_lists` (bool): Flatten arrays with indexed keys **Filter Parameters:** - `search` - Full-text search - `cage_code` - Filter by CAGE code - `naics` - Filter by NAICS code - `name` - Filter by entity name - `psc` - Filter by PSC code - `purpose_of_registration_code` - Filter by registration purpose - `socioeconomic` - Filter by socioeconomic status; takes SAM business-type codes (e.g. `OY` Black American Owned, `A6` SBA-certified 8(a), `A2` Woman Owned β€” see `GET /api/business_types/`), not set-aside codes; accepts pipe-separated values for OR semantics, e.g. `socioeconomic="OY|A2"` - `state` - Filter by state - `total_awards_obligated_gte` / `total_awards_obligated_lte` - Obligation amount range - `uei` - Filter by UEI - `zip_code` - Filter by ZIP code **Returns:** [PaginatedResponse](#paginatedresponse) with entity dictionaries **Example:** ```python entities = client.list_entities(search="Booz Allen", limit=20) for entity in entities.results: print(f"{entity['legal_business_name']}") print(f"UEI: {entity.get('uei', 'N/A')}") if entity.get('business_types'): print(f"Types: {', '.join(bt['code'] for bt in entity['business_types'])}") ``` ### get_entity() Get a specific entity by UEI or CAGE code. ```python entity = client.get_entity(key="ZQGGHJH74DW7", shape=None) ``` **Parameters:** - `key` (str): UEI or CAGE code - `shape` (str, optional): Fields to return **Returns:** Dictionary with entity details **Example:** ```python entity = client.get_entity("ZQGGHJH74DW7") print(f"Name: {entity['legal_business_name']}") print(f"UEI: {entity['uei']}") if entity.get('physical_address'): addr = entity['physical_address'] print(f"Location: {addr.get('city')}, {addr.get('state_code')}") ``` **Common Entity Fields:** - `uei` - Unique Entity Identifier - `cage_code` - CAGE code - `legal_business_name` - Official business name - `display_name` - Display name - `dba_name` - Doing Business As name - `business_types` - Array of business type codes - `primary_naics` - Primary NAICS code - `physical_address` - Physical address (nested) - `mailing_address` - Mailing address (nested) - `email_address` - Contact email - `entity_url` - Website --- ## Forecasts Contract forecast and planning information. ### list_forecasts() List contract forecasts. ```python forecasts = client.list_forecasts( page=1, limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) agency=None, award_date_after=None, award_date_before=None, fiscal_year=None, fiscal_year_gte=None, fiscal_year_lte=None, modified_after=None, modified_before=None, naics_code=None, naics_starts_with=None, search=None, source_system=None, status=None, ) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page - `shape` (str): Fields to return - `flat` (bool): Flatten nested objects - `flat_lists` (bool): Flatten arrays with indexed keys **Filter Parameters:** - `agency` - Filter by agency code - `award_date_after` / `award_date_before` - Expected award date range - `fiscal_year` - Exact fiscal year - `fiscal_year_gte` / `fiscal_year_lte` - Fiscal year range - `modified_after` / `modified_before` - Last-modified date range - `naics_code` - NAICS code (exact match) - `naics_starts_with` - NAICS code prefix - `search` - Full-text search - `source_system` - Filter by source system - `status` - Filter by status **Returns:** [PaginatedResponse](#paginatedresponse) with forecast dictionaries **Example:** ```python forecasts = client.list_forecasts(agency="GSA", fiscal_year=2025, limit=20) for forecast in forecasts.results: print(f"{forecast['title']}") print(f"Anticipated: {forecast.get('anticipated_award_date', 'TBD')}") print(f"Fiscal Year: {forecast.get('fiscal_year', 'N/A')}") ``` **Common Forecast Fields:** - `id` - Forecast identifier - `title` - Forecast title - `description` - Description - `anticipated_award_date` - Expected award date - `fiscal_year` - Fiscal year - `naics_code` - Industry code - `status` - Current status --- ## Opportunities Active contract opportunities and solicitations. ### list_opportunities() List contract opportunities/solicitations. ```python opportunities = client.list_opportunities( page=1, limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) active=None, agency=None, awarded=None, awardee_uei=None, first_notice_date_after=None, first_notice_date_before=None, last_notice_date_after=None, last_notice_date_before=None, naics=None, notice_type=None, place_of_performance=None, psc=None, response_deadline_after=None, response_deadline_before=None, search=None, set_aside=None, solicitation_number=None, ) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page - `shape` (str): Fields to return - `flat` (bool): Flatten nested objects - `flat_lists` (bool): Flatten arrays with indexed keys - `exact` (bool, keyword-only): Ask for an exact `count` (see [Exact counts](#exact-counts)). Requires Tango API 5.11.1 **Filter Parameters:** - `active` - Filter by active status (bool) - `agency` - Filter by agency code - `awarded` - Whether the opportunity has an award, either posted on it or linked to it (bool). Requires Tango API 5.5.0 - `awardee_uei` - Awardee UEI, case-insensitive; OR several with `|`. Requires Tango API 5.5.0 - `first_notice_date_after` / `first_notice_date_before` - First notice date range - `last_notice_date_after` / `last_notice_date_before` - Last notice date range - `naics` - NAICS code - `notice_type` - Filter by notice type - `place_of_performance` - Filter by place of performance - `psc` - PSC code - `response_deadline_after` / `response_deadline_before` - Response deadline range - `search` - Full-text search - `set_aside` - Set-aside type - `solicitation_number` - Solicitation number (exact match) **Returns:** [PaginatedResponse](#paginatedresponse) with opportunity dictionaries **Example:** ```python opportunities = client.list_opportunities(agency="DOD", active=True, limit=20) for opp in opportunities.results: print(f"{opp['title']}") print(f"Solicitation: {opp.get('solicitation_number', 'N/A')}") print(f"Deadline: {opp.get('response_deadline', 'Not specified')}") print(f"Active: {opp.get('active', False)}") ``` **Common Opportunity Fields:** - `opportunity_id` - Unique identifier - `title` - Opportunity title - `solicitation_number` - Solicitation number - `description` - Description - `response_deadline` - Response deadline - `active` - Is currently active - `naics_code` - Industry code - `psc_code` - Product/service code **Document roles β€” `attachments(doc_role, doc_role_alt)`:** On a **Pro plan or above**, each attachment can say what the document is for. `doc_role` is one of `requirement`, `instructions`, `pricing`, `terms`, `reference` or `unknown`; `doc_role_alt` is a runner-up role, and is null on nearly every attachment. ```python opp = client.get_opportunity( opportunity_id, shape="opportunity_id,title,attachments(name,url,doc_role,doc_role_alt)", ) for attachment in opp["attachments"]: print(attachment["name"], attachment.get("doc_role")) ``` - **You have to name them.** `attachments(*)` does not include either field, and no default shape does. - **The keys are absent, not null**, on an attachment Tango has not classified. Use `attachment.get("doc_role")`. - A Free-plan request that names them gets the response without them, plus an entry in `meta.upgrade_hints`. - There is no filter on document role. **Award fields:** Tango API 5.5.0 adds award information to opportunities. None of it is in the SDK's default shape, so name the fields you want. ```python opp = client.get_opportunity( opportunity_id, shape=( "opportunity_id,title,awarded,award_date,award_amount,awardee,awardee_uei," "award_count,solicitation_opportunity_id," "awards(opportunity_id,notice_id,award_number,award_date,award_amount,awardee,awardee_uei)" ), ) awarded = client.list_opportunities( awardee_uei="ABCDEF123456", shape="opportunity_id,title,award_date,awardee", ) ``` - `award_date`, `award_amount`, `awardee` and `awardee_uei` are filled only where SAM.gov posted an award notice; elsewhere they are null. `award_amount` is the text SAM.gov published, not a number. - SAM.gov often posts an award as its own opportunity. When that award notice references its solicitation, the award's `solicitation_opportunity_id` points back to the solicitation, and the solicitation's `awards(...)` lists up to ten of the most recent linked awards; `award_count` is the full count. An award notice that does not reference its solicitation is not linked. - `awarded` is true when the opportunity has an award of its own or has linked awards. - The `awarded` and `awardee_uei` filters search every opportunity, not just active ones, so pass `active=True` to narrow to open opportunities. - Notices accept `award_date`, `award_amount`, `awardee` and `awardee_uei` in `shape` too. **Attachment counts β€” `meta(attachments_count, files_count, links_count)`:** Tango API 5.9.0 splits an opportunity's attachment count by attachment `type`. A `file` is a document attached to the notice, and only files have extracted text; a `link` is a URL the notice lists. ```python opp = client.get_opportunity( opportunity_id, shape="opportunity_id,title,meta(attachments_count,files_count,links_count)", ) files = opp["meta"]["files_count"] if files is None: print("not counted yet") ``` - `meta.files_count` counts the files and `meta.links_count` counts the links. - `meta.attachments_count` still counts every attachment, links included. An attachment of any other type counts only there, so `files_count + links_count` need not equal it. - **`None` means unknown, not zero.** Both new fields are null until the record has been counted. - None of the three is in the SDK's default shape, so name the ones you want. - The opportunity embedded in a vehicle accepts them too: `opportunity(meta(files_count,links_count))`. --- ## Notices Contract award notices and modifications. ### list_notices() List contract notices. ```python notices = client.list_notices( page=1, limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) active=None, agency=None, naics=None, notice_type=None, posted_date_after=None, posted_date_before=None, psc=None, response_deadline_after=None, response_deadline_before=None, search=None, set_aside=None, solicitation_number=None, ) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page - `shape` (str): Fields to return - `flat` (bool): Flatten nested objects - `flat_lists` (bool): Flatten arrays with indexed keys - `exact` (bool, keyword-only): Ask for an exact `count` (see [Exact counts](#exact-counts)). Requires Tango API 5.11.1 **Filter Parameters:** - `active` - Filter by active status (bool) - `agency` - Filter by agency code - `naics` - NAICS code - `notice_type` - Filter by notice type - `posted_date_after` / `posted_date_before` - Posted date range - `psc` - PSC code - `response_deadline_after` / `response_deadline_before` - Response deadline range - `search` - Full-text search - `set_aside` - Set-aside type - `solicitation_number` - Solicitation number (exact match) **Returns:** [PaginatedResponse](#paginatedresponse) with notice dictionaries **Example:** ```python notices = client.list_notices(agency="GSA", notice_type="Presolicitation", limit=20) for notice in notices.results: print(f"{notice['title']}") print(f"Solicitation: {notice.get('solicitation_number', 'N/A')}") print(f"Posted: {notice.get('posted_date', 'N/A')}") ``` **Common Notice Fields:** - `notice_id` - Notice identifier - `title` - Notice title - `solicitation_number` - Solicitation number - `description` - Description - `posted_date` - Date posted - `naics_code` - Industry code **Attachment counts β€” `attachment_count`, `file_count`, `link_count`:** Tango API 5.9.0 splits a notice's attachment count by attachment `type`. A `file` is a document attached to the notice, and only files have extracted text; a `link` is a URL the notice lists. ```python notices = client.list_notices( agency="GSA", shape="notice_id,title,attachment_count,file_count,link_count", ) ``` - `file_count` counts the files and `link_count` counts the links. - `attachment_count` still counts every attachment, links included. An attachment of any other type counts only there, so `file_count + link_count` need not equal it. - **`None` means unknown, not zero.** Both new fields are null until the notice has been counted. - The API returns all three when no `shape` is sent, but the SDK's default `NOTICES_MINIMAL` shape does not name them, so ask for them. --- ## Grants Federal grant opportunities and assistance listings. ### list_grants() List grant opportunities. ```python grants = client.list_grants( page=1, limit=25, shape=None, flat=False, flat_lists=False, # Filter parameters (all optional) agency=None, applicant_types=None, cfda_number=None, funding_categories=None, funding_instruments=None, opportunity_number=None, posted_date_after=None, posted_date_before=None, response_date_after=None, response_date_before=None, search=None, status=None, ) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page (max 100) - `shape` (str): Response shape string - `flat` (bool): Flatten nested objects in shaped response - `flat_lists` (bool): Flatten arrays using indexed keys **Filter Parameters:** - `agency` - Filter by agency code - `applicant_types` - Filter by applicant type - `cfda_number` - Filter by CFDA number - `funding_categories` - Filter by funding category - `funding_instruments` - Filter by funding instrument - `opportunity_number` - Filter by opportunity number (exact match) - `posted_date_after` / `posted_date_before` - Posted date range - `response_date_after` / `response_date_before` - Response date range - `search` - Full-text search - `status` - Filter by status **Returns:** [PaginatedResponse](#paginatedresponse) with grant dictionaries **Example:** ```python grants = client.list_grants(agency="HHS", status="F", limit=20) # F = Forecasted, P = Posted for grant in grants.results: print(f"{grant['title']}") print(f"Opportunity: {grant.get('opportunity_number', 'N/A')}") print(f"Status: {grant.get('status', {}).get('description', 'N/A')}") ``` **Common Grant Fields:** - `grant_id` - Grant identifier - `opportunity_number` - Opportunity number - `title` - Grant title - `status` - Status information (nested object with code and description) - `agency_code` - Agency code - `description` - Description - `last_updated` - Last updated timestamp - `cfda_numbers` - CFDA numbers (list of objects with number and title) - `applicant_types` - Applicant types (list of objects with code and description) - `funding_categories` - Funding categories (list of objects with code and description) - `funding_instruments` - Funding instruments (list of objects with code and description) - `category` - Category (object with code and description) - `important_dates` - Important dates (list) - `attachments` - Attachments (list of objects) **Example with Expanded Fields:** ```python # Get grants with expanded status and CFDA numbers grants = client.list_grants( shape="grant_id,title,opportunity_number,status(*),cfda_numbers(number,title)", limit=10 ) for grant in grants.results: print(f"Grant: {grant['title']}") if grant.get('status'): print(f"Status: {grant['status'].get('description')}") if grant.get('cfda_numbers'): for cfda in grant['cfda_numbers']: print(f"CFDA: {cfda.get('number')} - {cfda.get('title')}") ``` --- ## GSA eLibrary Contracts GSA Schedule contracts from the GSA eLibrary. ### list_gsa_elibrary_contracts() List GSA eLibrary contracts with filtering and shaping. ```python contracts = client.list_gsa_elibrary_contracts( page=1, limit=25, shape=ShapeConfig.GSA_ELIBRARY_CONTRACTS_MINIMAL, # Filter parameters (all optional) contract_number=None, key=None, piid=None, schedule=None, search=None, sin=None, uei=None, ) ``` **Filter Parameters:** - `contract_number` - Filter by contract number - `key` - Filter by key - `piid` - Filter by PIID - `schedule` - Filter by GSA schedule - `search` - Full-text search - `sin` - Filter by SIN (Special Item Number) - `uei` - Filter by UEI **Returns:** [PaginatedResponse](#paginatedresponse) with GSA eLibrary contract dictionaries ### get_gsa_elibrary_contract() Get a single GSA eLibrary contract by UUID. ```python contract = client.get_gsa_elibrary_contract("UUID_HERE") ``` --- ## Protests Bid protest records from three venues: GAO, the U.S. Court of Federal Claims (COFC), and the SBA Office of Hearings and Appeals (SBA OHA). ### list_protests() List bid protests with filtering and shaping. ```python protests = client.list_protests( page=1, limit=25, shape=ShapeConfig.PROTESTS_MINIMAL, # Filter parameters (all optional) source_system=None, outcome=None, case_type=None, agency=None, case_number=None, solicitation_number=None, protester=None, filed_date_after=None, filed_date_before=None, decision_date_after=None, decision_date_before=None, naics_code=None, search=None, ) ``` **Filter Parameters:** - `source_system` - Filter by source system: `"gao"`, `"cofc"`, or `"sba_oha"` - `outcome` - Filter by outcome (e.g., `"Denied"`, `"Dismissed"`, `"Withdrawn"`, `"Sustained"`) - `case_type` - Filter by case type - `agency` - Filter by protested agency - `case_number` - Filter by base case number, matched case-insensitively (e.g., `"b-423274"` for GAO, `"26-1391"` for COFC, `"SIZ-6100"` for SBA OHA) - `solicitation_number` - Filter by solicitation number - `protester` - Search by protester name - `filed_date_after` / `filed_date_before` - Filed date range - `decision_date_after` / `decision_date_before` - Decision date range - `naics_code` - The NAICS code at issue in an SBA OHA size or NAICS appeal (e.g., `"541519"`). GAO and COFC protests carry no NAICS code, so this filter returns SBA OHA records only - `search` - Full-text search **Returns:** [PaginatedResponse](#paginatedresponse) with protest dictionaries **Example:** ```python protests = client.list_protests( source_system="gao", outcome="Sustained", filed_date_after="2024-01-01", shape="case_id,case_number,title,outcome,filed_date,dockets(docket_number,outcome)", limit=25, ) for protest in protests.results: print(f"{protest['case_number']}: {protest['title']} β€” {protest['outcome']}") ``` ### get_protest() Get a single protest by case_id (UUID). ```python protest = client.get_protest( "CASE_UUID", shape="case_id,case_number,title,source_system,outcome,filed_date,dockets(*)", ) ``` **Notes:** - Use `shape=...,dockets(...)` to include nested docket records. --- ## Contract Appeals Contract Disputes Act appeal decisions from the Civilian Board of Contract Appeals (CBCA) and the Armed Services Board of Contract Appeals (ASBCA). **These are not bid protests.** A protest challenges an award or a solicitation before performance; an appeal here challenges a contracting officer's final decision under an existing contract β€” a claim, a termination, a differing-site-conditions dispute. Protests live at [Protests](#protests) and share no identifiers with this resource. One row is one decision as the board's own listing publishes it, so several fields describe the listing rather than the dispute. `listed` goes false once the board's newest listing stops carrying the decision; the row is kept, never dropped. ### list_contract_appeals() List appeal decisions with filtering and shaping. ```python appeals = client.list_contract_appeals( page=1, limit=25, shape=ShapeConfig.CONTRACT_APPEALS_MINIMAL, # Filter parameters (all optional) board=None, docket=None, appellant=None, judge=None, decision_type=None, decision_date_after=None, decision_date_before=None, listed=None, document_id=None, search=None, ordering=None, ) ``` **Filter Parameters:** - `board` - `"cbca"` or `"asbca"`; OR both with `"cbca|asbca"` - `docket` - Exact docket match, e.g. `"3288-R"`, `"59116"` or `"7092-C(6682, 6765, 6767)"`. A leading `CBCA` / `ASBCA` and `No.` / `Nos.` are ignored, so a docket can be pasted as it is cited. Commas are part of a docket, never a separator; OR several with `|` - `appellant` - Case-insensitive substring match on the appellant's name (min 2 characters) - `judge` - Case-insensitive exact match on the judge as the listing names them - `decision_type` - CBCA only: `"Decision"`, `"Dismissal"`, `"Order"`, `"Full Board Order"`, or the listing's own text. ASBCA rows carry no type - `decision_date_after` / `decision_date_before` - Decision date range (`YYYY-MM-DD`) - `listed` - Whether the board's newest listing still carries the decision - `document_id` - The board's own document id - `search` - Ranked full-text search over the appellant and the full decision text (min 2 characters); wrap in double quotes for a phrase - `ordering` - `decision_date` (the default, as `-decision_date`), `appellant`, `first_listed_at` or `rank`. `rank` requires a non-empty `search` **Returns:** [PaginatedResponse](#paginatedresponse) with appeal-decision dictionaries **Example:** ```python appeals = client.list_contract_appeals( board="asbca", search="differing site conditions", decision_date_after="2025-01-01", ordering="rank", limit=25, ) for appeal in appeals.results: dockets = ", ".join(appeal["docket_numbers"]) print(f"{appeal['board'].upper()} {dockets}: {appeal['appellant']} ({appeal['decision_date']})") ``` ### get_contract_appeal() Get a single decision by `uuid`. ```python appeal = client.get_contract_appeal( "DECISION_UUID", shape=ShapeConfig.CONTRACT_APPEALS_COMPREHENSIVE, ) ``` **Notes:** - `docket_numbers` is a list β€” the dockets with the board prefix stripped (`3288-R`, `59116`), and a consolidated appeal carries several. `docket_raw` keeps the listing's own text, and `docket_source` says where the dockets came from. - **Reading `decision_text` requires an Enterprise plan, and below that tier the key is absent rather than null** β€” read it with `.get()`, not `[...]`. Neither default shape names it: the body runs to roughly 100K characters, so asking for it on every row is rarely what you want. - **Searching that text is free at every plan.** `search=` matches inside the decision body and returns no fragment of it, so buying the body does not change what you can find. --- ## Federal Register Federal Register documents β€” rules, proposed rules, notices and presidential documents published since 1994. A document is identified by `uuid`. `document_number` is not unique on its own: the Federal Register reused some numbers before 2016, so `document_number=` can return more than one document. ### list_federal_register_documents() List documents with filtering and shaping. ```python documents = client.list_federal_register_documents( page=1, limit=25, shape=ShapeConfig.FEDERAL_REGISTER_MINIMAL, # Filter parameters (all optional) search=None, document_number=None, type=None, agency=None, fr_agency=None, publication_date_after=None, publication_date_before=None, effective_on_after=None, effective_on_before=None, comments_close_on_after=None, comments_close_on_before=None, comments_open=None, cfr_title=None, cfr_part=None, significant=None, rin=None, executive_order_number=None, ordering=None, ) ``` **Filter Parameters:** - `search` - Ranked full-text search over the title, abstract and action; wrap in double quotes for a phrase - `document_number` - Exact FR document number, e.g. `"2016-31922"`; OR several with `|` - `type` - `"Notice"`, `"Rule"`, `"Proposed Rule"`, `"Presidential Document"`, `"Correction"`, `"Sunshine Act Document"` or `"Uncategorized Document"` (case-insensitive); OR several with `|`. An unknown type is an error, not an empty page. Documents published before 2008 are mostly `Uncategorized Document`, so a type filter undercounts that era - `agency` - A Tango agency name, abbreviation, code or organization key, e.g. `"EPA"`. Matches a document when any agency it lists falls within that organization, so a department includes its sub-agencies; OR several with `|` - `fr_agency` - The Federal Register's own agency slug, e.g. `"environmental-protection-agency"`; OR several with `|` - `publication_date_after` / `publication_date_before` - Publication date range (`YYYY-MM-DD`) - `effective_on_after` / `effective_on_before` - Effective date range (`YYYY-MM-DD`) - `comments_close_on_after` / `comments_close_on_before` - Comment-deadline range (`YYYY-MM-DD`) - `comments_open` - `True` for documents whose comment period closes today or later, `False` for those already closed; documents with no comment deadline match neither - `cfr_title` - A CFR title number, e.g. `"40"` - `cfr_part` - A CFR part number, e.g. `"52"`. Requires `cfr_title`, and both must match the same CFR reference, so `cfr_title="40", cfr_part="52"` finds 40 CFR 52 - `significant` - Significant under Executive Order 12866 - `rin` - A Regulation Identifier Number, e.g. `"2060-AV16"`; OR several with `|` - `executive_order_number` - Exact executive order number - `ordering` - `publication_date` (the default, as `-publication_date`), `effective_on`, `comments_close_on`, `document_number` or `rank`. `rank` requires a non-empty `search` **Returns:** [PaginatedResponse](#paginatedresponse) with document dictionaries **Example:** ```python documents = client.list_federal_register_documents( type="Proposed Rule", comments_open=True, agency="EPA", limit=25, ) for doc in documents.results: print(f"{doc['document_number']} ({doc['publication_date']}): {doc['title']}") print(f" comments close {doc['comments_close_on']}") ``` ### get_federal_register_document() Get a single document by `uuid`. To look one up by its document number, use `list_federal_register_documents(document_number=...)`. ```python document = client.get_federal_register_document( "DOCUMENT_UUID", shape=ShapeConfig.FEDERAL_REGISTER_COMPREHENSIVE, ) ``` **Notes:** - `agencies`, `cfr_references`, `dockets` and `topics` are the Federal Register's own structures, served as published. `agencies` carries Federal Register agency slugs, not Tango organization keys. - `full_text`, the document's plain text, is available on this method only and only when named in `shape` (e.g. `shape="uuid,title,full_text"`). It can run to several MB, so neither default shape includes it. --- ## State & Local (SLED) State, local and education procurement β€” solicitations that never appear on SAM.gov because they were never federal. **Beta**: coverage is partial and grows one jurisdiction at a time. This data does not join to the federal data. There is no UEI, no PIID, no agency-hierarchy key and no NAICS/PSC crosswalk; `organization(*)` here is three strings, not the federal 7-key office payload. ### list_sled_opportunities() List SLED solicitations with filtering and shaping. ```python solicitations = client.list_sled_opportunities( page=1, limit=25, shape=ShapeConfig.SLED_OPPORTUNITIES_MINIMAL, # Filter parameters (all optional) state=None, jurisdiction=None, status=None, active=None, agency=None, solicitation_number=None, solicitation_type=None, has_documents=None, revision_kind=None, naics=None, nigp=None, unspsc=None, category=None, category_code=None, posted_after=None, posted_before=None, response_deadline_after=None, response_deadline_before=None, first_seen_after=None, first_seen_before=None, change_seen_after=None, modified_after=None, modified_before=None, search=None, ordering=None, ) ``` **Two defaults worth knowing before your first call:** - **Passing neither `status` nor `active` returns open solicitations only.** Only about a fifth of the corpus is open, and a portal drops a closed solicitation rather than restating it, so the API defaults the list to `status=open`. Pass an explicit `status` to page the whole corpus. `status="unknown"` (standing rosters, dateless RFIs) is hidden by that default β€” reach it with `status="open|unknown"`. `get_sled_opportunity()` returns the solicitation whatever its status. - **`status` is Tango's answer, not the portal's.** It is derived from the portal's word, the deadline and the clock, and refreshed every fifteen minutes. The portal's own word is served as `source_status` and is frozen at last capture β€” most of what it calls open already has a passed deadline. Never filter liveness on it. **Filter Parameters:** - `state` - Two-letter state or territory code. Multi-value: `"TX|OK"` - `jurisdiction` - `"state"`, `"local"`, `"education"`, or `"unknown"` for aggregator rows that cannot tell state from local - `status` - `"open"`, `"closed"`, `"awarded"`, `"cancelled"`, `"unknown"` - `active` - Sugar for federal-shaped callers: `True` is `status="open"`; `False` is its complement, so it includes `unknown` - `agency` - Substring match on the buyer's published text (min 2 characters); no code resolution behind it - `solicitation_number` - The number a human would quote; null on roughly a third of the corpus - `solicitation_type` - `"rfp"`, `"ifb"`, `"rfq"`, `"rfi"`, `"itb"`, `"sole_source"`, `"grant"`, `"other"`. `"null"` (portal states no type) is a distinct answer from `"other"` - `has_documents` - Whether the solicitation advertises at least one document - `revision_kind` - Kind of the most recent substantive revision - `naics` / `nigp` / `unspsc` / `category` - Exact match within one category scheme. **`naics` is thin on purpose**: scheme tagging is mid-migration, so only a small share of entries are tagged NAICS - `category_code` - Match a code under ANY scheme, including the untagged pre-migration strings. The escape hatch when a scheme-specific filter returns less than expected - `posted_after` / `posted_before` - Posted-date range - `response_deadline_after` / `response_deadline_before` - Deadline range - `first_seen_after` / `first_seen_before` - When Tango first observed it. The polling primitive - `change_seen_after` - When Tango *observed* the last substantive change. A scrape date, not an amendment date - `modified_after` / `modified_before` - When the Tango row last changed - `platform` / `native_id` / `external_id` - Support filters for reproducing a record with us. Not in any response shape and not stable values - `search` - Ranked full-text search over title, agency, identifiers, category labels and description, widened by the solicitations whose *attachment text* matched (min 2 characters) - `ordering` - `rank`, `response_deadline`, `posted_date`, `first_seen_at`, `last_seen_at`, `last_change_seen_at`, `modified`. `rank` requires a non-empty `search` **Returns:** [PaginatedResponse](#paginatedresponse) with solicitation dictionaries **Example:** ```python # Open Texas solicitations closing this month, newest first page = client.list_sled_opportunities( state="TX", response_deadline_before="2026-10-01", ordering="response_deadline", limit=25, ) for row in page.results: print(f"{row['state']} {row.get('solicitation_number') or 'β€”'}: {row['title']}") # Full-text search puts the matching passage on each row that matched on its body hits = client.list_sled_opportunities( search="environmental mitigation", shape="opportunity_id,title,state,snippet,response_deadline", ) ``` `snippet` is present only under `search=`, and only on rows that matched on their description β€” a title-or-agency match honestly carries none. Attachment matching contributes ids only: a caller learns *that* a document matched, never what it said. ### get_sled_opportunity() Get a single solicitation by `opportunity_id`, whatever its status. ```python row = client.get_sled_opportunity( "OPPORTUNITY_UUID", shape="opportunity_id,title,status,attachments(*),revisions(*)", ) ``` **Notes:** - `meta.attachment_count` can be **lower** than `len(row["attachments"])`. Some portals auto-generate a cover sheet alongside the real documents; it is listed and flagged `is_generated_summary`, but excluded from the count and from `has_documents`. The count answers "does this hold its solicitation package"; the array answers "what files exist". - `size_bytes` and `char_count` only mean something as a pair β€” 3 MB that yielded no characters is a scan awaiting OCR. - `raw(*)` needs a Small plan or above, and is explicitly unstable: its shape varies by portal platform. - `delisted_at` is when a portal dropped the solicitation from its listing before its deadline, and is what `status_reason="delisted"` means. It is null when the solicitation was never delisted or has been seen again since. - `meta.jurisdiction_declared` says whether the source stated the jurisdiction level itself. `False` means Tango classified it from the issuer's name, which is the common case on a state's central portal. **Reading a document body β€” `attachments(extracted_text)`:** ```python row = client.get_sled_opportunity( opportunity_id, shape="opportunity_id,attachments(name,size_bytes,extracted_text)", ) ``` Needs a **Small plan or above**, and Tango API 4.25.1 or later (`client.get_version()` reports what you are calling). Three rules: - **You have to name it.** `attachments(*)` does not carry the body, and neither default shape names it β€” the API only resolves it for a caller who asked, so a default would make every detail fetch pay for a document nobody wanted to read. - **The key is absent, not null**, whenever the text is not being served to you: below Small (where it is withheld and named in `meta.upgrade_hints`), on a contested document, or where the text cannot be resolved. Use `attachment.get("extracted_text")`. - **A contested document never returns text**, at any plan β€” its stored bytes disagree with what the record advertised, so its text is not reliably that record's. Searching document text and reading it are separate things. `search=` matches inside attachment text on **every plan** and returns no fragment of it; `extracted_text` is a per-record read on Small and above. Buying the body does not change search. ### list_sled_opportunity_revisions() List one solicitation's observed revision history. ```python revisions = client.list_sled_opportunity_revisions( "OPPORTUNITY_UUID", kind=None, source_declared=None, observed_after=None, observed_before=None, ) ``` **Notes:** - `observed_at` is the scrape that saw the change, not the date the agency made it. No state portal emits amendment notices, so `kind` is Tango's inference from the diff on about 95% of revisions, resolution is that state's crawl cadence, and history starts when Tango began reading the jurisdiction. - Unlike the `revisions(*)` expand, this route serves `enrichment` rows β€” Tango's own detail fetch filling in coverage rather than an agency amendment. Pass `kind="enrichment"` for only those. - `changes` (the per-field before and after) needs a Small plan; it is left out of the default shape for that reason. `changed_fields` names what moved at every plan. ### get_sled_coverage() Get the per-state coverage rollup. Takes no parameters; not shaped or paginated. ```python coverage = client.get_sled_coverage() print(coverage["totals"]) for row in coverage["states"]: print(row["state"], row["total_count"], row["by_status"], row["last_change_observed_at"]) ``` **Call this before treating a per-state count as market size.** A thin result for a state is at least as likely to be a portal Tango does not read as a quiet market, and that is the ambiguity this endpoint exists to resolve. Every state row carries all five status buckets whether or not they have rows, so a total and two buckets never invite subtraction. ### list_sled_forecasts() List planned state procurements. ```python forecasts = client.list_sled_forecasts( state=None, agency=None, procurement_category=None, procurement_method=None, contract_number=None, incumbent_name=None, advertisement_after=None, advertisement_before=None, first_seen_after=None, first_seen_before=None, modified_after=None, modified_before=None, search=None, ordering=None, ) ``` **Notes:** - **Forecasts carry no liveness at all** β€” no deadline to have passed, so there is no `status` field, no `active` filter, and no open-only default. Currency is the caller's call from `estimated_advertisement_date`. - `estimated_advertisement_date` is the **start of the published quarter**, not a posting date. `estimated_advertisement_raw` keeps the portal's own words (`"Q3 (Jan.-March 2027)"`), and a large share of rows publish no quarter at all. - `estimated_value(min,max,raw)` is parsed from a free-text award band at serve time. **A band naming one number is a floor, so `max` is `None`** β€” never read a missing `max` as an unbounded ceiling. `raw` is always there to check the parse against. - `incumbent_name` is published text, not a resolved Tango entity. - `ordering`: `rank`, `estimated_advertisement_date`, `first_seen_at`, `last_seen_at`, `modified`. ### get_sled_forecast() ```python forecast = client.get_sled_forecast("FORECAST_UUID") ``` --- ## GSA eBuy GSA eBuy requests for quotes, proposals and information (RFQs, RFPs, RFIs), keyed by `rfq_id`. **Access is scoped to your account.** You see only requests posted under the GSA schedule contracts linked to your account, and the endpoints require the Pro tier or above (below it they return 403). With no linked contract, `list_ebuy_requests()` returns an empty page rather than an error, and `get_ebuy_request()` raises `TangoNotFoundError` for a request outside your scope, the same as for an id that does not exist. Use `get_ebuy_access()` to tell "no access" from "no matches". ### list_ebuy_requests() List requests with filtering and shaping. ```python requests = client.list_ebuy_requests( page=1, limit=25, shape=ShapeConfig.EBUY_REQUESTS_MINIMAL, # Filter parameters (all optional) search=None, rfq_id=None, reference_number=None, request_type=None, status=None, sin=None, schedule=None, buyer_agency=None, agency=None, contract_number=None, issue_date_after=None, issue_date_before=None, close_date_after=None, close_date_before=None, ordering=None, ) ``` **Filter Parameters:** - `search` - Full-text search over the title, description, reference number, request id and attachment text. Results rank by relevance unless `ordering` is given - `rfq_id` - Exact request id, e.g. `"RFQ1835158"` - `reference_number` - The buyer's own solicitation number; dashes are ignored - `request_type` - `"RFQ"`, `"RFP"` or `"RFI"` - `status` - `"Open"` or `"Cancelled"`, as last seen (see the note below) - `sin` - Special Item Number, e.g. `"54151S"` - `schedule` - GSA schedule - `buyer_agency` - The buyer agency as eBuy names it (free text) - `agency` - A Tango agency name, abbreviation, code or organization key, e.g. `"GSA"`. Matches the whole organization subtree, so a department includes its sub-agencies. Requires Tango API 5.3.0 - `contract_number` - Narrow to requests posted under one of your own linked contracts. A contract not linked to your account returns an empty page, not an error - `issue_date_after` / `issue_date_before` - Issue date range (`YYYY-MM-DD`, inclusive) - `close_date_after` / `close_date_before` - Close date range (`YYYY-MM-DD`, inclusive) - `ordering` - `issue_date` (the default, as `-issue_date`), `close_date`, `last_seen` or `modified`; prefix `-` for descending String filters accept several values joined with `|` (OR). **Returns:** [PaginatedResponse](#paginatedresponse) with request dictionaries **Example:** ```python requests = client.list_ebuy_requests(status="Open", sin="54151S", ordering="close_date") for req in requests.results: print(f"{req['rfq_id']} closes {req['close_date']}: {req['title']}") print(f" last seen {req['last_seen']}") ``` **Notes:** - **`status` is frozen at the last state the request was seen in.** Only currently-active requests are carried, so a request that closes stops appearing rather than getting a final row. `Open` means "open the last time it was seen", not "open now"; read `last_seen` for staleness. - The contract number a request was posted under is never returned in any payload. - `buyer_agency_code` and some other buyer and contact fields are sparse on older requests. ### get_ebuy_request() Get a single request by `rfq_id`. ```python request = client.get_ebuy_request( "RFQ1835158", shape=ShapeConfig.EBUY_REQUESTS_COMPREHENSIVE, ) for attachment in request["attachments"]: print(attachment["doc_seq_num"], attachment["doc_name"], attachment["is_link"]) ``` The default shape returns every field plus two expands: `organization` (the buyer office, with the same seven keys as other resources' `organization` expand) and `attachments`. Each attachment carries `doc_seq_num`, `doc_name`, `doc_type`, `doc_path`, `is_link` and `doc_session_date`. `is_link=True` means `doc_path` is an outbound URL with no stored document behind it. `amendments`, `line_items` and `addresses` are lists of objects, served as eBuy publishes them. **Reading a document's text β€” `attachments(extracted_text)`** (Tango API 5.9.1): ```python request = client.get_ebuy_request( "RFQ1835158", shape="rfq_id,attachments(doc_seq_num,doc_name,extracted_text)", ) for attachment in request["attachments"]: text = attachment.get("extracted_text") if text: print(attachment["doc_name"], len(text)) ``` - `extracted_text` is the text extracted from the attachment's document. - **It is returned only when you name it.** The default shape does not include it, and neither does `attachments(*)`. - **The API omits the key, rather than sending null**, for an attachment with no text: an external link, an empty scan, or a document that has not been extracted yet. The SDK's shaped result reads an omitted key as `None`, so treat `None` as "no text", not as an error. ### get_ebuy_attachment_url() Get a short-lived download URL for one stored attachment. ```python url = client.get_ebuy_attachment_url("RFQ1835158", doc_seq_num=1) ``` **Returns:** The signed URL the API redirects to, as a string. The SDK reads the redirect without following it, so no document is downloaded. The URL expires after about five minutes: fetch it promptly, and call this again rather than storing it. **Raises:** - `TangoAttachmentLinkError` (a `TangoValidationError`) - The entry is an external link (`is_link`), not a stored document. The link is on `error.url` - `TangoNotFoundError` - The request is unknown or outside your scope, the attachment does not exist, or its document has not been captured yet ### get_ebuy_access() Check whether your account can read eBuy requests. ```python access = client.get_ebuy_access() if not access.enabled: print(access.reason) # "tier_required" or "no_contract_grant" print(access.contracts) # your own linked contracts, sorted ``` **Returns:** `EbuyAccess` with `enabled` (bool), `reason` (`"tier_required"`, `"no_contract_grant"` or `None`; `tier_required` wins when both apply) and `contracts` (list of str). --- ## Budget Federal account Γ— fiscal year budget rollups, covering the full budget lifecycle (requested β†’ enacted β†’ apportioned β†’ obligated β†’ outlayed), pre-computed ratios and trends, the contract / assistance / unlinked breakdown, and request-vs-actual spend. ### list_budget_accounts() List budget accounts. One row per `(federal_account_symbol, fiscal_year)`. ```python accounts = client.list_budget_accounts( page=1, limit=25, shape=ShapeConfig.BUDGET_ACCOUNTS_MINIMAL, # Filter parameters (all optional) federal_account_symbol=None, fiscal_year=None, fiscal_year_gte=None, fiscal_year_lte=None, agency_code=None, bureau_name=None, account_title=None, bea_category=None, on_off_budget=None, subfunction_code=None, account_category=None, account_category_in=None, data_through_period=None, data_through_period_gte=None, data_through_period_lte=None, data_through_period_isnull=None, search=None, ordering=None, ) ``` **Filter Parameters:** - `federal_account_symbol` - Exact federal account symbol (e.g., `"097-0100"`) - `fiscal_year` - Fiscal year (exact) - `fiscal_year_gte` / `fiscal_year_lte` - Fiscal year range - `agency_code` - Agency code (exact) - `bureau_name` - Bureau name (exact) - `account_title` - Account title (case-insensitive substring match) - `bea_category` - BEA category (exact) - `on_off_budget` - On/off budget flag (exact) - `subfunction_code` - Subfunction code (exact) - `account_category` - Account category (exact): `budgetary` or `credit_financing` today; treat it as an open string - `account_category_in` - Comma-separated account categories to match any of (e.g. `"budgetary,credit_financing"`) - `data_through_period` - File A period (1-12) the account-year's figures run through (exact); below 12 the year is partial - `data_through_period_gte` / `data_through_period_lte` - `data_through_period` range - `data_through_period_isnull` - `True` for accounts with no File A data, `False` for accounts with it - `search` - Full-text search over `account_title`, `agency_name`, `bureau_name` - `ordering` - Sort field; prefix with `-` for descending. The default is the latest fiscal year first, then largest `enacted_ba` first, with accounts that have no `enacted_ba` last. **Source anomalies:** the default shape includes `account_category` and `source_anomalies`. `source_anomalies` is a list of problems found in the source data behind the account, and `[]` when there are none. Each element is a `BudgetAccountSourceAnomaly` (a `TypedDict`; every key is optional and may be `None`, so read keys with `.get()`): `code`, `field`, `bound_field`, `action` (`capped` or `flagged`), `reported_value`, `served_value`, `likely_cause`, `affected_fields`, `message`, and `source` (`dataset`, `fiscal_year`, and `rows` of `fiscal_period`, `piid`, `parent_piid`, `tas`, `reporting_agency_id`, `transaction_obligated_amount`, `file_c_source`). Today `code` is one of `contract_exceeds_obligations`, `assistance_exceeds_obligations` or `contract_without_obligations`; treat it as an open string. There is no filter on anomalies. ```python for acct in client.list_budget_accounts(fiscal_year=2025).results: for anomaly in acct["source_anomalies"] or []: print(acct["federal_account_symbol"], anomaly.get("code"), anomaly.get("action")) ``` **Returns:** [PaginatedResponse](#paginatedresponse) of `BudgetAccount` records (see [ShapeConfig](#shapeconfig-predefined-shapes) for the default shape). **Example:** ```python accounts = client.list_budget_accounts( agency_code="097", fiscal_year_gte=2023, ordering="-enacted_ba", limit=10, ) for acct in accounts.results: print(f"{acct.federal_account_symbol} FY{acct.fiscal_year}: " f"enacted ${acct.enacted_ba:,}") ``` ### get_budget_account() Get a single budget account by id. ```python account = client.get_budget_account( 12345, shape=ShapeConfig.BUDGET_ACCOUNTS_MINIMAL, ) ``` **Parameters:** - `id` (str | int): Budget account id. - `shape` (str, optional): Response shape. Defaults to `BUDGET_ACCOUNTS_MINIMAL`. - `flat` / `flat_lists` / `joiner`: See [Shaping Guide](shapes.md). **Returns:** A `BudgetAccount` record. ### get_budget_account_quarters() Get quarterly TAS-grain flow for a budget account. FY21+ only. ```python quarters = client.get_budget_account_quarters(12345, limit=25) ``` **Parameters:** - `id` (str | int): Budget account id. - `tas` (str, optional): Narrow to a single Treasury Account Symbol. - `limit` (int): Results per page (max 100). **Returns:** [PaginatedResponse](#paginatedresponse) of quarterly flow records. ### get_budget_account_recipients() Get funding-office Γ— recipient contract-flow detail for a budget account. ```python recipients = client.get_budget_account_recipients( 12345, funding_organization_id=None, limit=25, ) ``` **Parameters:** - `id` (str | int): Budget account id. - `funding_organization_id` (str, optional): Narrow to a single funding office (Organization UUID). - `limit` (int): Results per page (max 100). **Returns:** [PaginatedResponse](#paginatedresponse) of `(funding_office, recipient)` flow records. --- ## Business Types Business type classifications. ### list_business_types() List available business type codes. ```python business_types = client.list_business_types(page=1, limit=25) ``` **Parameters:** - `page` (int): Page number - `limit` (int): Results per page **Returns:** [PaginatedResponse](#paginatedresponse) with business type dictionaries **Example:** ```python business_types = client.list_business_types(limit=50) for biz_type in business_types.results: print(f"{biz_type.code}: {biz_type.name}") ``` **Business Type Fields:** - `code` - Business type code - `name` - Business type name - `description` - Description --- ## NAICS NAICS (North American Industry Classification System) codes. ### list_naics() List NAICS codes with optional filtering. ```python naics = client.list_naics( page=1, limit=25, # Filter parameters (all optional) employee_limit=None, employee_limit_gte=None, employee_limit_lte=None, revenue_limit=None, revenue_limit_gte=None, revenue_limit_lte=None, search=None, ) ``` **Filter Parameters:** - `employee_limit` - Exact employee size standard - `employee_limit_gte` / `employee_limit_lte` - Employee limit range - `revenue_limit` - Exact revenue size standard - `revenue_limit_gte` / `revenue_limit_lte` - Revenue limit range - `search` - Full-text search (code or description) **Returns:** [PaginatedResponse](#paginatedresponse) with NAICS dictionaries **Example:** ```python naics = client.list_naics(search="software", limit=10) for code in naics.results: print(f"{code['code']}: {code['description']}") ``` ### get_naics() Get a single NAICS code by code string. ```python naics = client.get_naics("541511") ``` **Returns:** Dictionary with NAICS code details. ### get_naics_metrics() Get computed metrics for a NAICS code. ```python metrics = client.get_naics_metrics(code="541511", months=12, period_grouping="month") ``` --- ## PSC Product and Service Codes. ### list_psc() ```python psc = client.list_psc(page=1, limit=25) ``` ### get_psc() ```python psc = client.get_psc("D302") ``` ### get_psc_metrics() ```python metrics = client.get_psc_metrics(code="D302", months=12, period_grouping="month") ``` **Parameters:** - `code` (str): PSC code. Required. - `months` (int): Trailing window in months. - `period_grouping` (str): `"month"`, `"quarter"` or `"year"`. - `group_by` (`"agency"` | `"department"` | list | None): Split each period by funding organization. `agency` is an L2 short code such as `"2100"`; `department` is the CGAC code as an int, e.g. `97` for DoD. - `fiscal_year` (bool): Bucket by federal fiscal year instead of calendar periods. Default `False`. - `rolling` (bool): Add rolling averages. The API skips them, with a `warning`, when `group_by` is set. Default `False`. `get_naics_metrics()` and `get_entity_metrics()` take the same options. --- ## MAS SINs GSA Multiple Award Schedule Special Item Numbers. ### list_mas_sins() ```python sins = client.list_mas_sins(page=1, limit=25) ``` ### get_mas_sin() ```python sin = client.get_mas_sin("54151S") ``` --- ## Assistance Listings (CFDA) Catalog of Federal Domestic Assistance listings. ### list_assistance_listings() ```python listings = client.list_assistance_listings(page=1, limit=25) ``` ### get_assistance_listing() ```python listing = client.get_assistance_listing("10.310") ``` --- ## Departments ### list_departments() ```python depts = client.list_departments(page=1, limit=25) ``` ### get_department() ```python dept = client.get_department("097") ``` --- ## Business Types (by code) ### get_business_type() Get a single business type by code. ```python bt = client.get_business_type("A6") ``` --- ## IT Dashboard Federal IT investments from the OMB IT Dashboard. ### list_itdashboard_investments() ```python investments = client.list_itdashboard_investments( page=1, limit=25, search=None, agency_code=None, type_of_investment=None, # Pro/Business+ tier-gated filters available ) ``` **Notes:** - Filter tier-gating: `search` is free; `agency_code`, `type_of_investment` require Pro; `agency_name`, `cio_rating`, `performance_risk` require Business+. - Shape defaults to `ShapeConfig.ITDASHBOARD_INVESTMENTS_MINIMAL`. ### get_itdashboard_investment() ```python investment = client.get_itdashboard_investment("023-000001234") ``` --- ## Entity Sub-resources ### list_entity_contracts() ```python contracts = client.list_entity_contracts("ABCDEF123456", limit=25) ``` ### list_entity_idvs() ```python idvs = client.list_entity_idvs("ABCDEF123456", limit=25) ``` ### list_entity_otas() / list_entity_otidvs() ```python otas = client.list_entity_otas("ABCDEF123456", limit=25) otidvs = client.list_entity_otidvs("ABCDEF123456", limit=25) ``` ### list_entity_subawards() ```python subawards = client.list_entity_subawards("ABCDEF123456", limit=25) ``` ### list_entity_lcats() ```python lcats = client.list_entity_lcats("ABCDEF123456", limit=25) ``` ### get_entity_metrics() ```python metrics = client.get_entity_metrics("ABCDEF123456", months=12, period_grouping="month") # five fiscal years of obligations, split by funding department by_dept = client.get_entity_metrics( "ABCDEF123456", months=60, period_grouping="year", group_by="department", fiscal_year=True ) ``` Takes the same `group_by`, `fiscal_year` and `rolling` options as [`get_psc_metrics()`](#get_psc_metrics). ### get_entity_budget_flows() Get budget flows for an entity (`/api/entities/{uei}/budget-flows/`) β€” the federal accounts that funded contracts and assistance awarded to this entity. ```python flows = client.get_entity_budget_flows("ABCDEF123456", fiscal_year=2024) for row in flows.results: print(row["federal_account_symbol"], row["contract_obligated"]) # next page more = client.get_entity_budget_flows("ABCDEF123456", page=2, fiscal_year=2024) ``` **Parameters:** - `uei` (str): Entity UEI. Required. - `page` (int): Page number. Default 1. - `limit` (int): Results per page. Default 25, max 100. - `fiscal_year` (int | None): Optional fiscal year filter. **Returns:** `PaginatedResponse[dict[str, Any]]` β€” standard `count / next / previous / results`. Result rows are raw dicts from the API (not shape-controlled). --- ## IDV LCATs ### list_idv_lcats() ```python lcats = client.list_idv_lcats("GS-00F-XXXX", limit=25) ``` --- ## Agency Sub-resources ### list_agency_awarding_contracts() List contracts where the agency is the awarding agency. ```python contracts = client.list_agency_awarding_contracts("4700", limit=25) ``` ### list_agency_funding_contracts() List contracts where the agency is the funding agency. ```python contracts = client.list_agency_funding_contracts("4700", limit=25) ``` --- ## Resolve / Validate ### resolve() Resolve a free-text name to ranked entity or organization candidates. ```python result = client.resolve( name="Lockheed Martin", target_type="entity", # or "organization" state="MD", # optional city="Bethesda", # optional context="defense contractor", # optional ) for candidate in result.candidates: print(candidate.identifier, candidate.display_name) ``` **Notes:** - Free-tier: up to 3 candidates with `identifier` and `display_name`. - Pro+: up to 5 candidates with additional `match_tier` field. ### validate() Validate the format of a PIID, solicitation number, or UEI. ```python result = client.validate(identifier_type="uei", value="ABCDEF123456") # identifier_type is one of: "piid", "solicitation", "uei" ``` **Note:** The parameter is named `identifier_type` (not `type`) to avoid shadowing the Python builtin. --- ## Opportunities (attachments) ### search_opportunity_attachments() Semantic search over opportunity attachments. `q` is required. ```python results = client.search_opportunity_attachments( q="cybersecurity", top_k=10, include_extracted_text=False, ) ``` **Parameters:** - `q` (str): Search query (required) - `top_k` (int, optional): Number of top results to return - `include_extracted_text` (bool, optional): Whether to include extracted text from attachments in results **Returns:** dict with search results --- ## Webhook Alerts The Alerts API is the canonical (and only) write surface for webhook subscriptions. Every alert maps to one of the five `alerts.*.match` event types and delivers when its saved-search filters match new or modified records. ### list_webhook_alerts() ```python alerts = client.list_webhook_alerts(page=1, page_size=25) ``` ### get_webhook_alert() ```python alert = client.get_webhook_alert("ALERT_UUID") ``` ### create_webhook_alert() ```python alert = client.create_webhook_alert( name="New cloud IT contracts", query_type="contract", filters={"naics": "541511"}, ) ``` For multi-endpoint accounts, pin the delivery target with `endpoint=`: ```python alert = client.create_webhook_alert( name="New cloud IT contracts", query_type="contract", filters={"naics": "541511"}, endpoint="ENDPOINT_UUID", ) ``` **Notes:** - `name` and `query_type` are required. `query_type` is **singular** (e.g. `"contract"`, not `"contracts"`). - `endpoint=` is optional and only required when the account has multiple webhook endpoints; for single-endpoint accounts the server auto-resolves. ### update_webhook_alert() ```python alert = client.update_webhook_alert("ALERT_UUID", name="Updated name") ``` ### delete_webhook_alert() ```python client.delete_webhook_alert("ALERT_UUID") ``` --- ## Utility ### get_version() ```python version = client.get_version() ``` ### list_api_keys() ```python keys = client.list_api_keys() ``` --- ## Webhooks Webhook APIs let **Large / Enterprise** users manage delivery endpoints and discover the supported event-type catalog. Filter subscriptions (alerts) live in the [Webhook Alerts](#webhook-alerts) section above. > **For testing, signing, and a CLI tool**, see [`docs/WEBHOOKS.md`](webhooks.md). This section covers SDK method signatures only. ### list_webhook_event_types() Discover supported `event_type` values. ```python info = client.list_webhook_event_types() print(info.event_types[0].event_type) ``` ### list_webhook_endpoints() List your webhook endpoint(s). ```python endpoints = client.list_webhook_endpoints(page=1, limit=25) ``` ### get_webhook_endpoint() ```python endpoint = client.get_webhook_endpoint("ENDPOINT_UUID") ``` ### create_webhook_endpoint() / update_webhook_endpoint() / delete_webhook_endpoint() In production, MakeGov provisions the initial endpoint for you. These are most useful for dev/self-service. ```python endpoint = client.create_webhook_endpoint("https://example.com/tango/webhooks") endpoint = client.update_webhook_endpoint(endpoint.id, is_active=False) client.delete_webhook_endpoint(endpoint.id) ``` ### test_webhook_delivery() Send an immediate test webhook to your configured endpoint. ```python result = client.test_webhook_delivery() print(result.success, result.status_code) ``` ### get_webhook_sample_payload() Fetch Tango-shaped sample deliveries. ```python sample = client.get_webhook_sample_payload(event_type="alerts.contract.match") print(sample["event_type"]) ``` ### Deliveries / redelivery The API does not currently expose a public `/api/webhooks/deliveries/` or redelivery endpoint. Use: - `test_webhook_delivery()` for connectivity checks - `get_webhook_sample_payload()` for building handlers ### Receiving webhooks (signature verification) Every delivery includes an HMAC signature header: - `X-Tango-Signature: sha256=` Compute the digest over the **raw request body bytes** using your shared secret. The SDK ships a stdlib-only verifier that mirrors the Tango server's signing scheme byte-for-byte. Use it instead of hand-rolling β€” it's importable from a default install (no extras needed): ```python from tango.webhooks import verify_signature if not verify_signature(raw_body, secret, request.headers.get("X-Tango-Signature")): return 401 ``` `verify_signature` returns `False` for missing/empty/malformed headers β€” it never raises. Comparison is constant-time. --- ## Webhook tooling (`tango.webhooks`) The `tango.webhooks` subpackage adds testing and developer-tooling primitives on top of the API methods above. Signing helpers ship with the default install; the receiver and CLI ship with `pip install 'tango-python[webhooks]'`. See [`docs/WEBHOOKS.md`](webhooks.md) for usage guides; this section is the import-level reference. ### Signing (default install) ```python from tango.webhooks import ( verify_signature, # (body: bytes, secret: str, header: str | None) -> bool generate_signature, # (body: bytes, secret: str) -> str ("sha256=" wire form) parse_signature_header, # (header: str | None) -> str | None (strips "sha256=") SIGNATURE_HEADER, # "X-Tango-Signature" SIGNATURE_PREFIX, # "sha256=" ) ``` ### `WebhookReceiver` (with `[webhooks]` extra) A stdlib-based local HTTP receiver, useful in tests and during local development. ```python from tango import WebhookReceiver, Delivery # exported from top-level tango package # or: from tango.webhooks.receiver import WebhookReceiver, Delivery with WebhookReceiver(secret="dev").run() as rx: # ... cause something to POST to rx.url ... deliveries: list[Delivery] = rx.deliveries ``` Constructor (all keyword arguments): | Arg | Default | Meaning | |---|---|---| | `secret` | `""` | Shared secret. Empty means signatures are not verified. | | `path` | `/tango/webhooks` | URL path to accept POSTs on. | | `host` | `127.0.0.1` | Bind address. | | `port` | `0` | TCP port. `0` = OS picks a free port. | | `forward_to` | `None` | Optional URL to mirror each delivery to. | | `max_history` | `256` | Cap on the in-memory `deliveries` deque. | | `on_delivery` | `None` | Callback fired for every delivery (verified or not). | | `require_signature` | `None` | Override default (require iff `secret` is set). | Each `Delivery` is a dataclass: `received_at`, `path`, `signature_header`, `body_bytes`, `body_json`, `verified`, `remote_addr`, `forward_status`, `forward_error`. ### `simulate.sign` and `simulate.deliver` ```python from tango.webhooks import sign, SignedRequest from tango.webhooks import simulate # Offline β€” produce the signed wire form without POSTing: signed: SignedRequest = sign({"events": [{"event_type": "..."}]}, secret="s") signed.body # bytes you would put on the wire signed.signature # bare lowercase hex signed.headers # {"Content-Type": ..., "X-Tango-Signature": "sha256=..."} # With delivery β€” sign and POST to a target URL: result = simulate.deliver(target_url="http://localhost:8011/tango/webhooks", payload={...}, secret="s") result.status_code # status from the receiver result.signature # bare hex result.sent_bytes # exact bytes that were POSTed result.response_body # body the receiver returned ``` `simulate.deliver` and `simulate.sign` accept payloads as `dict`, `list`, `str`, or raw `bytes`. Dicts/lists are serialized via `json.dumps(..., sort_keys=True, separators=(",", ":"))` so signatures are reproducible across runs. ### CLI entry point The `tango[webhooks]` extra also installs a `tango` console script. See [`docs/WEBHOOKS.md` Β§ CLI reference](webhooks.md#cli-reference) for the full command list. --- ## Response Objects ### PaginatedResponse All list methods return a `PaginatedResponse` object with the following attributes: ```python response = client.list_contracts(limit=25) # Attributes response.count # Total number of results response.next # URL to next page (or None) response.previous # URL to previous page (or None) response.results # List of result dictionaries response.count_type # "exact" or "approximate" (the API's X-Results-CountType header) ``` #### Exact counts `list_opportunities()`, `list_notices()`, `list_contracts()` and `list_idvs()` report an estimated `count` (`count_type == "approximate"`) once a filtered result set passes 10,000 matches, and that estimate is only a lower bound. Pass `exact=True` to get an exact count instead; it is more expensive for the API, so ask only when you need the total. On opportunities and notices it requires Tango API 5.11.1. ```python page = client.list_opportunities(agency="DOD", limit=1, exact=True) print(page.count, page.count_type) # count_type is "exact" ``` **Example:** ```python contracts = client.list_contracts(limit=25) print(f"Total contracts: {contracts.count:,}") print(f"Results on this page: {len(contracts.results)}") # Iterate through results for contract in contracts.results: print(contract['piid']) # Check for more pages (contracts use keyset pagination via cursor) if contracts.next: next_page = client.list_contracts(cursor=contracts.cursor, limit=25) ``` **Pagination Example (contracts use keyset pagination, not page numbers):** ```python cursor = None all_results = [] page_num = 1 while True: response = client.list_contracts(cursor=cursor, limit=100) all_results.extend(response.results) print(f"Batch {page_num}: {len(response.results)} results") if not response.next: break cursor = response.cursor # use cursor for next page page_num += 1 print(f"Total collected: {len(all_results)} results") ``` --- ## ShapeConfig (predefined shapes) The SDK provides predefined shape strings as constants on `ShapeConfig`. Use them as the `shape` argument for list/get methods when you want a consistent, validated set of fields without building a custom shape string. ```python from tango import TangoClient, ShapeConfig client = TangoClient() # List methods default to the minimal shape when shape is omitted contracts = client.list_contracts(limit=10) # uses CONTRACTS_MINIMAL # Or pass the constant explicitly contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10) entity = client.get_entity("UEI_KEY", shape=ShapeConfig.ENTITIES_COMPREHENSIVE) ``` **Available constants (by resource):** | Constant | Used by | Description | |----------|---------|-------------| | `CONTRACTS_MINIMAL` | `list_contracts` | key, piid, award_date, recipient(display_name), description, total_contract_value | | `ENTITIES_MINIMAL` | `list_entities` | uei, legal_business_name, cage_code, business_types | | `ENTITIES_COMPREHENSIVE` | `get_entity` | Full entity profile (addresses, naics, psc, obligations, etc.) | | `FORECASTS_MINIMAL` | `list_forecasts` | id, title, anticipated_award_date, fiscal_year, naics_code, status | | `OPPORTUNITIES_MINIMAL` | `list_opportunities` | opportunity_id, title, solicitation_number, response_deadline, active | | `NOTICES_MINIMAL` | `list_notices` | notice_id, title, solicitation_number, posted_date | | `GRANTS_MINIMAL` | `list_grants` | grant_id, opportunity_number, title, status(*), agency_code | | `IDVS_MINIMAL` | `list_idvs`, `list_vehicle_awardees` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated, idv_type | | `IDVS_COMPREHENSIVE` | `get_idv` | Full IDV with offices, place_of_performance, competition, transactions, etc. | | `VEHICLES_MINIMAL` | `list_vehicles` | uuid, solicitation_identifier, is_synthetic_solicitation, program_acronym, organization_id, organization, vehicle_type, description, idv_count, holder_count, order_winner_count, awardee_count, order_count, total_obligated, vehicle_obligations, vehicle_contracts_value, latest_award_date, solicitation_title, solicitation_date | | `VEHICLES_COMPREHENSIVE` | `get_vehicle` | Full vehicle with competition_details, fiscal_year, set_aside, etc. | | `VEHICLE_AWARDEES_MINIMAL` | `list_vehicle_awardees` | uuid, key, piid, award_date, title, order_count, idv_obligations, idv_contracts_value, recipient(display_name,uei) | | `ORGANIZATIONS_MINIMAL` | `list_organizations` | key, fh_key, name, level, type, short_name | | `OTAS_MINIMAL` | `list_otas` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated | | `OTIDVS_MINIMAL` | `list_otidvs` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated, idv_type | | `SUBAWARDS_MINIMAL` | `list_subawards` | award_key, prime_recipient(uei,display_name), subaward_recipient(uei,display_name) | | `GSA_ELIBRARY_CONTRACTS_MINIMAL` | `list_gsa_elibrary_contracts` | uuid, contract_number, schedule, recipient(display_name,uei), idv(key,award_date) | | `PROTESTS_MINIMAL` | `list_protests` | case_id, case_number, title, source_system, outcome, filed_date | | `CONTRACT_APPEALS_MINIMAL` | `list_contract_appeals` | uuid, board, docket_numbers, decision_date, appellant, judge, decision_type, url | | `CONTRACT_APPEALS_COMPREHENSIVE` | `get_contract_appeal` | The list fields plus docket_raw, docket_source, decision_date_repaired, decision_type_raw, listing_year, first_listed_at, listed, text_status, text_char_count (omits `decision_text`, which needs an Enterprise plan) | | `FEDERAL_REGISTER_MINIMAL` | `list_federal_register_documents` | uuid, document_number, publication_date, type, subtype, title, abstract, action, agencies, cfr_references, citation, significant, comments_close_on, effective_on, html_url, pdf_url | | `FEDERAL_REGISTER_COMPREHENSIVE` | `get_federal_register_document` | The list fields plus dates, signing_date, start_page, end_page, volume, docket_ids, dockets, regulation_id_numbers, topics, correction_of, corrections, executive_order_number, presidential_document_number, proclamation_number, comment_url, regulations_dot_gov_url, raw_text_url, body_html_url (omits `full_text`) | | `EBUY_REQUESTS_MINIMAL` | `list_ebuy_requests` | rfq_id, request_type, title, schedule, sin, status, buyer_name, buyer_agency, buyer_agency_code, reference_number, issue_date, close_date, attachment_count, link_count, last_seen | | `EBUY_REQUESTS_COMPREHENSIVE` | `get_ebuy_request` | Every field, plus the `organization` and `attachments` expands (without `extracted_text`, which must be named) | | `BUDGET_ACCOUNTS_MINIMAL` | `list_budget_accounts`, `get_budget_account` | id, federal_account_symbol, fiscal_year, data_through_period, agency_code/name, bureau_name, account_title, bea_category, on_off_budget, subfunction_code, account_category, lifecycle (requested/enacted/apportioned/obligated/outlayed/unobligated), contract & assistance rollups, key ratios, next-year growth, source_anomalies | | `VEHICLE_ORDERS_MINIMAL` | `list_vehicle_orders` | key, piid, award_date, recipient(display_name,uei), total_contract_value, obligated | | `ITDASHBOARD_INVESTMENTS_MINIMAL` | `list_itdashboard_investments` | Minimal IT Dashboard investment fields | | `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` | `get_itdashboard_investment` | Full investment fields: uii, agency_code, agency_name, bureau_code, bureau_name, investment_title, type_of_investment, part_of_it_portfolio, updated_time, url | | `SLED_OPPORTUNITIES_MINIMAL` | `list_sled_opportunities` | opportunity_id, solicitation_number, solicitation_type, title, state, jurisdiction, agency, status, status_reason, delisted_at, posted_date, response_deadline, source_url, has_documents, first_seen_at, last_change_seen_at (no `description` β€” detail-only on the API) | | `SLED_OPPORTUNITIES_COMPREHENSIVE` | `get_sled_opportunity` | Full solicitation with description, the raw portal status, the delisting timestamp, both deadlines, bid opening, category codes, and organization / contact / meta / attachments / revisions | | `SLED_REVISIONS_MINIMAL` | `list_sled_opportunity_revisions` | observed_at, sequence, kind, changed_fields, source_declared (omits `changes`, which needs a Small plan) | | `SLED_FORECASTS_MINIMAL` | `list_sled_forecasts` | forecast_id, state, agency, title, estimated_advertisement_date, estimated_advertisement_raw, procurement_category, procurement_method, contract_number, incumbent_name, source_url, estimated_value(*) | | `SLED_FORECASTS_COMPREHENSIVE` | `get_sled_forecast` | Full forecast with description, contract_term, mbe_dbe_goal, delivery_location, and organization / contact / estimated_value | All predefined shapes are validated at SDK release time (see [Developer Guide](https://github.com/makegov/tango-python/blob/main/docs/DEVELOPERS.md#sdk-conformance-maintainers)). For custom shapes, see the [Shaping Guide](shapes.md). --- ## Error Handling The SDK provides specific exception types for different error scenarios. ### Exception Types ```python from tango import ( TangoAPIError, # Base exception TangoAuthError, # 401 - Authentication failed TangoNotFoundError, # 404 - Resource not found TangoValidationError, # 400 - Invalid parameters TangoRateLimitError, # 429 - Rate limit exceeded ) ``` ### TangoAPIError Base exception for all Tango API errors. **Attributes:** - `message` (str): Error message - `status_code` (int, optional): HTTP status code ### TangoAuthError Raised when authentication fails (401). **Common causes:** - Invalid API key - Expired API key - Missing API key for protected endpoint ### TangoNotFoundError Raised when a resource is not found (404). **Common causes:** - Invalid agency code - Invalid entity key - Resource doesn't exist ### TangoValidationError Raised when request parameters are invalid (400). **Attributes:** - `message` (str): Error message - `status_code` (int): HTTP status code (400) - `details` (dict): Validation error details from API ### TangoRateLimitError Raised when rate limit is exceeded (429). ### Error Handling Examples ```python from tango import ( TangoClient, TangoAPIError, TangoAuthError, TangoNotFoundError, TangoValidationError, TangoRateLimitError, ) client = TangoClient(api_key="your-api-key") # Handle specific errors try: agency = client.get_agency("INVALID") except TangoNotFoundError: print("Agency not found") except TangoAuthError: print("Authentication failed - check your API key") except TangoAPIError as e: print(f"API error: {e.message}") # Handle validation errors with details try: contracts = client.list_contracts( award_date_gte="invalid-date" ) except TangoValidationError as e: print(f"Validation error: {e.message}") if e.response_data: print(f"Details: {e.response_data}") # Handle rate limiting try: contracts = client.list_contracts(limit=100) except TangoRateLimitError: print("Rate limit exceeded - please wait before retrying") # Implement exponential backoff here # Catch-all for any API error try: result = client.list_contracts() except TangoAPIError as e: print(f"An error occurred: {e.message}") if e.status_code: print(f"Status code: {e.status_code}") ``` --- ## Best Practices ### 1. Use Response Shaping Always use response shaping for better performance: ```python # ❌ Without shaping (slow, large response) contracts = client.list_contracts(limit=100) # βœ… With shaping (fast, small response) contracts = client.list_contracts( shape="key,piid,recipient(display_name),total_contract_value", limit=100 ) ``` See [Shaping Guide](shapes.md) for details. ### 2. Handle Pagination Properly Don't fetch all results at once - paginate responsibly: ```python # βœ… Good - process batch by batch (contracts use keyset/cursor pagination) cursor = None batches = 0 while batches < 10: # Limit to 10 batches contracts = client.list_contracts(cursor=cursor, limit=100) process_contracts(contracts.results) if not contracts.next: break cursor = contracts.cursor batches += 1 ``` ### 3. Use Filters to Narrow Results Filter on the server side instead of client side: ```python # ❌ Don't do this all_contracts = client.list_contracts(limit=1000) gsa_contracts = [c for c in all_contracts.results if c['awarding_agency']['code'] == 'GSA'] # βœ… Do this instead gsa_contracts = client.list_contracts( awarding_agency="GSA", limit=100 ) ``` ### 4. Handle Errors Gracefully Always wrap API calls in try-except blocks: ```python try: contracts = client.list_contracts(limit=10) except TangoAPIError as e: logger.error(f"Failed to fetch contracts: {e.message}") # Handle error appropriately ``` ### 5. Use Environment Variables for API Keys Never hardcode API keys: ```python # ❌ Don't do this client = TangoClient(api_key="sk_live_abc123...") # βœ… Do this instead import os client = TangoClient(api_key=os.getenv("TANGO_API_KEY")) # Or just use the default (loads from environment) client = TangoClient() ``` --- ## Additional Resources - [Shaping Guide](shapes.md) - Response shaping syntax, examples, and field reference - [Developer Guide](https://github.com/makegov/tango-python/blob/main/docs/DEVELOPERS.md) - Dynamic models, predefined shapes, and SDK conformance (maintainers) - [Quick Start](https://github.com/makegov/tango-python/blob/main/docs/quick_start.ipynb) - Interactive notebook with examples - [GitHub Repository](https://github.com/makegov/tango-python) - Source code and examples - [Tango API Documentation](https://tango.makegov.com/docs) - Full API documentation --- # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [1.21.0] - 2026-10-29 ### Added - **`fsc` on `list_dibbs_rfqs()`, `list_dibbs_rfps()` and `list_dibbs_awards()` (Tango API 5.13.0).** Filters DIBBS records by Federal Supply Class, the first four digits of the NSN (`fsc="6515"`); OR several with `|` (`"6515|6530"`). Each value must be exactly four digits, or the API returns 400. Optional and keyword-style, appended after the existing parameters, so existing calls send the same request. ## [1.20.0] - 2026-10-24 ### Added - **`exact=True` on `list_opportunities()`, `list_notices()`, `list_contracts()` and `list_idvs()`.** Past 10,000 matches these endpoints report an estimated `count` that is only a lower bound; `exact=True` sends `?exact=true` for a real count (opportunities and notices require Tango API 5.11.1). Keyword-only and off by default, so existing calls send the same request. ## [1.19.0] - 2026-10-21 ### Added - **`group_by`, `fiscal_year` and `rolling` on `get_entity_metrics()`, `get_naics_metrics()` and `get_psc_metrics()`.** The metrics endpoints have always accepted these query parameters, but the SDK built only the path, so callers could not split obligations by funding `"agency"` or `"department"` or bucket them by federal fiscal year. Each is optional; existing calls send the same request as before. ## [1.18.2] - 2026-10-19 ### Fixed - **`TangoRateLimitError.limit_type` no longer reports a daily lockout as `burst`.** It matched "minute" anywhere in the API's detail, and a daily 429 reads `Rate limit exceeded for daily. Please try again in 16 hours, 58 minutes.`, so callers were told to retry a burst limit they could not clear until midnight UTC. It now reads the rate's name from `exceeded for ` and checks for daily first. ## [1.18.1] - 2026-10-19 ### Fixed - **API errors now carry the server's reason.** A 403 or other non-2xx response the SDK had no dedicated exception for raised `TangoAPIError("API request failed with status 403")` and threw the response body away, so a caller refused for a G2X-only shape field or a plan-gated filter couldn't tell why. The message now ends with the API's own explanation (`API request failed with status 403: G2X shape fields are not allowed for your account.`), and the parsed body is on `response_data`. Non-JSON bodies, such as a proxy's 502 page, keep the old message. ## [1.18.0] - 2026-10-19 ### Added - **`obligations_by_fiscal_year(fiscal_year, obligated)` shape expand on contracts, IDVs, OTAs and OTIDVs** (Tango API 5.11.0). Returns the award's obligations per federal fiscal year, each rounded to cents, with `fiscal_year` parsed as `int` and `obligated` as `Decimal`. It is always `None` on IDVs and OTIDVs, whose transactions report a running lifetime total. - **`attachments(extraction_status)` shape field on opportunities and notices** (Tango API 5.11.0). Reports `pending`, `extracting`, `completed`, `failed` or `unsupported` for each attachment, so you can tell why `extracted_text` is missing. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.11.0) and regenerated the shape overlay. - Documented that `recipient_uei` on `list_contracts()` (and `uei` on the IDV, OTA and OTIDV lists) accepts several UEIs joined by `|` (Tango API 5.11.0); the SDK already passed the value through unchanged. ## [1.17.0] - 2026-10-16 ### Added - **`commercial_item_acquisition_procedures` filter on `list_contracts()` and `list_idvs()`** (Tango API 5.10.0). Filters by the FPDS commercial item acquisition procedures code: `A` (commercial products/services), `B` (products or services pursuant to FAR 12.102(f)), `C` (services pursuant to FAR 12.102(g)), `D` (commercial procedures not used) or `E` (DoD Section 803 Commercial Solutions Opening). Codes are case-insensitive and pipe-separated for OR, e.g. `"A|E"`; an unknown or multi-character code matches nothing. The API does not offer it on OTAs or OTIDVs, so `list_otas()` and `list_otidvs()` do not take it. The field itself was already returned in responses. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.10.0). ## [1.16.0] - 2026-10-10 ### Added - **Extracted text on eBuy request attachments** (Tango API 5.9.1). `attachments(extracted_text)` on eBuy requests returns the text extracted from an attachment's document. It is returned only when named: the default `get_ebuy_request()` shape and `attachments(*)` leave it out. An attachment with no text (an external link, an empty scan, or a document not yet extracted) is sent by the API without the key rather than with a null; the SDK's shaped result reads that as `None`. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.9.1). ## [1.15.0] - 2026-10-06 ### Added - **`matched_by` on agency-filter diagnostics** (Tango API 5.9.0). Each entry of `PaginatedResponse.meta["resolved_filters"][]` that resolved now says how its token matched: `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match, worth checking against the resolved name). An entry that did not resolve has no `matched_by`. `meta` is passed through as the API sends it, so no code change was needed to receive the field; this release documents it and pins it with a test. `agency_warnings`, `unresolved_agency_tokens` and `resolved_agencies` are unchanged. - **File and link counts on opportunities and notices** (Tango API 5.9.0). An attachment's `type` is `file` (a document attached to the notice; only files have extracted text) or `link` (a URL the notice lists), and the new fields count each: `meta.files_count` and `meta.links_count` on opportunities, `file_count` and `link_count` on notices. The existing `meta.attachments_count` and `attachment_count` still count every attachment, links included, and an attachment of any other type counts only there, so files plus links need not equal the total. The new fields are `None` until a record has been counted, so treat `None` as unknown, not zero. All four are accepted in custom shapes, as is `opportunity(meta(files_count,links_count))` on vehicles; no default SDK shape names them. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.9.0) and regenerated `tango/shapes/generated_overlay.py`. ## [1.14.0] - 2026-10-02 ### Added - **`PaginatedResponse.count_type`**: `"exact"` or `"approximate"`, read from the API's `X-Results-CountType` header on every list method (`None` when the API doesn't send it). Past 1,000 matches the contract, IDV, opportunity and notice lists may return a query-planner estimate as `count`, which can be well off; this is how a caller tells the two apart. It is taken from each response itself, so concurrent calls on one client can't see each other's value the way `last_response_headers` can. ## [1.13.0] - 2026-10-02 ### Added - **`holder_count` and `order_winner_count` on vehicles** (Tango API 5.8.0). `holder_count` is the number of distinct companies holding one of the vehicle's IDVs, and `order_winner_count` is the number of distinct companies that have won a task order under it. Both are in the default `VEHICLES_MINIMAL` and `VEHICLES_COMPREHENSIVE` shapes and accepted in custom shapes. - **`data_through_period` on budget accounts** (Tango API 5.8.0). The File A period (1-12) an account-year's figures run through; below 12 the year is partial, and `None` means there is no File A data. It is in the default `BUDGET_ACCOUNTS_MINIMAL` shape and accepted in custom shapes. - **`list_budget_accounts(data_through_period=..., data_through_period_gte=..., data_through_period_lte=..., data_through_period_isnull=...)`** filters by that period, exactly, by range, or by whether it is set. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.8.0) and regenerated `tango/shapes/generated_overlay.py`. ### Deprecated - **`awardee_count` on vehicles.** It is the same value as `order_winner_count`; use that instead. The API removes it at its next major version, and the SDK's default vehicle shapes will drop it then. ## [1.12.0] - 2026-10-02 ### Added - **`account_category` and `source_anomalies` on budget accounts** (Tango API 5.7.0). Both are in the default `BUDGET_ACCOUNTS_MINIMAL` shape and accepted in custom shapes. `account_category` is `budgetary` or `credit_financing` today. `source_anomalies` lists the problems found in the source data behind an account, and is `[]` when there are none. Each element is typed as the new `BudgetAccountSourceAnomaly` `TypedDict` (with `BudgetAccountAnomalySource` and `BudgetAccountAnomalySourceRow` for its nested `source`), and every key is optional. Treat `account_category` and an anomaly's `code` as open strings, since new values may appear. - **`list_budget_accounts(account_category=..., account_category_in=...)`** filters by account category, exactly or against a comma-separated list. ### Changed - **`list_budget_accounts()` documents the API's default ordering**: the latest fiscal year first, then largest `enacted_ba` first, with accounts that have no `enacted_ba` last. - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.7.0) and regenerated `tango/shapes/generated_overlay.py`. ### Fixed - **`list_idvs()`, `list_idv_awards()`, `list_idv_child_idvs()` and `list_idv_transactions()` now return the API's pagination `cursor`.** They dropped it, so `response.cursor` was always `None` and a caller following the cursor stopped after the first page. ## [1.11.0] - 2026-09-29 ### Added - **Award fields on opportunities and notices** (Tango API 5.5.0) β€” new `awarded` / `awardee_uei` filters on `list_opportunities()`, plus award leaves and an `awards(...)` expand in the opportunity and notice shapes (see `docs/API_REFERENCE.md`). ## [1.10.0] - 2026-09-29 ### Added - **`list_sbir_topics(cycle_name=...)`** filters topics by their DSIP solicitation cycle (e.g. `DOD_SBIR_2026_P1_CBZ`), and `SbirTopic` gains a `cycle_name` field (Tango API 5.3.1). The vendored API contract is refreshed to 5.3.1. ## [1.9.0] - 2026-09-28 ### Added - **GSA eBuy requests** (Tango API 5.1.0). Four methods over the `/api/ebuy/` resource: `list_ebuy_requests()`, `get_ebuy_request()`, `get_ebuy_attachment_url()` and `get_ebuy_access()`, plus `EbuyRequest` / `EbuyAttachment` schemas, an `EbuyAccess` result type, and the `EBUY_REQUESTS_MINIMAL` / `EBUY_REQUESTS_COMPREHENSIVE` defaults. These are the RFQs, RFPs and RFIs posted to GSA eBuy. All fourteen of the API's filters are explicit named parameters, including `search` (which also matches attachment text), `reference_number`, `sin`, `agency` and `contract_number`. Access is scoped to your account: you see only requests posted under the GSA schedule contracts linked to it, and the endpoints require the Pro tier or above. With no linked contract, `list_ebuy_requests()` returns an empty page rather than an error, so `get_ebuy_access()` reports whether access is enabled, why not (`tier_required` or `no_contract_grant`), and which contracts are linked. `status` is frozen at the last state a request was seen in, because a request that closes stops appearing rather than getting a final row; read `last_seen` for staleness. `get_ebuy_attachment_url()` returns the short-lived signed URL the API redirects to without downloading the document, and raises the new `TangoAttachmentLinkError` (a `TangoValidationError`) with the link on `.url` when the entry is an external link rather than a stored document. The `agency` filter requires Tango API 5.3.0. - **`alerts.ebuy_request.match` is an alertable event type.** `create_webhook_alert(query_type="ebuy_request", ...)` works. ## [1.8.0] - 2026-09-28 ### Added - **Federal Register documents** (Tango API 5.3.0). Two methods over the new `/api/federal_register/` resource: `list_federal_register_documents()` and `get_federal_register_document()`, plus a `FederalRegisterDocument` schema and the `FEDERAL_REGISTER_MINIMAL` / `FEDERAL_REGISTER_COMPREHENSIVE` defaults. These are the rules, proposed rules, notices and presidential documents published in the Federal Register since 1994. All seventeen of the API's filters are explicit named parameters, including `comments_open`, `cfr_title` / `cfr_part`, `rin`, and both `agency` (a Tango organization, including its sub-agencies) and `fr_agency` (the Federal Register's own agency slug). `get_federal_register_document()` takes the document's `uuid`, not its `document_number`, because a document number is not unique on its own: the Federal Register reused some before 2016. Look a document up by number with `list_federal_register_documents(document_number=...)`. `full_text` is available on the detail method only when named in `shape`, and neither default shape includes it, since it can run to several MB. `ordering="rank"` requires a non-empty `search`, matching the API. - **`alerts.federal_register.match` is an alertable event type.** `create_webhook_alert(query_type="federal_register", ...)` works. - **`agency` filter on `list_budget_accounts()`, `list_exclusions()` and `list_itdashboard_investments()`** (Tango API 5.3.0). It takes a Tango agency name, abbreviation, code or organization key (e.g. `EPA`) and matches the whole organization subtree, so a department includes its sub-agencies; OR several with `|`. On exclusions it scopes by the excluding agency. On IT Dashboard it is available at every plan. - **The `organization` expand is accepted on budget accounts, exclusions, SBIR topics and SBIR solicitations**, along with the `organization_id` field on budget accounts and exclusions. `organization(...)` carries `agency_code`, `agency_name`, `department_code`, `department_name`, `office_code`, `office_name` and `organization_id`. The SDK rejected these shapes client-side before. The default shapes are unchanged. ### Fixed - **`list_itdashboard_investments()` documents the API's current filter tiers.** `agency_name` is available at every plan, not Business+ only. ## [1.7.0] - 2026-09-23 ### Added - **Contract Disputes Act appeals** (Tango API 4.26.0). Two methods over the new `/api/contract_appeals/` resource: `list_contract_appeals()` and `get_contract_appeal()`, plus a `ContractAppeal` schema and the `CONTRACT_APPEALS_MINIMAL` / `CONTRACT_APPEALS_COMPREHENSIVE` defaults. These are decisions of the Civilian Board of Contract Appeals (CBCA) and the Armed Services Board of Contract Appeals (ASBCA) β€” appeals of a contracting officer's final decision under an existing contract, which is a different dispute from a bid protest and shares no identifiers with `list_protests()`. All ten of the API's filters are explicit named parameters. Three behaviors are documented on the methods and the model, because each is otherwise a support question. **`decision_text` needs an Enterprise plan, and below that tier the key is absent rather than null** β€” read it with `.get()`. **Searching that text is free at every plan**: `search=` matches inside the decision body and returns no fragment of it, so buying the body does not change what you can find. And **`docket` accepts a docket as it is cited** β€” a leading `CBCA` / `ASBCA` and `No.` / `Nos.` are ignored, while commas stay part of a docket (`7092-C(6682, 6765, 6767)`) rather than separating two. Neither default shape names `decision_text`: the body runs to roughly 100K characters, so putting it in a default would make every fetch ask for something most callers cannot read. `ordering="rank"` requires a non-empty `search`, matching the API. - **`alerts.contract_appeal.match` is an alertable event type.** `create_webhook_alert(query_type="contract_appeal", ...)` works. That method's `query_type` docstring now names the full current set and points at `list_webhook_event_types()` as the authority, since a list written into a docstring can only go stale. ### Fixed - **`attachments(doc_role, doc_role_alt)` on opportunities and notices no longer raises `ShapeValidationError`.** The Tango API serves both fields on a Pro plan or above, but the SDK rejected them client-side after the request had already been made. `doc_role` says what an attachment is for (`requirement`, `instructions`, `pricing`, `terms`, `reference` or `unknown`) and `doc_role_alt` is a runner-up role that is usually null. Both must be named in the shape, since `attachments(*)` does not include them, and an attachment that has not been classified omits both keys, so read them with `.get()`. - **The shape overlay generator no longer lets one resource's view of a model hide fields from another's.** An opportunity is reachable both from `list_opportunities()` and as the `opportunity` expand on vehicles, and the vehicles embed exposes fewer attachment fields. Whichever tree was generated last replaced the other, so the opportunity schema lost fields its own endpoint serves. The generator now adds the missing fields instead of replacing the schema, and keeps every existing field's type as it was. - **SLED solicitations accept `delisted_at` and `meta(jurisdiction_declared)`.** Both were rejected client-side even though the API returns them. `delisted_at` is when a portal dropped a solicitation from its listing before its deadline, which is what `status_reason="delisted"` means. `meta.jurisdiction_declared` says whether the source stated the jurisdiction level itself or Tango classified it from the issuer's name. `delisted_at` is now in both `SLED_OPPORTUNITIES_MINIMAL` and `SLED_OPPORTUNITIES_COMPREHENSIVE`, matching the API's own list default. ### Changed - **SLED response values now carry the types the API returns.** The SDK's SLED schema had guessed several types from field names. `posted_date`, `response_deadline`, `response_deadline_original` and `bid_opening_date` on `SledOpportunity` now parse to timezone-aware `datetime` values (before, `posted_date` and `bid_opening_date` were truncated to a `date` and the two deadlines stayed strings), as does `estimated_advertisement_date` on `SledForecast`. `estimated_value(min, max)` on forecasts now parses to `Decimal`. `category_codes` is typed as a list of `{scheme, code}` objects, `attachments` and `revisions` as lists, `meta(last_change_source_declared)` and `revisions(source_declared)` as booleans, and `attachments(size_bytes, pages)` and `revisions(sequence)` as integers. If you compared any of the date fields as strings, compare them as `datetime` values instead. - Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.1.0) and regenerated `tango/shapes/generated_overlay.py`. The one resource the SDK does not wrap yet, `ebuy/requests`, is recorded in `contracts/shape_coverage_baseline.json` as a known gap. - The `ContractAppeal` shape schema is hand-curated in `tango/shapes/explicit_schemas.py` rather than left to the generated overlay. The generator falls back to name heuristics for a resource the live-API type probe has not sampled yet, and those heuristics get four of this resource's fields wrong: `docket_numbers` is a list, `listed` and `decision_date_repaired` are booleans, and `listing_year` is an integer. ### Documentation - `list_protests()` and `docs/API_REFERENCE.md` now describe all three protest venues: GAO, the U.S. Court of Federal Claims (COFC) and the SBA Office of Hearings and Appeals (SBA OHA). `naics_code` is documented as the NAICS code at issue in an SBA OHA size or NAICS appeal, which GAO and COFC protests never carry, rather than the solicitation's code. `case_number` examples now cover each venue's format, and `naics_code` is listed among the filter parameters. - `docs/API_REFERENCE.md` documents the document-role fields on opportunity and notice attachments, and `delisted_at` and `meta.jurisdiction_declared` on SLED solicitations. - New **Contract Appeals** section in `docs/API_REFERENCE.md`, leading with what separates an appeal from a protest, plus the two new `ShapeConfig` constants in the shapes table. - Added `alerts.contract_appeal.match` to the event-type listing in `docs/WEBHOOKS.md`. ## [1.6.0] - 2026-09-10 ### Added - **`attachments(extracted_text)` β€” SLED document bodies on the Small plan and above** (Tango API 4.25.1). Re-vendored the contract and regenerated the shape overlay, so `shape="...,attachments(name,extracted_text)"` now validates instead of being rejected client-side. Three properties are documented on the model and in `docs/API_REFERENCE.md`, because each is otherwise a support question: the leaf must be **named** (neither `SLED_OPPORTUNITIES_MINIMAL` nor `SLED_OPPORTUNITIES_COMPREHENSIVE` includes it, and `attachments(*)` does not carry it, because the API only resolves the body for a caller who asked); the **key is absent rather than null** when the text is not being served, so read it with `.get()`; and a **contested document never returns text at any plan**. Searching document text stays ungated on every plan and returns no fragment of it β€” buying the body does not change search. - **State, local and education (SLED) procurement** (Tango API 4.25.0). Six methods over the new `/api/sled/` namespace: `list_sled_opportunities()`, `get_sled_opportunity()`, `list_sled_opportunity_revisions()`, `get_sled_coverage()`, `list_sled_forecasts()`, `get_sled_forecast()`, plus `SledOpportunity` / `SledOpportunityRevision` / `SledForecast` schemas and five `ShapeConfig` defaults. Every one of the API's 27 solicitation filters and 13 forecast filters is an explicit named parameter. Four behaviors are documented on the methods themselves because each misleads a caller who assumes federal semantics. **Passing neither `status` nor `active` returns open solicitations only** β€” that default is the API's, and the SDK deliberately does not synthesize a `status` param, since doing so would make `active=False` unreachable (pinned by a test). **`status` is Tango-derived and refreshed every fifteen minutes**; the portal's own word is served as `source_status`, is frozen at last capture, and is not a liveness filter. **Category scheme tagging is mid-migration**, so `naics=` matches only the small tagged share and `category_code=` is the escape hatch. And **`meta.attachment_count` can be lower than `len(attachments)`**, because an auto-generated portal cover sheet is listed and flagged `is_generated_summary` but excluded from the count. `SLED_REVISIONS_MINIMAL` omits `changes` on purpose: the per-field before/after needs a Small plan, so naming it by default would 403 a Free caller. `changed_fields` is in the default and available at every plan. - **`previous_uii` on `list_itdashboard_investments()`.** The Tango API has accepted this filter for a while β€” it resolves a retired UII forward to whatever superseded it β€” and the SDK never picked it up, so it was a silent no-op for anyone who passed it through. Ungated, unlike its analytical neighbours on that endpoint. Found by the SDK's own filter-conformance check, not by SLED work. ### Changed - Re-vendored `contracts/filter_shape_contract.json` (schema_version 2, 48 resources) and regenerated `tango/shapes/generated_overlay.py` from it β€” 535 fields across 33 containers, 84 nested schemas. Besides the SLED expands this closes three entity gaps the older contract could not see: `relationships(confidence, verification_method)` and the whole `workforce(*)` expand were reachable on the API and rejected client-side by the SDK's schema. - Baselined 14 reverse-shape-coverage gaps in `contracts/shape_coverage_baseline.json`. All 14 are nested sub-resource routes the newer contract publishes for the first time (`entities_contracts`, `idvs_awards`, `vehicles_orders`, and similar); none is SLED, and none is a regression β€” they are pre-existing SDK gaps that only became visible with the re-vendored contract. The gate reports 0 new drift. ### Documentation - New **State & Local (SLED)** section in `docs/API_REFERENCE.md` covering all six methods, both defaults that surprise people, and the five new `ShapeConfig` constants. - Corrected `docs/WEBHOOKS.md`. It stated flatly that "nothing fires when a record merely lapses"; that is now false for exactly one query type. `alerts.sled_opportunity.match` **does** fire on a closing, because SLED liveness is a stored column a fifteen-minute sweep writes rather than a query-time derivation. Also documented that there is no `sled_forecast` query type and that SLED revisions and attachments are not separately alertable. ## [1.5.1] - 2026-08-10 ### Documentation - Documented (and pinned with tests) the OR syntax `list_entities(socioeconomic=...)` has always supported: pipe-separated values match entities holding any of the listed designations, e.g. `socioeconomic="OY|A2"`; values are SAM business-type codes (e.g. `OY` Black American Owned, `A6` SBA-certified 8(a), `A2` Woman Owned), not set-aside codes. ### Changed - The sdist no longer packages `.github/workflows`, so CI-only commits stop changing the sdist hash. ([#58](https://github.com/makegov/tango-python/pull/58)) ## [1.5.0] - 2026-08-04 ### Added - **`relationships(type, source)` on entities.** Tango API 4.20.0 added two keys to each entry in the entity `relationships` expand: `type`, the stable relationship-type code (`prime_sub`, `parent_subsidiary`, `ultimate_parent`, `predecessor`), and `source`, where the tie came from (`sam`, `subawards`). Both are shape-selectable, so `shape="uei,relationships(type,source,uei)"` now resolves against the SDK's schema. Re-vendored the contract and regenerated the shape overlay; the coverage gate reports 0 gaps. - `PaginatedResponse.meta` now carries the response-level `meta` block the API returns, with three accessors over it: `unresolved_agency_tokens` (agency tokens that matched nothing, per filter), `resolved_agencies` (the organization each token *did* match), and `agency_warnings` (the API's human-readable notes). Agency values resolve fuzzily, so a token can match an organization the caller did not intend and quietly scope the query to that subtree β€” and a token that resolves to nothing was previously dropped with no signal at all. Both cases were indistinguishable from "no such records exist". The API now reports both; until now the SDK read the envelope key-by-key and dropped `meta` on the floor, so SDK users were the one group that could not see it. `resolved_agencies` is the accessor that matters for the wrong-organization case: nothing is dropped there, so an unresolved-token check cannot detect it. All accessors return empty rather than raising when `meta` is absent (most responses) or malformed. - A fully-unresolvable agency filter now raises `TangoValidationError` naming the offending value instead of returning an empty page. This needed no SDK change β€” the existing 400 handler already reads the API's `error` key β€” but it is new behavior for callers of `list_subawards()`, `list_opportunities()`, `list_notices()`, and `list_vehicles()`, which previously returned an empty result set. Contracts, IDVs, OTAs, and OTIDVs already behaved this way. ### Changed - **The `relation` value vocabulary changed upstream β€” match on `type` instead.** In Tango API 4.20.0 the `relation` label stopped collapsing to `affiliate` for subcontracting and corporate-succession ties and now names the partner's role: `subcontractor` / `prime`, `predecessor` / `successor`, and `descendant` (rather than `child`) on the far side of an ultimate-parent tie. `affiliate` survives only as a fallback for a type the API doesn't recognize. This affects the large majority of relationship entries. No SDK code change is required β€” `relation` was and remains a `str`. But if you have application code branching on the string `affiliate`, switch it to `type`, which is stable and won't churn again. See the [entities data dictionary](https://docs.makegov.com/data-dictionary/entities/#relationships) for the full vocabulary table. ### Notes - `PaginatedResponse.page_metadata` is documented as always `None`: the API has never emitted a `page_metadata` key, so the field has only ever read a value that does not exist. It is retained so existing attribute access keeps working. Use `meta`. ## [1.4.0] - 2026-07-20 ### Added - `list_protests()` now accepts `naics_code`, filtering protests by the solicitation's NAICS code. The API has always supported it (verified live: 15,027 protests unfiltered, 12 for `541519`, 2 for `336411`), but `protests` was absent from the conformance checker's resource-to-method map, so the gap was never reported. - `list_psc()` now accepts `has_awards`, restricting results to codes with contract award history (2,526 PSC codes unfiltered, 2,243 with awards). `False` is sent explicitly rather than dropped, since the API distinguishes the two. This param has always worked but was invisible to the contract until [makegov/tango#2948](https://github.com/makegov/tango/pull/2948) added the `view_handled_params` declaration for params a viewset reads straight from `query_params`. That PR also fixed a truthiness bug where `has_awards=false` filtered identically to `true`, and is deployed β€” verified live at 2,526 for `False` and 2,243 for `True`. One caveat that is not an SDK issue: `/api/psc/` responses are cached for 30 days per query-param key, so any `?has_awards=` key requested *before* that deploy still serves the old awards-only result until its entry expires or is invalidated. ### Fixed - **The reverse shape-coverage gate was blind to seven resources, and the SDK's schemas had silently drifted behind four of them.** The gate skipped any resource whose contract shape tree was falsy (`if not shape: continue`). Tango published `"shape": null` for `entities`, `opportunities`, `notices`, `protests`, `itdashboard`, `events`, and `news` β€” five of them because its contract generator crashed on tier-aware viewsets ([makegov/tango#2944](https://github.com/makegov/tango/pull/2944)) β€” so the gate reported full coverage while checking nothing for them. Re-vendoring the fixed contract surfaced **69 real gaps** (36 fields, 20 expands, 13 flattened expands) across entities, notices, protests, and itdashboard, all now closed by a regenerated overlay. The user-visible consequence was worse than missing schema entries. Because `ShapeParser` validates client-side, the SDK *rejected* 13 fields the API accepts, before ever issuing a request β€” `list_entities(shape="display_name")` raised `ShapeValidationError` against an endpoint that returns 200 for it. Affected: `Entity`'s `display_name`, `entity_type`, `entity_structure`, `organization_structure`, `profit_structure`, `purpose_of_registration`, `country_of_incorporation`, `past_performance`, `registered`, `sba_business_types`, and `Protest`'s `decisions`, `resolved_agency`, `resolved_protester`. All 13 now validate. Note that `registered` and `sba_business_types` regressed *in 1.3.0* β€” they validated under 1.1.1 β€” so the overlay generation had narrowed `Entity` while nothing was watching. The gate no longer skips silently: a resource declaring `shape_supported: true` with no shape tree is now a hard finding (`contract_missing_shape`) reported as an upstream contract defect rather than an SDK one. Contracts predating `schema_version: 2` omit the key, where a null tree stays genuinely ambiguous and skipping remains correct. - **Seven resources with working SDK methods were never conformance-checked at all.** `RESOURCE_TO_METHOD` omitted `protests`, `psc`, `mas_sins`, `departments`, `business_types`, and `assistance_listings` entirely, and mapped `offices` to `None` as "not yet implemented" even though `list_offices` exists. Their filter coverage had never been validated. Wiring them up found one real gap (`protests.naics_code`, above); the other six were already complete. `events` and `news` stay mapped to `None` β€” genuinely absent from the SDK, now with a note explaining that `list_webhook_event_types` is unrelated. - **`refresh_contract.py` + `probe_shape_types.py` re-run against the corrected contract.** `contracts/observed_shape_types.json` gained live-sampled types for the five newly-visible resources (entities alone contributes 136 observed paths), so the regenerated overlay resolves their types from real API responses rather than name heuristics. ### Changed - `CONTRACT_OMITTED_PARAMS` now warns when an entry is no longer needed, mirroring how baseline entries are burned down, and the list is now **empty** β€” which is the goal state. It briefly held `mas_sins: search`, added because the API applies it (330 results unfiltered, 0 for a nonsense term, 32 for `office`) while the contract recorded `filter_params: []`, so the checker would otherwise have flagged a working parameter as a silent no-op and invited its removal. Both that entry and `budget/accounts: search` were retired by the new warning once [makegov/tango#2944](https://github.com/makegov/tango/pull/2944) and [#2948](https://github.com/makegov/tango/pull/2948) taught the contract generator to publish them. The carve-out mechanism stays for the next such case. ## [1.3.0] - 2026-07-19 ### Added - **DIBBS, exclusions, and SBIR/STTR endpoint support.** Six endpoint families Tango shipped in v4.16–v4.18 had no SDK support at all β€” no models, no methods. Added `list_dibbs_rfqs`/`get_dibbs_rfq`, `list_dibbs_rfps`/`get_dibbs_rfp`, `list_dibbs_awards`/`get_dibbs_award`, `list_exclusions`/`get_exclusion`, `list_sbir_topics`/`get_sbir_topic`, and `list_sbir_solicitations`/`get_sbir_solicitation`, with all 85 filter params, shape schemas, and `ShapeConfig` defaults. New models: `DibbsRfq`, `DibbsRfp`, `DibbsAward`, `Exclusion`, `SbirTopic`, `SbirSolicitation`. Two API behaviors are worth knowing. `is_open` (DIBBS) and `is_currently_excluded` (exclusions) are derived at query time, so filter with the `open` / `active` kwargs rather than shaping on those fields. And DIBBS `total_contract_price` is the *order* total repeated on every line item β€” never sum it across rows; deduplicate on award + delivery-order number first. - **Reverse shape-coverage: the SDK now captures every field and expand the API returns.** The conformance check only validated one direction β€” that the SDK's shape constants reference *allowed* fields. Nothing checked the reverse, so the hand-maintained `tango/shapes/explicit_schemas.py` had silently fallen ~200+ fields behind the API: 209 leaf fields, 41 whole nested expand branches, and 3 resources (naics, psc, mas_sins) the typed shape API could not request at all. A new generated overlay (`tango/shapes/generated_overlay.py`, produced by `scripts/generate_shape_overlay.py` and merged over the base by `SchemaRegistry`) closes all of them, with types resolved from live-API sampling rather than guessed. Notable now-shapeable data: contract/IDV acquisition attributes (`fair_opportunity_limited_sources`, `subcontracting_plan`, …), `contracts.officers` and `period_of_performance`, the full `organizations` hierarchy (`obligation_rank`, `l1..l8_fh_key`, `budget_appropriation`, `children`/`parent`), `otas`/`otidvs` `transactions`, and the deep `vehicles.awardees[.orders]` tree. Code-object expands (`set_aside`, `award_type`, `idv_type`, …), previously modeled inconsistently as `str`/bare `dict`, now uniformly resolve to `{code, description}`. - **Reverse shape-coverage gate.** `scripts/check_shape_coverage.py` walks Tango's shape trees (from the vendored contract) against the SDK schemas and fails when the SDK misses anything the API exposes and it isn't in `contracts/shape_coverage_baseline.json`. Offline against the vendored contract β€” no token, runs on forks β€” and wired into the `lint.yml` conformance job. Regenerate the overlay with `scripts/generate_shape_overlay.py` (from the vendored contract + `contracts/observed_shape_types.json`, no API key); refresh the type observations with `scripts/probe_shape_types.py` (maintainer-run, needs a key). - **Contract-first conformance system.** The canonical API filter/shape contract is now vendored at `contracts/filter_shape_contract.json` (refresh with the new `scripts/refresh_contract.py`), so the conformance check runs out of the box β€” locally, in CI, and on forks β€” with no tango checkout or access token. `scripts/check_filter_shape_conformance.py` gained three new checks on top of filter coverage: **staleness** (an SDK filter argument the API no longer accepts is an error β€” it would silently no-op), **types** (each argument's annotation is validated against the contract's `schema_version: 2` per-filter type metadata), and a **known-gaps baseline** (`contracts/conformance_baseline.json`) that downgrades accepted missing params from errors to warnings so backlog is tracked instead of silent. A new `--suggest` flag prints ready-to-paste typed parameter scaffolds for any missing filters. The first run against the current API surface found 7 real coverage gaps, now baselined: `key` on contracts/IDVs/OTAs/OTIDVs, `cage` on entities, `id` on forecasts, and `opportunity_id` on opportunities. - `TangoValidationError` now exposes the API's structured validation details directly: `.issues` (the list of `{"path": ..., "reason": ...}` entries the server returns for shape errors) and `.available_fields` (the endpoint's valid field set, when included). Both were previously reachable only by digging through `.response_data`. ([#45](https://github.com/makegov/tango-python/issues/45)) ### Changed - The CI conformance job (`lint.yml`) now runs unconditionally against the vendored contract instead of silently skipping when `TANGO_API_REPO_ACCESS_TOKEN` is absent; the token is only used for a best-effort staleness notice comparing the vendored contract to tango HEAD. `scripts/pr_review.py` likewise defaults its conformance step to the vendored contract (override with `TANGO_CONTRACT_MANIFEST`). - 400 error messages now name the rejected field(s) and reason when the API returns structured `issues` β€” e.g. `Invalid request parameters: Invalid shape: tradeoff_process (unknown_field)` instead of just `Invalid request parameters: Invalid shape`. ([#45](https://github.com/makegov/tango-python/issues/45)) ### Fixed - **`docs/WEBHOOKS.md` listed only five of the eight webhook alert types.** It was missing `alerts.exclusion.match`, `alerts.dibbs_rfq.match`, and `alerts.dibbs_rfp.match`. No SDK change was needed β€” event types are served by the API and never hardcoded, so the new types already worked β€” but the hand-written list had gone stale. Also documents two things that surprise people: DIBBS *awards* are not alertable, and nothing fires when a record merely lapses (an exclusion hitting its termination date, or an RFQ/RFP passing its close date, emits no event). A production smoke test now asserts every live event type appears in the doc, so the list cannot silently fall behind again. - **Refreshed the vendored API contract, which had gone stale by seven resources.** It tracked 25 resources against Tango's current 32, so the conformance and coverage checks were validating against out-of-date truth and could not see DIBBS, exclusions, SBIR, or `budget/accounts` at all. Refreshing it also surfaced 72 additional fields on existing resources, now covered. Nested routes are keyed with a slash (`budget/accounts`), which silently broke the old `budget_accounts` mapping β€” both keys are now accepted. - **`check_filter_shape_conformance.py` no longer reports false stale params.** It resolved SDK arguments to API params only through an explicit `api_param_mapping` dict, so methods that express the translation as tuple tables β€” `("account_title__icontains", account_title)` and `range_filters = (("apportioned", apportioned, apportioned_gte, ...))` β€” looked like they exposed dozens of params the API rejects. They do not: `list_budget_accounts` correctly sends `apportioned__gte`, `fiscal_year__lte`, and `account_title__icontains`. The checker now understands both tuple forms (in `Assign`, `AnnAssign`, and inline `for` iterables), with an explicit `api_param_mapping` still taking precedence. This let `budget/accounts` be conformance-checked for the first time; its genuinely missing lookup variants (`agency_code__in`, `bureau_name__icontains`, …) are now baselined. ## [1.2.0] - 2026-06-05 ### Added - `list_budget_accounts()` now exposes the full range-filter surface that the REST endpoint has always supported. Every numeric metric on `/api/budget/accounts/` β€” the 26 fields in the backend's `RANGE_NUMERIC_FIELDS` list (`enacted_ba`, `apportioned`, `obligated_total`, `unobligated_balance`, `contract_obligated`, `contract_share_of_obligated_capped`, `ba_growth_next_year_pct`, `actual_vs_requested_contract`, all the ratio fields and their `_capped` variants, etc.) β€” is now accepted in three forms: exact match (`field=`), greater-or-equal (`field_gte=`), and less-or-equal (`field_lte=`). Previously only the identity / taxonomy filters were exposed, which forced callers to discover accounts by exact symbol lookup; the new surface makes pipeline-style queries (e.g. "all FY24 accounts where contract share β‰₯ 60%, unobligated balance β‰₯ $200M, and next-year growth β‰₯ 15%, sorted by largest headroom first") a single SDK call. The new params map to the API's `field__gte` / `field__lte` form; `ordering=` already accepted any of these fields and continues to. ## [1.1.3] - 2026-06-04 ### Added - Reference-data list/get methods now accept `shape` (and the associated `flat` / `flat_lists`) parameters, matching the underlying API which has always supported the shape system via `ShapeOnDemandMixin`. Affected: `list_naics` / `get_naics`, `list_psc` / `get_psc`, `list_assistance_listings` / `get_assistance_listing`, `list_business_types` / `get_business_type`, `list_mas_sins` / `get_mas_sin`. When `shape` is omitted, behavior is unchanged β€” the API applies its own per-resource default. `list_business_types` returns raw dicts (instead of `BusinessType` instances) when a `shape` is supplied so the caller gets exactly the shape requested. ## [1.1.2] - 2026-06-04 ### Changed - `get_entity_budget_flows()` now exposes the backend's standard page/limit pagination and `fiscal_year` filter, and returns `PaginatedResponse[dict[str, Any]]` instead of a raw dict. The backend has always paginated this endpoint via `StandardResultsSetPagination`; the previous signature gave callers no way to reach pages beyond the first or to narrow by fiscal year. Callers that were indexing `result["results"]` on the old return value should switch to `result.results` (and can now use `result.next` / `page=` to walk further pages). - Completed the strict-`mypy` burn-down across `tango/shapes/` (parser, generator, factory, schema). All changes are type-annotation/typing corrections with no runtime behavior change, except: - `FieldSchema.nested_model` is now typed `type | str | None` (it always accepted string model names from the explicit schemas; the annotation was wrong). `ModelFactory.validate_data` and `ShapeParser._validate_field_spec` likewise accept `type | str` for the model argument. - Removed two dead `elif field_spec.is_wildcard:` branches (in `TypeGenerator.generate_type` and `ModelFactory.create_instance`) and the now-orphaned `_parse_nested_wildcard` helper. These were unreachable β€” wildcard field specs are fully handled by the top-of-loop branch that `continue`s before reaching them β€” so removal is behavior-preserving. ### Docs - `docs/API_REFERENCE.md` now documents the Budget surface that shipped in v1.1.0: a new `## Budget` section covering `list_budget_accounts`, `get_budget_account`, `get_budget_account_quarters`, and `get_budget_account_recipients`; a `get_entity_budget_flows()` entry under Entity Sub-resources; a `BUDGET_ACCOUNTS_MINIMAL` row in the ShapeConfig table; and a Budget entry in the table of contents. ### CI - Bumped GitHub Actions off the deprecated Node 20 runtime (forced off 2026-06-02): `actions/checkout` v4β†’v6, `astral-sh/setup-uv` v4β†’v8.1.0 (pinned exact β€” no floating `v8` major tag is published yet), and `codecov/codecov-action` v3β†’v5 (with the renamed `files:` input). - `mypy` is now a **hard gate** in `lint.yml` (no longer advisory). The `tango/` package type-checks cleanly under strict mypy. ## [1.1.1] - 2026-05-29 ### Removed - The `notebooks` optional extra (`jupyter`, `ipykernel`). It only powered local editing of `docs/quick_start.ipynb`, which still renders on GitHub/PyPI without it, and its transitive tree (jupyter-server, jupyterlab, nbconvert, tornado, etc.) accounted for the bulk of the repo's open Dependabot alerts. Contributors who want to re-run the notebook can `pip install jupyter` directly. The shipped SDK is unaffected β€” its only runtime dependency remains `httpx`. ### Changed - Refreshed the dev/test dependency lock to clear the remaining Dependabot alerts (patched `idna`, `pygments`, `pytest`, `python-dotenv`; dropped `urllib3`/`requests` transitives). Dev-tool majors moved forward (`mypy` 1.18β†’2.1, `pytest` 8β†’9, `ruff` 0.14β†’0.15, `vcrpy` 7β†’8); all lint, type, and test gates stay green. No change to the shipped SDK's runtime deps. ## [1.1.0] - 2026-05-29 ### Fixed - `_parse_webhook_alert`: aligned the parser output with the `WebhookAlert` type contract. Sparse server payloads now hydrate `query_type` and `filters` as `""` / `{}` (matching their declared non-null types) rather than `None`, and `status` is typed as the `Literal["active", "paused"]` the model promises. Clears the four type-check errors this introduced; no change for full payloads. - `Contract` model: removed dead fields (`id`, `award_id`, `recipient_name`, `award_amount`, `awarding_agency`, `funding_agency`) and added the real API fields (`key`, `piid`, `obligated`, `total_contract_value`, `base_and_exercised_options_value`, `awarding_office`, `funding_office`, `naics_code`, `psc_code`, `set_aside`, `solicitation_identifier`, `parent_award`, `legislative_mandates`, `subawards_summary`, `place_of_performance`). The deprecated fields remain declared with `None` defaults for one minor cycle (they never returned data) and will be removed in `2.0.0`. New `OrganizationOfficePayload` dataclass for the office fields. (`Contract` is a documentation-only dataclass β€” not instantiated or exported β€” so there is no runtime impact.) - `list_contracts`: no longer sends `page=1` to the cursor-only `/api/contracts/` endpoint. When no cursor is supplied, neither `page` nor `cursor` is sent and the API returns the first page by default. - Shape validation: registered the `ContractOrIDVCompetition` nested schema (alias of `Competition`) so nested selections like `competition(extent_competed,number_of_offers_received)` on contract / IDV shapes validate instead of raising `ShapeValidationError`. ### Added - Budget accounts surface (tango v4.6.8): `list_budget_accounts`, `get_budget_account`, `get_budget_account_quarters`, `get_budget_account_recipients`. New `BudgetAccount` dataclass exported from the top-level package, plus `ShapeConfig.BUDGET_ACCOUNTS_MINIMAL`. - Singleton detail GETs: `get_contract`, `get_contract_subawards`, `get_contract_transactions`, `get_forecast`, `get_grant`, `get_notice`, `get_opportunity`, `get_subaward`. - `get_entity_budget_flows(uei)` for `/api/entities/{uei}/budget-flows/`. - `list_otidv_awards(key)` for `/api/otidvs/{key}/awards/` (parity with Node). - `grant_id` filter kwarg on `list_grants` (supports multi-value OR via `|`). ### CI - Re-enabled `lint.yml` as a PR + push-to-main gate. `ruff format` and `ruff check` are hard gates; `mypy` runs advisory (continue-on-error) pending burn-down of ~28 pre-existing type errors. The filter/shape conformance check is a separate job that skips cleanly until a `TANGO_API_REPO_ACCESS_TOKEN` secret for the private manifest repo is configured, at which point it becomes a hard gate. ## [1.0.0] - 2026-05-13 > First stable release. `tango-python` is now at full API parity with the > Tango HTTP surface, the legacy subject-based webhook subscription > mechanism has been removed in favor of filter alerts, the shape parser > agrees byte-for-byte with the server's expand-alias handling, and the > SDK's docs are auto-published to `docs.makegov.com/sdks/python/` via the > composer pipeline (makegov/docs#15 / makegov/docs#16). From `1.x` on, > we'll only do breaking changes on a major bump. > > Originally tracked as: API parity (PR #25), subject-based webhook > removal (PR #27 / issue #2275), shape-validator alias support (PR #28 / > issue #2266), and the docs-only content port (makegov/docs#16). ### Added - `ordering` parameter on `list_forecasts`, `list_grants`, `list_subawards`, `list_gsa_elibrary_contracts`, and `list_opportunities`. Prefix with `-` for descending. Closes a parity gap with the API surface (these endpoints all accept `?ordering=` server-side). - `create_webhook_endpoint` accepts `name=` (keyword-only) and now **requires** it. The Tango API enforces unique `(user, name)` on endpoints; omitting `name` returns a 400 server-side, so the SDK raises `TangoValidationError` client-side instead of round-tripping. (0.7.0 β€” never publicly released β€” emitted a `DeprecationWarning` instead.) - `update_webhook_endpoint` accepts `name=` for renaming an endpoint. - Webhook alerts (filter subscriptions): `list_webhook_alerts`, `get_webhook_alert`, `create_webhook_alert`, `update_webhook_alert`, `delete_webhook_alert` β€” the canonical write surface over `/api/webhooks/alerts/`. New `WebhookAlert` dataclass exported from the top-level package. - `resolve(name, target_type, ...)` β€” POST `/api/resolve/` to rank entity / organization candidates from a free-text name. Returns `ResolveResult` with `ResolveCandidate` entries (both exported). - `validate(identifier_type, value)` β€” POST `/api/validate/` to validate the format of a PIID, solicitation number, or UEI. Returns `ValidateResult` (exported). - Reference data: `list_departments`, `get_department`, `list_psc`, `get_psc`, `get_psc_metrics`, `get_naics`, `get_naics_metrics`, `get_business_type`, `list_assistance_listings`, `get_assistance_listing`, `list_mas_sins`, `get_mas_sin`. - Entity sub-resources: `list_entity_contracts`, `list_entity_idvs`, `list_entity_otas`, `list_entity_otidvs`, `list_entity_subawards`, `list_entity_lcats`, `get_entity_metrics`. All shape-aware where the underlying endpoint supports shaping. - IDV sub-resources: `list_idv_lcats`. - Agency sub-resources: `list_agency_awarding_contracts`, `list_agency_funding_contracts`. - Misc: `search_opportunity_attachments(q, top_k, include_extracted_text)` for `/api/opportunities/attachment-search/`; `get_version()` for `/api/version/`; `list_api_keys()` for `/api/api-keys/`. ### Changed - `create_webhook_alert` accepts `endpoint=` (keyword-only). Required for accounts with multiple webhook endpoints; auto-resolves for single-endpoint accounts. Closes the multi-endpoint smoke-test gap (tango#2256). - `test_webhook_delivery` now sends the canonical `endpoint` body key instead of the deprecated `endpoint_id` alias (tango#2252). The Python kwarg name stays `endpoint_id=` for backwards compatibility; the wire payload is what changed. - **`generate_signature(body, secret)` now returns the full wire form `"sha256="`** instead of bare hex. Callers can assign the return value directly to the `X-Tango-Signature` header without wrapping in a format string. This is a breaking change for code that relied on the bare-hex return; pass it through `parse_signature_header()` to recover the previous form. `verify_signature` accepts both prefixed and bare-hex inputs (unchanged), so receivers continue to work either way. ### Removed - **Subject-based webhook subscription surface** (tango#2275). Migrate to `create_webhook_alert(...)` and the alerts API. - Methods: `list_webhook_subscriptions`, `get_webhook_subscription`, `create_webhook_subscription`, `update_webhook_subscription`, `delete_webhook_subscription`. - Dataclasses: `WebhookSubscription`, `WebhookSubjectTypeDefinition`. Both are no longer exported from the top-level `tango` package β€” importing them raises `ImportError`. - Fields: `default_subject_type` removed from `WebhookEventType`; `subject_types` and `subject_type_definitions` removed from `WebhookEventTypesResponse`. The server's `/api/webhooks/event-types/` response no longer carries these. - CLI: the entire `tango webhooks subscriptions` Click subgroup (`list` / `get` / `create` / `delete`). Use the SDK's `client.create_webhook_alert(...)` etc. directly β€” there is no CLI subgroup for alerts. - `ordering` kwarg from `list_notices` and `list_protests`. The notices and protests viewsets reject every `?ordering=` value at runtime (tango#2254); the kwarg silently sent unsupported values. Other five list methods retain `ordering`. ### Fixed - `TangoClient._post()` and `_patch()` accept both `json_data=` (positional) and `json=` (keyword) for backward compatibility. Internal callers and docs examples that use `json=` no longer fail with `TypeError`. Passing **both** now raises `TangoValidationError` rather than silently preferring one β€” that ambiguity would hide caller bugs. - `get_psc_metrics` / `get_naics_metrics` / `get_entity_metrics` docstrings β€” `period_grouping` values are `"month"` / `"quarter"` / `"year"` (the path-segment values the API accepts), not `"monthly"` / `"quarterly"`. - `docs/API_REFERENCE.md#get_agency` β€” example uses `client.get_agency("GSA")` consistently and notes the parameter accepts CGAC / FPDS / short code / abbreviation / canonical name. - `README.md` Quick Start β€” `get_agency()` returns an `Agency` dataclass, so the example uses attribute access (`agency.name`) instead of `agency['name']` which would `TypeError`. - `scripts/smoke_api_parity.py` β€” `list_business_types(limit=1)` is now wrapped in the `run(...)` helper so a failure on that call records FAIL instead of aborting the smoke run. - `tango webhooks endpoints create` CLI now accepts and requires `--name` (passed through to `create_webhook_endpoint(name=...)`). Previously the option was absent, meaning the CLI could never set a custom endpoint name and every call would 400 server-side (the server enforces `unique(user, name)`). - `WebhookAlert.query_type` and `WebhookAlert.filters` tightened from `Optional` to non-optional (`str` and `dict[str, Any]` respectively). Legacy nullable rows were purged by the tango#2275 migration; the server model and serializer guarantee non-null values for all current data. `WebhookAlert.status` narrowed from `str` to `Literal["active", "paused"]` β€” the server serializer produces exactly those two values. - **Shape validator agrees with server on `naics(...)` / `psc(...)` expansions.** The client-side `ShapeParser.validate()` previously rejected the canonical `shape=naics(code,description)` form (which the server has always accepted) and also rejected the alias `shape=naics_code(code,description)`. The parser now mirrors the server's `_EXPAND_ALIASES` (introduced in Tango PR makegov/tango#2259) and rewrites `naics_code(...)` / `psc_code(...)` to their canonical `naics(...)` / `psc(...)` form at parse time. Bare scalar leaves (`shape=naics_code` / `shape=psc_code`) are left untouched and still return the raw column value, matching the server. Schemas for `Contract`, `Forecast`, `Opportunity`, `Notice`, and `Vehicle` gained explicit `naics` / `psc` expand entries backed by the existing `CodeDescription` nested model. Fixes makegov/tango#2266. - **`Subaward` schema matches the server's `SubawardSerializer`.** The previous `SUBAWARD_SCHEMA` declared two fields the server has never exposed (`id`, `amount`) and was missing every real field on the resource β€” including `piid`, `key`, `awarding_office` / `funding_office` / `place_of_performance` / `subaward_details` / `fsrs_details` / `highly_compensated_officers` / `usaspending_permalink`, and the denormalized `prime_awardee_*` / `recipient_*` lookup columns. Shape strings that referenced any real field (e.g. `shape="piid"`) would fail client-side validation with `unknown_field`, and conversely the SDK happily passed `shape="id"` / `shape="amount"` through to the server, where they were rejected. `SUBAWARD_SCHEMA` is now derived directly from `awards.serializers.subawards.SubawardSerializer` and the resource's runtime `available_fields`. The `Subaward` dataclass in `tango/models.py` was updated to match. New nested schemas `SubawardDetails`, `FsrsDetails`, `SubawardPlaceOfPerformance`, and `HighlyCompensatedOfficer` are registered so the corresponding shape expansions validate end-to-end. ### Documentation - New `docs/ERRORS.md` β€” full exception hierarchy, recovery patterns, and the shape-error classes (`ShapeValidationError`, `ShapeParseError`, `TypeGenerationError`, `ModelInstantiationError`). Ported from `docs.makegov.com/sdks/python/errors.md` ahead of the docs-site auto-pull cutover (makegov/docs#15 / makegov/docs#16). - New `docs/PAGINATION.md` β€” page-based vs cursor-based strategies, iteration patterns, and the `PaginatedResponse` field reference. Ported from `docs.makegov.com/sdks/python/pagination.md`. - New `docs/CLIENT.md` β€” `TangoClient` constructor reference, `rate_limit_info` / `last_response_headers` properties, and retry-semantics note (the SDK has no built-in retry). Ported from `docs.makegov.com/sdks/python/client.md`. ### CI - New `.github/workflows/docs-dispatch.yml` β€” fires on push to `main` when `docs/**`, `README.md`, or `CHANGELOG.md` changes and dispatches `external_updated` at `makegov/docs` so the public docs site rebuilds with the latest SDK content. Required for the makegov/docs#15 auto-pull pipeline. ## [0.6.0] - 2026-05-07 ### Added - Vehicles: new top-level fields `program_acronym`, `idv_count`, `total_obligated`, `is_synthetic_solicitation`, `latest_award_date`, `description`, `opportunity_id`. - Vehicles: new `metrics(*)` shape expansion bundling 12 computed metrics: `avg_offers_received`, `award_concentration_hhi`, `order_concentration_hhi`, `competed_rate`, `using_agency_count`, `avg_order_value`, `max_order_value`, `top_recipient_share`, `recent_obligations_24mo`, `recent_orders_24mo`, `days_since_last_order`, `obligation_to_ceiling_ratio`. Backed by a new `VehicleMetrics` schema. - `list_vehicle_orders(uuid, ...)` for the new `/api/vehicles/{uuid}/orders/` endpoint, returning task orders under the vehicle's IDVs with two-phase pagination. - `list_vehicles` gained 21 explicit filter parameters per API 4.3.0: `vehicle_type`, `type_of_idc`, `contract_type`, `set_aside` (multi-value via `|`), `who_can_use`, `naics_code`, `psc_code`, `program_acronym`, `agency`, `organization_id`, `total_obligated_min`/`max`, `idv_count_min`/`max`, `order_count_min`/`max`, `fiscal_year`, `award_date_after`/`before`, `last_date_to_order_after`/`before`. - `list_vehicle_awardees` gained a `search` parameter for entity-aware full-text search across IDV fields and recipient entity details (API 4.3.0). - `ordering` parameter on `list_vehicles` (whitelist: `vehicle_obligations`, `latest_award_date`, `total_obligated`, `award_date`, `last_date_to_order`, `fiscal_year`, `idv_count`, `order_count`) and on `list_vehicle_orders` (whitelist: `award_date`, `obligated`, `total_contract_value`). Prefix with `-` for descending. - `ShapeConfig.VEHICLE_ORDERS_MINIMAL` default for the new orders endpoint. - Shaping: New `organization(*)` expand on `Vehicle`, `Forecast`, `Grant`, `ITDashboardInvestment`, and `Protest` schemas β€” returns the canonical 7-key office payload (`organization_id`, `office_code`, `office_name`, `agency_code`, `agency_name`, `department_code`, `department_name`). Selectable as the bare leaf (`shape=...,organization`) or as a sub-selectable expansion (`shape=...,organization(office_code,...)`). - Shaping: New `vehicle(*)` expand on `Contract` β€” request the parent vehicle inline from `/api/contracts/` (API 4.2.0). - `Vehicle` and `VehicleMetrics` are now exported from the top-level `tango` package. - `tango.webhooks` subpackage with HMAC-SHA256 signing helpers (`verify_signature`, `generate_signature`, `parse_signature_header`) that mirror the canonical Tango server scheme byte-for-byte. Importable from a default `pip install tango-python` (pure stdlib). - `WebhookReceiver`: a stdlib-based local HTTP listener for development and integration tests. Verifies signatures, optionally forwards each delivery to a downstream URL, and records deliveries in memory for inspection. Usable as a context manager (`with WebhookReceiver(secret=...).run() as rx: ...`). - `tango.webhooks.simulate.deliver(...)`: locally sign and POST a payload to any URL β€” no Tango involvement. Useful for offline iteration on receiver code. - New `tango[webhooks]` extra (adds `click`) ships a `tango` console script covering the full webhook lifecycle for developer integrations: - `listen` β€” local receiver - `simulate` β€” sign a payload locally; with `--to`, also POST it - `trigger` β€” ask Tango to send a real test delivery - `fetch-sample` β€” print the canonical payload Tango emits for an event type - `list-event-types` β€” discover what's subscribable - `endpoints list|get|create|delete` β€” manage delivery endpoints - `subscriptions list|get|create|delete` β€” manage what events you receive Together these let a developer go from zero to receiving real Tango webhooks without leaving the shell or dropping into Python. ### Changed - `ShapeConfig.VEHICLES_MINIMAL` and `VEHICLES_COMPREHENSIVE` now include the new top-level fields and the `organization` expansion. `VEHICLES_COMPREHENSIVE` defaults to `metrics(*)` and no longer pulls the deprecated `competition_details(*)` blob. ### Deprecated - Vehicles shape fields `agency_details`, `competition_details`, and the `opportunity` expansion. The upstream API now sends a `Deprecation: true` header for these and recomputes them at request time. Explicit use in `shape=...` emits a Python `DeprecationWarning`. Sunset timeline TBD upstream. ### Notes - Console script name `tango` may be revisited in a future release if it conflicts with sibling tooling (`tango-scripts` reuses the bare name). ### Documentation - New `docs/WEBHOOKS.md` β€” comprehensive guide covering install, concepts, a zero-to-receiving quickstart, full CLI reference, and programmatic patterns for `WebhookReceiver` / `simulate.sign` / `simulate.deliver` in pytest fixtures. - `docs/API_REFERENCE.md`: filled in `get_webhook_subscription`, replaced the hand-rolled signature-verification snippet with a pointer to `tango.webhooks.verify_signature`, and added a new "Webhook tooling (`tango.webhooks`)" section that documents every importable from the new subpackage. - `README.md`: new "Webhook Tooling" section under Advanced Features, plus the new guide is linked from the Documentation index. ## [0.5.0] - 2026-04-08 ### Added - IT Dashboard investments: `list_itdashboard_investments`, `get_itdashboard_investment` (`/api/itdashboard/`) with shaping and filter params (`search`, `agency_code`, `agency_name`, `type_of_investment`, `updated_time_after`, `updated_time_before`, `cio_rating`, `cio_rating_max`, `performance_risk`). Tier-gated by the API: free tier gets `search`, pro adds structured filters, business+ adds CIO/performance analytics. New `ITDashboardInvestment` model and `ShapeConfig.ITDASHBOARD_INVESTMENTS_MINIMAL` / `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` defaults. ## [0.4.4] - 2026-03-25 ### Added - `parent_piid` filter parameter on `list_contracts` for filtering orders under a specific parent IDV PIID. - `user_agent` and `extra_headers` parameters on `TangoClient` for custom request headers. - `TangoClient.last_response_headers` property for accessing full HTTP headers from the most recent API response. ## [0.4.3] - 2026-03-21 ### Added - `TangoRateLimitError` now exposes `wait_in_seconds`, `detail`, and `limit_type` properties parsed from the API's 429 response body. - `RateLimitInfo` dataclass for structured access to rate limit headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and per-window daily/burst variants). - `TangoClient.rate_limit_info` property returns rate limit info from the most recent API response. ### Changed - `_request` now passes the full 429 response body to `TangoRateLimitError` (previously discarded), enabling callers to access `wait_in_seconds` and the specific limit type that was exceeded. ## [0.4.2] - 2026-03-04 ### Added - Protests endpoints: `list_protests`, `get_protest` with shaping and filter params (`source_system`, `outcome`, `case_type`, `agency`, `case_number`, `solicitation_number`, `protester`, `filed_date_after`, `filed_date_before`, `decision_date_after`, `decision_date_before`, `search`). ### Changed - Lint CI workflow disabled for push/PR (runs only on manual trigger) until the private `makegov/tango` repo is accessible to the workflow. - Updated documents to reflect changes since v0.4.0 - Entities: `ENTITIES_COMPREHENSIVE` now uses `federal_obligations(*)` expansion; the API treats federal obligations as an expansion rather than a plain shape field. - Docs: `SHAPES.md` documents `federal_obligations(*)` as an expansion for entity shaping. - Integration tests: `test_parsing_nested_objects_with_missing_data` accepts award office fields (`office_code`, `agency_code`, `department_code`) and empty nested objects when the API returns partial data. ### Removed - Assistance: `list_assistance` endpoint and all related tests, docs, and references. - IDV summaries: `get_idv_summary` and `list_idv_summary_awards` endpoints and related integration tests, cassettes, and API reference section. ## [0.4.1] - 2026-03-03 ### Added - GSA eLibrary contracts: `list_gsa_elibrary_contracts`, `get_gsa_elibrary_contract` with shaping and filter params (`contract_number`, `key`, `piid`, `schedule`, `search`, `sin`, `uei`). ### Changed - Conformance: replaced `**kwargs`/`**filters` with explicit filter parameters on `list_contracts`, `list_idvs`, `list_entities`, `list_forecasts`, `list_grants`, `list_notices`, `list_opportunities` for full filter/shape conformance. Backward compatibility preserved for `list_contracts(filters=SearchFilters(...))`. ## [0.4.0] - 2026-02-24 ### Added - Offices, Organizations, OTAs, OTIDVs, Subawards, NAICS, and Assistance endpoints. - Filter/shape conformance tooling and documentation. ### Changed - CI lint workflow runs filter/shape conformance when the manifest is available. ## [0.3.0] - 2026-02-09 ### Added - Vehicles endpoints: `list_vehicles`, `get_vehicle`, and `list_vehicle_awardees` (supports shaping + flattening). (refs `makegov/tango#1328`) - IDV endpoints: `list_idvs`, `get_idv`, `list_idv_awards`, `list_idv_child_idvs`, `list_idv_transactions`, `get_idv_summary`, `list_idv_summary_awards`. (refs `makegov/tango#1328`) - Webhooks v2 client support: event type discovery, subscription CRUD, endpoint management, test delivery, and sample payload helpers. (refs `makegov/tango#1274`) ### Changed - Expanded explicit schemas to support common IDV shaping expansions (award offices, officers, period of performance, etc.). - HTTP client now supports PATCH/DELETE helpers for webhook management endpoints. ## [0.2.0] - 2025-11-16 - Entirely refactored SDK --- # Client Configuration `TangoClient` is the entry point for every API call. This guide covers the constructor, the rate-limit and response-inspection properties, and how the client handles authentication and transport. For per-method signatures, see [`API_REFERENCE.md`](api-reference.md). For error handling, see [`ERRORS.md`](errors.md). For shaping responses, see [`SHAPES.md`](shapes.md). ## Constructor ```python from tango import TangoClient client = TangoClient( api_key="your-api-key", # or set TANGO_API_KEY env var base_url="https://tango.makegov.com", # default user_agent="my-app/1.0", # optional custom User-Agent extra_headers={"X-Custom": "val"}, # optional additional headers ) ``` | Parameter | Type | Default | Description | |---|---|---|---| | `api_key` | `str \| None` | `None` | API key. Falls back to `TANGO_API_KEY` environment variable. | | `base_url` | `str` | `"https://tango.makegov.com"` | Base URL for the Tango API. | | `user_agent` | `str \| None` | `None` | Custom User-Agent string appended to the default. | | `extra_headers` | `dict[str, str] \| None` | `None` | Additional HTTP headers sent with every request. | The client uses [httpx](https://www.python-httpx.org/) under the hood with a 30-second timeout. The API key is sent as an `X-API-KEY` header on every request. ## Properties ### `rate_limit_info` Returns rate limit information from the most recent API response. ```python resp = client.list_contracts(limit=5) info = client.rate_limit_info if info: print(f"Remaining: {info.remaining}/{info.limit}") print(f"Resets in: {info.reset}s") print(f"Daily remaining: {info.daily_remaining}/{info.daily_limit}") ``` The `RateLimitInfo` object exposes: | Field | Type | Description | |---|---|---| | `limit` | `int \| None` | Request limit for the current window | | `remaining` | `int \| None` | Requests remaining in the current window | | `reset` | `int \| None` | Seconds until the window resets | | `daily_limit` | `int \| None` | Daily request limit | | `daily_remaining` | `int \| None` | Daily requests remaining | | `daily_reset` | `int \| None` | Seconds until the daily limit resets | | `burst_limit` | `int \| None` | Burst request limit | | `burst_remaining` | `int \| None` | Burst requests remaining | | `burst_reset` | `int \| None` | Seconds until the burst limit resets | ### `last_response_headers` Returns the full HTTP headers from the most recent API response, as an `httpx.Headers` object. ```python resp = client.list_contracts(limit=5) headers = client.last_response_headers print(headers["content-type"]) ``` ## Retry Semantics The SDK does **not** include built-in retry or backoff. Each method call maps to exactly one HTTP request. If you need retry-on-429 or retry-on-transient-error behavior, wrap your calls (or catch [`TangoRateLimitError`](errors.md#tangoratelimiterror-429) and use `wait_in_seconds`). See the [Rate Limits guide](https://docs.makegov.com/guides/patterns/rate-limits/) for recommended strategies. --- # Tango Python SDK – Dynamic Models Guide This document explains how the **Python dynamic shaping system** works. It mirrors the Node.js `DYNAMIC_MODELS.md` guide for the Python SDK. --- ## Overview Tango's dynamic modeling allows you to: - Request _exactly the fields you want_ - Validate the shape string against Tango's schemas - Generate a typed model descriptor at runtime - Materialize shaped objects using correct: - date parsing - datetime parsing - decimal handling - list vs scalar logic - nested structure --- ## Components ### ShapeParser Parses shape strings into a `ShapeSpec`. ```python from tango.shapes import ShapeParser parser = ShapeParser() spec = parser.parse("key,piid,recipient(display_name)") ``` ### SchemaRegistry Holds the field schemas for all models. ```python from tango.shapes import SchemaRegistry from tango.models import Contract registry = SchemaRegistry() schema = registry.get_schema(Contract) award_date_field = schema["award_date"] # FieldSchema(name='award_date', type=date | None) ``` ### TypeGenerator Builds a dynamic `TypedDict`-backed type from `(shape_spec, base_model)`. ```python from tango.shapes import ShapeParser, TypeGenerator from tango.models import Contract parser = ShapeParser() spec = parser.parse("key,piid,recipient(display_name)") gen = TypeGenerator() dynamic_type = gen.generate_type( shape_spec=spec, base_model=Contract, type_name="ContractShaped", ) ``` ### ModelFactory Takes a dynamic type + raw API JSON and produces typed `ShapedModel` instances. The `TangoClient` uses this pipeline automatically after fetching data. ```python from tango import TangoClient client = TangoClient(api_key="your-api-key") contracts = client.list_contracts( shape="key,award_date,recipient(display_name)", ) # contracts.results are ShapedModel instances materialized by ModelFactory: # - date/datetime strings parsed to date/datetime objects # - decimals normalized via Decimal # - nested structures are themselves ShapedModel instances ``` --- ## Example: Full Shaping Pipeline (manual) ```python from tango.shapes import ShapeParser, TypeGenerator, ModelFactory, create_default_parser_registry from tango.models import Contract parser = ShapeParser() spec = parser.parse("key,award_date,recipient(display_name)") gen = TypeGenerator() dynamic_type = gen.generate_type( shape_spec=spec, base_model=Contract, type_name="ContractShaped", ) parsers = create_default_parser_registry() factory = ModelFactory(gen, parsers) shaped = factory.create_instance( data={ "key": "C-1", "award_date": "2024-01-15", "recipient": {"display_name": "Acme"}, }, shape_spec=spec, base_model=Contract, dynamic_type=dynamic_type, ) ``` `shaped` becomes: ```python ContractShaped(key='C-1', award_date=datetime.date(2024, 1, 15), recipient=ContractShaped_Recipient(display_name='Acme')) ``` --- ## Attribute Access `ShapedModel` is a `dict` subclass with `__getattr__` so fields are accessible both as dictionary keys and as attributes: ```python # Both styles work shaped["key"] # "C-1" shaped.key # "C-1" # Nested models are also ShapedModel instances shaped.recipient["display_name"] # "Acme" shaped.recipient.display_name # "Acme" ``` Accessing a field that was not included in your shape raises a descriptive `AttributeError` with suggestions: ```python shaped.award_amount # AttributeError: Field 'award_amount' not found in ContractShaped. # Available fields: 'key', 'award_date', 'recipient' # This field may not be included in your shape specification. # To include this field, add it to your shape parameter. ``` --- ## Type Safety The Python SDK enforces shape correctness at parse time via `ShapeParser.validate()`. Nested structures are recursively materialized as `ShapedModel` instances, guaranteeing the same access patterns at every depth. No static class generation happens at build time; shapes are resolved at runtime. --- ## Caching `TypeGenerator` caches descriptors using a thread-safe LRU cache (default: 100 entries). `ShapeParser` also caches parse results keyed on the raw shape string. --- ## Nested Models If a field is nested in the schema (e.g. `"recipient"` β†’ `RecipientProfile`), the generator recursively builds the nested descriptor, naming it `{ParentType}_{FieldName}` (e.g. `ContractShaped_Recipient`). Each nested object is also a `ShapedModel`, so attribute access and `repr` work uniformly at every level. --- ## Predefined Shape Constants `ShapeConfig` provides opinionated defaults for each resource's list and detail methods. Each `TangoClient` method applies its corresponding default automatically; pass `shape=` to override. ```python from tango import TangoClient, ShapeConfig client = TangoClient(api_key="your-api-key") # These are equivalent β€” list_contracts defaults to CONTRACTS_MINIMAL contracts = client.list_contracts(limit=10) contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10) # Other resources entities = client.list_entities(shape=ShapeConfig.ENTITIES_MINIMAL) idvs = client.list_idvs(shape=ShapeConfig.IDVS_MINIMAL) ``` See [API Reference – ShapeConfig](api-reference.md#shapeconfig-predefined-shapes) for the full table of constants. --- # Error Handling The SDK raises typed exceptions for HTTP errors and for shape-related failures. All exceptions are importable from `tango.exceptions` (and re-exported from the top-level `tango` package for the API errors). For a compact reference of each class, see [`API_REFERENCE.md` Β§ Error Handling](api-reference.md#error-handling). This guide covers the hierarchy, recovery patterns, and the shape-error classes that don't have a dedicated section there. ## Exception Hierarchy ``` TangoAPIError β”œβ”€β”€ TangoAuthError (401 Unauthorized) β”œβ”€β”€ TangoNotFoundError (404 Not Found) β”œβ”€β”€ TangoValidationError (400 Bad Request) β”œβ”€β”€ TangoRateLimitError (429 Too Many Requests) └── ShapeError β”œβ”€β”€ ShapeValidationError (invalid field names) β”œβ”€β”€ ShapeParseError (invalid shape syntax) β”œβ”€β”€ TypeGenerationError (dynamic type generation failure) └── ModelInstantiationError (model creation failure) ``` ## API Errors ### TangoAPIError (base) All API errors inherit from this class. | Attribute | Type | Description | |---|---|---| | `status_code` | `int \| None` | HTTP status code | | `response_data` | `dict` | Parsed response body (credentials redacted) | | `message` | `str` | Human-readable error message | ```python from tango import TangoClient from tango.exceptions import TangoAPIError client = TangoClient() try: resp = client.list_contracts(limit=10) except TangoAPIError as e: print(f"API error {e.status_code}: {e.message}") ``` ### TangoAuthError (401) Raised when the API key is missing, invalid, or expired. ```python from tango.exceptions import TangoAuthError try: client = TangoClient(api_key="invalid-key") client.list_contracts(limit=1) except TangoAuthError: print("Check your API key") ``` ### TangoNotFoundError (404) Raised when a resource doesn't exist. ```python from tango.exceptions import TangoNotFoundError try: entity = client.get_entity("INVALID_UEI") except TangoNotFoundError: print("Entity not found") ``` ### TangoValidationError (400) Raised for invalid request parameters (bad date format, unknown filter, etc.). ### TangoRateLimitError (429) Raised when you exceed rate limits. Includes retry information. | Attribute | Type | Description | |---|---|---| | `wait_in_seconds` | `int \| None` | Seconds to wait before retrying | | `detail` | `str \| None` | Human-readable rate limit message | | `limit_type` | `str \| None` | `"burst"` or `"daily"` | ```python import time from tango.exceptions import TangoRateLimitError try: resp = client.list_contracts(limit=10) except TangoRateLimitError as e: if e.wait_in_seconds: print(f"Rate limited ({e.limit_type}). Retrying in {e.wait_in_seconds}s...") time.sleep(e.wait_in_seconds) resp = client.list_contracts(limit=10) ``` > **Note:** The SDK does not include built-in retry or backoff. You are responsible for handling rate limit errors. See the [Rate Limits guide](https://docs.makegov.com/guides/patterns/rate-limits/) for strategies. ## Shape Errors These are raised when there's a problem with the response shaping configuration, not the API itself. See [`SHAPES.md`](shapes.md) for shape syntax. ### ShapeValidationError Raised when a shape string references field names that don't exist on the model. ```python from tango.exceptions import ShapeValidationError try: resp = client.list_contracts(shape="key,piid,nonexistent_field", limit=1) except ShapeValidationError as e: print(f"Invalid shape: {e}") print(f"Shape string: {e.shape}") ``` ### ShapeParseError Raised when the shape string has invalid syntax (unbalanced parentheses, etc.). | Attribute | Type | Description | |---|---|---| | `shape` | `str` | The invalid shape string | | `position` | `int \| None` | Character position where parsing failed | ### TypeGenerationError Raised when the SDK fails to generate a dynamic TypedDict for a shaped response. ### ModelInstantiationError Raised when the SDK fails to create a model instance from API data. | Attribute | Type | Description | |---|---|---| | `field_name` | `str \| None` | Field that caused the failure | | `expected_type` | `type \| None` | Expected Python type | | `actual_value` | `Any` | Value that couldn't be coerced | ## Catching Everything To handle any SDK-raised error in one place, catch `TangoAPIError` and `ShapeError` (or just `Exception` at the outermost boundary): ```python from tango.exceptions import TangoAPIError, ShapeError try: resp = client.list_contracts(shape="key,piid", limit=10) except TangoAPIError as e: # HTTP-layer problems (auth, rate limit, validation, etc.) print(f"API error {e.status_code}: {e.message}") except ShapeError as e: # Shape-string or model-construction problems print(f"Shape error: {e}") ``` --- # Tango Python SDK [![PyPI](https://img.shields.io/pypi/v/tango-python.svg)](https://pypi.org/project/tango-python/) [![Python Versions](https://img.shields.io/pypi/pyversions/tango-python.svg)](https://pypi.org/project/tango-python/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) A modern Python SDK for the [Tango API](https://tango.makegov.com) by MakeGov, featuring dynamic response shaping and comprehensive type hints. ## Features - **Dynamic Response Shaping** - Request only the fields you need, reducing payload sizes by 60-80% - **Full Type Safety** - Runtime-generated TypedDict types with accurate type hints for IDE autocomplete - **Comprehensive API Coverage** - All major Tango API endpoints (contracts, IDVs, OTAs, entities, forecasts, opportunities, notices, grants, protests, webhooks, and more) - **Flexible Data Access** - Dictionary-based response objects with validation - **Modern Python** - Built for Python 3.12+ using modern async-ready patterns - **Production-Ready** - Comprehensive test suite with VCR.py-based integration tests ## Installation **Requirements:** Python 3.12 or higher ```bash pip install tango-python ``` Or with uv: ```bash uv pip install tango-python ``` ## Quick Start ```python from tango import TangoClient, ShapeConfig # Initialize the client client = TangoClient(api_key="your-api-key") # List agencies agencies = client.list_agencies() print(f"Found {agencies.count} agencies") # Get specific agency agency = client.get_agency("GSA") print(f"Agency: {agency.name}") # Search contracts contracts = client.list_contracts( limit=10 ) ``` ## Authentication Most endpoints require an API key. You can obtain one from the [Tango API portal](https://tango.makegov.com). ```python # With API key client = TangoClient(api_key="your-api-key") # From environment variable (TANGO_API_KEY) client = TangoClient() ``` ## Core Concepts ### Dynamic Response Shaping Response shaping is the most powerful feature of the Tango SDK. It lets you request only the fields you need, dramatically reducing payload sizes and improving performance. ```python from tango import TangoClient, ShapeConfig client = TangoClient(api_key="your-api-key") # Custom shape - only fields you need contracts = client.list_contracts( shape="key,piid,recipient(display_name,uei),total_contract_value", limit=10 ) # Access fields using dictionary syntax OR as an attribute for contract in contracts.results: print(f"PIID: {contract['piid']}") print(f"Recipient: {contract['recipient']['display_name']}") for contract in contracts.results: print(f"PIID: {contract.piid}") print(f"Recipient: {contract.recipient.display_name}") ``` ## API Methods ### Agencies ```python # List all agencies agencies = client.list_agencies(page=1, limit=25) # Get specific agency by code agency = client.get_agency("GSA") ``` ### Contracts ```python # List/search contracts with filtering contracts = client.list_contracts( page=1, limit=25, # Filter parameters keyword="software", awarding_agency="4700", # GSA agency code award_date_gte="2023-01-01", fiscal_year=2024, naics_code="541511" ) # Filter by specific agency contracts = client.list_contracts( awarding_agency="4700", # GSA limit=50 ) ``` **Available Filter Parameters:** **Text Search:** - `keyword` - Search contract descriptions (mapped to 'search' API param) **Date Filters:** - `award_date_gte`, `award_date_lte` - Award date range - `pop_start_date_gte`, `pop_start_date_lte` - Period of performance start date range - `pop_end_date_gte`, `pop_end_date_lte` - Period of performance end date range - `expiring_gte`, `expiring_lte` - Contract expiration date range **Party Filters:** - `awarding_agency`, `funding_agency` - Agency codes, names, abbreviations, or organization UUIDs. Multi-value OR via `|`. - `recipient_name`, `recipient_uei` - Vendor/recipient filters ### Checking how agency filters resolved Agency values are resolved fuzzily, so a token can match an organization you did not intend β€” which silently scopes the query to that organization's subtree. A short result set is then indistinguishable from "no such records exist". Responses expose what actually happened: ```python response = client.list_contracts(awarding_agency="HUD|HUDD") # Tokens that matched nothing and were ignored. if response.unresolved_agency_tokens: raise SystemExit(f"dropped: {response.unresolved_agency_tokens}") # {'awarding_agency': ['HUDD']} # What the tokens that DID match resolved to β€” the only way to catch a # plausible-but-wrong match, where nothing was dropped at all. for org in response.resolved_agencies.get("awarding_agency", []): print(org["name"], org["cgac"]) # Department of Housing and Urban Development 086 for warning in response.agency_warnings: print(warning) ``` Each entry of `response.meta["resolved_filters"][]` that resolved also says how its token matched, in `matched_by` (Tango API 5.9.0+): `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match). A `fuzzy` match is the one worth checking against the resolved name: ```python for entry in response.meta["resolved_filters"].get("awarding_agency", []): if entry.get("matched_by") == "fuzzy": print(f"{entry['token']!r} loosely matched {entry['resolved']['name']}") ``` If *every* token for a filter fails to resolve, the API returns `400` and the SDK raises `TangoValidationError` naming the offending value, rather than an empty page. **Classification:** - `naics_code`, `psc_code` - Industry/product codes - `set_aside_type` - Set-aside type **Type Filters:** - `fiscal_year`, `fiscal_year_gte`, `fiscal_year_lte` - Fiscal year filters - `award_type` - Award type code **Identifiers:** - `piid` - Procurement Instrument Identifier - `solicitation_identifier` - Solicitation ID **Sorting:** - `sort`, `order` - Sort results (e.g., `sort="award_date"`, `order="desc"`) **Response Options:** - `shape`, `flat`, `flat_lists` - Response shaping options ### IDVs, OTAs, OTIDVs ```python # List IDVs (keyset pagination) idvs = client.list_idvs(limit=25, awarding_agency="4700") # Get single IDV with shaping idv = client.get_idv("IDV_KEY", shape=ShapeConfig.IDVS_COMPREHENSIVE) # OTAs and OTIDVs follow the same pattern otas = client.list_otas(limit=25) otidvs = client.list_otidvs(limit=25) ``` ### Vehicles ```python vehicles = client.list_vehicles( search="GSA schedule", ordering="-vehicle_obligations", shape=ShapeConfig.VEHICLES_MINIMAL, ) vehicle = client.get_vehicle("UUID", shape=ShapeConfig.VEHICLES_COMPREHENSIVE) awardees = client.list_vehicle_awardees("UUID") orders = client.list_vehicle_orders("UUID", ordering="-obligated") ``` ### Entities (Vendors/Recipients) ```python # List entities with filters entities = client.list_entities(search="Booz Allen", state="VA", limit=25) # Get specific entity by UEI or CAGE code entity = client.get_entity("ZQGGHJH74DW7") ``` ### Forecasts ```python forecasts = client.list_forecasts(agency="GSA", fiscal_year=2025, limit=25) ``` ### Opportunities ```python opportunities = client.list_opportunities(agency="DOD", active=True, limit=25) ``` ### Notices ```python notices = client.list_notices(agency="DOD", notice_type="Presolicitation", limit=25) ``` ### Grants ```python grants = client.list_grants(agency="HHS", status="F", limit=25) # F = Forecasted ``` ### Protests ```python protests = client.list_protests(source_system="gao", outcome="Sustained", limit=25) protest = client.get_protest("CASE_UUID") ``` ### GSA eBuy ```python access = client.get_ebuy_access() # scoped to the schedule contracts linked to your account requests = client.list_ebuy_requests(status="Open", sin="54151S", limit=25) request = client.get_ebuy_request("RFQ1835158") url = client.get_ebuy_attachment_url("RFQ1835158", doc_seq_num=1) # short-lived signed URL ``` ### GSA eLibrary Contracts ```python contracts = client.list_gsa_elibrary_contracts(schedule="MAS", limit=25) contract = client.get_gsa_elibrary_contract("UUID") ``` ### Reference Data ```python # Offices, organizations, NAICS, PSC, subawards, business types offices = client.list_offices(search="acquisitions") organizations = client.list_organizations(level=1) naics = client.list_naics(search="software") get_naics = client.get_naics("541511") psc = client.list_psc() subawards = client.list_subawards(prime_uei="UEI123") business_types = client.list_business_types() mas_sins = client.list_mas_sins() assistance = client.list_assistance_listings() departments = client.list_departments() ``` ### Resolve / Validate ```python # Resolve a name to entity/org candidates result = client.resolve(name="Lockheed Martin", target_type="entity") for c in result.candidates: print(c.identifier, c.display_name) # Validate an identifier result = client.validate(identifier_type="uei", value="ABCDEF123456") ``` ### IT Dashboard ```python investments = client.list_itdashboard_investments(search="cloud", limit=25) investment = client.get_itdashboard_investment("023-000001234") ``` ### Entity Sub-resources ```python contracts = client.list_entity_contracts("ABCDEF123456", limit=25) idvs = client.list_entity_idvs("ABCDEF123456") otas = client.list_entity_otas("ABCDEF123456") metrics = client.get_entity_metrics("ABCDEF123456", months=12, period_grouping="month") ``` ## Pagination All list methods return a `PaginatedResponse` object with metadata: ```python response = client.list_contracts(limit=25) print(f"Total results: {response.count}") print(f"Next page URL: {response.next}") print(f"Previous page URL: {response.previous}") # Iterate through results for contract in response.results: print(contract['description']) # Get next page (contracts use keyset/cursor pagination) if response.next: next_response = client.list_contracts(cursor=response.cursor, limit=25) ``` ## Error Handling The SDK provides specific exception types for different error scenarios: ```python from tango import ( TangoClient, TangoAPIError, TangoAuthError, TangoNotFoundError, TangoRateLimitError, TangoValidationError ) client = TangoClient(api_key="your-api-key") try: contracts = client.list_contracts(limit=10) except TangoAuthError: print("Invalid API key or authentication required") except TangoNotFoundError: print("Resource not found") except TangoValidationError as e: print(f"Invalid parameters: {e.message}") print(f"Details: {e.response_data}") except TangoRateLimitError: print("Rate limit exceeded") except TangoAPIError as e: print(f"API error: {e.message}") ``` ## Advanced Features ### Custom Shapes Create custom shapes to request exactly the fields you need: ```python # Simple fields contracts = client.list_contracts( shape="key,piid,description,total_contract_value" ) # Nested relationships contracts = client.list_contracts( shape="key,piid,recipient(display_name,uei),place_of_performance(*))" ) # Wildcards for all fields contracts = client.list_contracts( shape="key,piid,recipient(*)" ) ``` ### Flattened Responses The `flat=True` parameter is passed to the API, which returns dot-notation keys in the raw response. The SDK still wraps the result in a `ShapedModel` β€” access nested fields via attribute or dict syntax, not dot-notation string keys: ```python contracts = client.list_contracts( shape="key,piid,recipient(display_name,uei)", flat=True ) for contract in contracts.results: # Attribute access print(contract.recipient.display_name) # Dict access (nested, not flat string keys) print(contract['recipient']['display_name']) ``` ### Webhook Tooling The SDK ships first-class tooling for **building and testing webhook integrations against the Tango API** β€” including signing helpers, a local receiver, and a command-line tool covering the full lifecycle: ```bash pip install 'tango-python[webhooks]' ``` This adds a `tango` console script with subcommands for the full webhook lifecycle: ```bash # Discover what's available tango webhooks list-event-types tango webhooks fetch-sample --event-type entities.updated # Local development tango webhooks listen --port 8011 --secret $SECRET # receiver tango webhooks simulate --secret $SECRET --event-type entities.updated # sign + print tango webhooks simulate --secret $SECRET --event-type entities.updated \ --to http://127.0.0.1:8011/tango/webhooks # also POST # Manage delivery endpoints tango webhooks endpoints create|list|get|delete # Force a real test delivery from Tango tango webhooks trigger ``` The signing helpers (`verify_signature`, `generate_signature`) are pure stdlib and importable from the default install β€” your receiver code doesn't need the extra: ```python from tango.webhooks import verify_signature if not verify_signature(raw_body, secret, request.headers.get("X-Tango-Signature")): return 401, "invalid signature" ``` For the full guide β€” workflow, CLI reference, and programmatic patterns for pytest fixtures β€” see [`docs/WEBHOOKS.md`](webhooks.md). ### Type Hints with IDE Support Import TypedDict types for IDE autocomplete: ```python from tango import TangoClient, ShapeConfig from tango.shapes import ContractMinimalShaped client = TangoClient(api_key="your-api-key") contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL) # Type hint enables IDE autocomplete contract: ContractMinimalShaped = contracts.results[0] print(contract["piid"]) # IDE knows this field exists print(contract["recipient"]["display_name"]) # Nested fields too ``` ## Development This project uses [uv](https://docs.astral.sh/uv/) for dependency management and tooling. ### Setup ```bash # Clone the repository git clone https://github.com/makegov/tango-python.git cd tango-python # Install dependencies with uv uv sync --all-extras # Or install dev dependencies only uv sync --group dev ``` ### Testing The SDK includes a comprehensive test suite with: - **Unit tests** - Fast tests for core functionality - **Integration tests** - Real API validation using VCR.py cassettes ```bash # Run all tests uv run pytest # Run only unit tests uv run pytest tests/ -m "not integration" # Run only integration tests uv run pytest tests/integration/ # Run integration tests with live API (requires TANGO_API_KEY) export TANGO_API_KEY=your-api-key export TANGO_USE_LIVE_API=true uv run pytest tests/integration/ # Refresh cassettes with fresh API responses export TANGO_API_KEY=your-api-key export TANGO_REFRESH_CASSETTES=true uv run pytest tests/integration/ ``` See [tests/integration/README.md](https://github.com/makegov/tango-python/blob/main/tests/integration/README.md) for detailed testing documentation. ### Code Quality ```bash # Format code uv run ruff format tango/ # Lint code uv run ruff check tango/ # Type checking uv run mypy tango/ # Run all checks uv run ruff format tango/ && uv run ruff check tango/ && uv run mypy tango/ ``` ### Project Structure ``` tango-python/ β”œβ”€β”€ tango/ # Main SDK package β”‚ β”œβ”€β”€ __init__.py # Public API exports β”‚ β”œβ”€β”€ client.py # TangoClient implementation β”‚ β”œβ”€β”€ models.py # Data models and shape configs β”‚ β”œβ”€β”€ exceptions.py # Exception classes β”‚ └── shapes/ # Dynamic model system β”‚ β”œβ”€β”€ __init__.py # Shapes package exports β”‚ β”œβ”€β”€ parser.py # Shape string parser β”‚ β”œβ”€β”€ generator.py # TypedDict generator β”‚ β”œβ”€β”€ factory.py # Instance factory β”‚ β”œβ”€β”€ schema.py # Schema registry β”‚ β”œβ”€β”€ explicit_schemas.py # Predefined schemas (Contract, Entity, Grant, etc.) β”‚ β”œβ”€β”€ models.py # Shape specification models β”‚ └── types.py # TypedDict exports β”œβ”€β”€ tests/ # Test suite β”‚ β”œβ”€β”€ __init__.py β”‚ β”œβ”€β”€ conftest.py # Pytest configuration β”‚ β”œβ”€β”€ test_client.py # Unit tests for client β”‚ β”œβ”€β”€ test_models.py # Model tests β”‚ β”œβ”€β”€ test_shapes.py # Shape system tests β”‚ β”œβ”€β”€ cassettes/ # VCR.py HTTP cassettes β”‚ └── integration/ # Integration tests β”‚ β”œβ”€β”€ __init__.py β”‚ β”œβ”€β”€ README.md # Integration test docs β”‚ β”œβ”€β”€ conftest.py # Integration test fixtures β”‚ β”œβ”€β”€ validation.py # Validation utilities β”‚ β”œβ”€β”€ test_agencies_integration.py β”‚ β”œβ”€β”€ test_contracts_integration.py β”‚ β”œβ”€β”€ test_entities_integration.py β”‚ β”œβ”€β”€ test_forecasts_integration.py β”‚ β”œβ”€β”€ test_grants_integration.py β”‚ β”œβ”€β”€ test_naics_integration.py β”‚ β”œβ”€β”€ test_notices_integration.py β”‚ β”œβ”€β”€ test_offices_integration.py β”‚ β”œβ”€β”€ test_opportunities_integration.py β”‚ β”œβ”€β”€ test_organizations_integration.py β”‚ β”œβ”€β”€ test_otas_otidvs_integration.py β”‚ β”œβ”€β”€ test_protests_integration.py β”‚ β”œβ”€β”€ test_reference_data_integration.py β”‚ β”œβ”€β”€ test_subawards_integration.py β”‚ β”œβ”€β”€ test_vehicles_idvs_integration.py β”‚ └── test_edge_cases_integration.py β”œβ”€β”€ docs/ # Documentation β”‚ β”œβ”€β”€ API_REFERENCE.md # Complete API reference β”‚ β”œβ”€β”€ DEVELOPERS.md # Developer guide β”‚ β”œβ”€β”€ SHAPES.md # Shape system guide β”‚ └── quick_start.ipynb # Interactive quick start β”œβ”€β”€ scripts/ # Utility scripts β”‚ β”œβ”€β”€ README.md β”‚ β”œβ”€β”€ check_filter_shape_conformance.py # Filter + shape conformance (CI) β”‚ β”œβ”€β”€ fetch_api_schema.py β”‚ β”œβ”€β”€ generate_schemas_from_api.py β”‚ └── pr_review.py # PR validation (lint, types, tests, conformance) β”œβ”€β”€ pyproject.toml # Project configuration β”œβ”€β”€ uv.lock # Dependency lock file β”œβ”€β”€ LICENSE # MIT License β”œβ”€β”€ CHANGELOG.md # Version history └── README.md # This file ``` ## Documentation - [Shape System Guide](shapes.md) - Comprehensive guide to response shaping - [API Reference](api-reference.md) - Detailed API documentation - [Developer Guide](https://github.com/makegov/tango-python/blob/main/docs/DEVELOPERS.md) - Technical documentation for developers - [Webhooks Guide](webhooks.md) - Workflow, CLI reference, and programmatic patterns for webhook integrations - [Quick Start Notebook](https://github.com/makegov/tango-python/blob/main/docs/quick_start.ipynb) - Interactive Jupyter notebook with examples ## Requirements - Python 3.12 or higher - httpx >= 0.27.0 ## License MIT License - see [LICENSE](https://github.com/makegov/tango-python/blob/main/LICENSE) for details. ## Support For questions, issues, or feature requests: - **Email**: [tango@makegov.com](mailto:tango@makegov.com) - **Issues**: [GitHub Issues](https://github.com/makegov/tango-python/issues) - **Documentation**: [https://docs.makegov.com/tango-python](https://docs.makegov.com/tango-python) ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Run lint and format: `uv run ruff format tango/ && uv run ruff check tango/` 4. Run type checking: `uv run mypy tango/` 5. Run tests: `uv run pytest` 6. (Optional) Run [filter and shape conformance](https://github.com/makegov/tango-python/blob/main/scripts/README.md#filter-and-shape-conformance) if you have the tango API manifest; CI will run it on push/PR 7. Commit your changes (`git commit -m 'Add amazing feature'`) 8. Push to the branch (`git push origin feature/amazing-feature`) 9. Open a Pull Request For a single command that runs formatting, linting, type checking, and tests (and conformance when the manifest is present), use: `uv run python scripts/pr_review.py --mode full` --- # Pagination The SDK uses two pagination strategies depending on the endpoint. For per-method pagination parameters, see [`API_REFERENCE.md`](api-reference.md). This guide is the conceptual overview and iteration patterns. ## Page-Based Pagination Most endpoints use traditional page-based pagination with `page` and `limit` parameters. ```python from tango import TangoClient client = TangoClient() # First page resp = client.list_entities(search="Booz Allen", limit=25) print(f"Total: {resp.count}") print(f"This page: {len(resp.results)}") print(f"Next: {resp.next}") # Next page resp2 = client.list_entities(search="Booz Allen", limit=25, page=2) ``` ### Iterating All Pages ```python page = 1 all_results = [] while True: resp = client.list_entities(search="Booz Allen", limit=100, page=page) all_results.extend(resp.results) if not resp.next: break page += 1 print(f"Fetched {len(all_results)} of {resp.count} entities") ``` **Endpoints using page-based pagination:** entities, forecasts, opportunities, notices, grants, protests, subawards, vehicles, vehicle awardees, organizations, GSA eLibrary contracts, IT Dashboard investments, agencies, offices, business types, NAICS, webhook subscriptions, webhook endpoints. ## Cursor-Based Pagination High-volume award endpoints use cursor-based (keyset) pagination for better performance on large datasets. Instead of a page number, you pass a `cursor` token from the previous response. ```python from urllib.parse import parse_qs, urlparse from tango import TangoClient client = TangoClient() # First page resp = client.list_contracts(limit=25, sort="award_date", order="desc") print(f"Total: {resp.count}") # Get cursor from the next URL if resp.next: qs = parse_qs(urlparse(resp.next).query) cursor = qs.get("cursor", [None])[0] # Fetch next page resp2 = client.list_contracts( limit=25, cursor=cursor, sort="award_date", order="desc", ) ``` ### Iterating All Pages ```python from urllib.parse import parse_qs, urlparse all_results = [] cursor = None while True: resp = client.list_contracts( keyword="cloud", limit=100, cursor=cursor, sort="award_date", order="desc", ) all_results.extend(resp.results) if not resp.next: break qs = parse_qs(urlparse(resp.next).query) cursor = qs.get("cursor", [None])[0] print(f"Fetched {len(all_results)} of {resp.count} contracts") ``` **Endpoints using cursor-based pagination:** contracts, IDVs, IDV awards, IDV child IDVs, IDV transactions, OTAs, OTIDVs. ## PaginatedResponse All list methods return a `PaginatedResponse` object: | Field | Type | Description | |---|---|---| | `count` | `int` | Total number of results available | | `next` | `str \| None` | Full URL for the next page, or `None` | | `previous` | `str \| None` | Full URL for the previous page, or `None` | | `results` | `list[T]` | List of results for this page | | `cursor` | `str \| None` | Cursor token (cursor-based endpoints only) | | `page_metadata` | `dict \| None` | Optional additional page metadata | --- # Response Shaping Guide Response shaping lets you control which fields the API returns, making your requests faster and more efficient. Instead of receiving hundreds of fields you don't need, you specify exactly what you want. **See also:** [API Reference](api-reference.md) for method parameters and [ShapeConfig (predefined shapes)](api-reference.md#shapeconfig-predefined-shapes); [Developer Guide](https://github.com/makegov/tango-python/blob/main/docs/DEVELOPERS.md) for dynamic models and maintainer conformance. ## Why Use Response Shaping? **Performance Benefits:** - **60-80% smaller responses** - Faster downloads, lower bandwidth costs - **Faster API responses** - Less data to process and serialize - **Clearer code** - Explicitly state what data you're using **Example:** A full contract response is ~2.4 MB. With shaping, you can reduce it to 320 KB (87% smaller) while getting all the data you actually need. ## Quick Start ```python from tango import TangoClient client = TangoClient(api_key="your-api-key") # Without shaping - returns ALL fields (slower, larger) contracts = client.list_contracts(limit=10) # With shaping - returns only what you specify (faster, smaller) contracts = client.list_contracts( limit=10, shape="key,piid,recipient(display_name),total_contract_value" ) # Or use a predefined shape constant from tango import ShapeConfig contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10) # Access the data for contract in contracts.results: print(f"{contract['piid']}: {contract['recipient']['display_name']}") ``` ## Predefined shapes (ShapeConfig) Instead of writing shape strings by hand, you can use the SDK’s predefined constants. Each list/get method has a default minimal shape when you omit `shape`; you can also pass a constant explicitly. ```python from tango import TangoClient, ShapeConfig client = TangoClient() # These are equivalent (list_contracts defaults to CONTRACTS_MINIMAL) contracts = client.list_contracts(limit=10) contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10) # Other resources entities = client.list_entities(shape=ShapeConfig.ENTITIES_MINIMAL) idvs = client.list_idvs(shape=ShapeConfig.IDVS_MINIMAL) grants = client.list_grants(shape=ShapeConfig.GRANTS_MINIMAL) ``` **Available constants:** Contracts (`CONTRACTS_MINIMAL`), Entities (`ENTITIES_MINIMAL`, `ENTITIES_COMPREHENSIVE`), Forecasts, Opportunities, Notices, Grants, IDVs, Vehicles (`VEHICLES_MINIMAL`, `VEHICLES_COMPREHENSIVE`, `VEHICLE_AWARDEES_MINIMAL`, `VEHICLE_ORDERS_MINIMAL`), Organizations, OTAs, OTIDVs, Subawards. See [API Reference – ShapeConfig](api-reference.md#shapeconfig-predefined-shapes) for the full table and which method uses which constant. > **Vehicles `metrics(*)` expansion:** The vehicles surface bundles 12 computed metrics under a single `metrics(*)` expansion (e.g. `award_concentration_hhi`, `competed_rate`, `top_recipient_share`). It is included in `VEHICLES_COMPREHENSIVE` by default. The `agency_details`, `competition_details`, and `opportunity` shape entries are deprecated and emit `DeprecationWarning` if requested explicitly. ## Basic Shaping ### Simple Fields List the fields you want, separated by commas: ```python # Just the basics contracts = client.list_contracts( shape="key,piid,description,award_date", limit=10 ) # Access the fields for contract in contracts.results: print(f"{contract['piid']}: {contract['description']}") print(f"Date: {contract['award_date']}") ``` ### Nested Fields Use parentheses to select fields from nested objects: ```python # Get recipient information contracts = client.list_contracts( shape="key,piid,recipient(display_name,uei,cage_code)", limit=10 ) for contract in contracts.results: recipient = contract['recipient'] print(f"Recipient: {recipient['display_name']}") print(f"UEI: {recipient['uei']}") ``` ### Multiple Levels You can nest as deeply as needed. Contract location information is on `place_of_performance` (not nested inside `recipient`): ```python # Get place of performance details contracts = client.list_contracts( shape="key,recipient(display_name),place_of_performance(city_name,state_code,zip_code)", limit=10 ) for contract in contracts.results: location = contract['place_of_performance'] print(f"{location['city_name']}, {location['state_code']} {location['zip_code']}") ``` ## Common Use Cases ### 1. Quick Lists and Dropdowns When you just need basic info for a list or dropdown: ```python # Minimal data for a dropdown contracts = client.list_contracts( shape="key,piid,recipient(display_name)", limit=100 ) # Build a dropdown for contract in contracts.results: print(f"{contract['piid']} - {contract['recipient']['display_name']}") ``` ### 2. Data Analysis When analyzing contracts, focus on the metrics: ```python # Get financial and timing data contracts = client.list_contracts( shape="key,piid,award_date,fiscal_year,total_contract_value,obligated", awarding_agency="GSA", limit=1000 ) # Analyze total_value = sum(c.get('total_contract_value', 0) or 0 for c in contracts.results) print(f"Total contract value: ${total_value:,.2f}") ``` ### 3. Geographic Analysis When you need location data: ```python # Get place of performance details # Note: use city_name (not city); congressional_district is not a shape field contracts = client.list_contracts( shape="key,piid,place_of_performance(city_name,state_code)", limit=100 ) # Group by state from collections import Counter states = Counter(c['place_of_performance']['state_code'] for c in contracts.results if c.get('place_of_performance') and c['place_of_performance'].get('state_code')) print(f"Top states: {states.most_common(5)}") ``` ### 4. Vendor Research When researching vendors and recipients: ```python # Get detailed vendor information # Note: entity physical_address uses 'city' and 'state_or_province_code' # business_types is a list of dicts with 'code' and 'description' entities = client.list_entities( shape="uei,legal_business_name,dba_name,business_types,physical_address(city,state_or_province_code)", limit=50 ) for entity in entities.results: print(f"{entity['legal_business_name']}") print(f"Business Types: {', '.join(bt['code'] for bt in entity.get('business_types', []))}") if entity.get('physical_address'): addr = entity['physical_address'] print(f"Location: {addr.get('city')}, {addr.get('state_or_province_code')}") ``` ### 5. Agency Research When analyzing agency activity: ```python # Get agency and classification details # Note: use awarding_office (not awarding_agency) for agency name/code sub-fields contracts = client.list_contracts( shape="key,awarding_office(agency_name,agency_code),naics(code,description),psc(code,description),total_contract_value", fiscal_year=2024, limit=500 ) # Analyze by agency from collections import defaultdict by_agency = defaultdict(float) for contract in contracts.results: if contract.get('awarding_office'): agency = contract['awarding_office']['agency_name'] value = float(contract.get('total_contract_value', 0) or 0) by_agency[agency] += value # Top agencies by value top_agencies = sorted(by_agency.items(), key=lambda x: x[1], reverse=True)[:10] for agency, value in top_agencies: print(f"{agency}: ${value:,.2f}") ``` ## Advanced Techniques ### Using Wildcards Get all fields from a nested object with `*`: ```python # Get all recipient fields contracts = client.list_contracts( shape="key,piid,recipient(*)", limit=10 ) # All recipient fields are now available for contract in contracts.results: recipient = contract['recipient'] # Has all fields: display_name, uei, cage_code, legal_business_name, etc. ``` ### Flattening Responses Convert nested structures to flat keys with dot notation: ```python # Flatten nested objects contracts = client.list_contracts( shape="key,piid,recipient(display_name,uei)", flat=True, limit=10 ) # Fields are now flattened for contract in contracts.results: print(contract['piid']) print(contract['recipient.display_name']) print(contract['recipient.uei']) ``` ## Best Practices ### 1. Start Minimal, Add as Needed Start with the minimum fields you need, then add more: ```python # Start here shape = "key,piid,recipient(display_name)" # Add more as you need them shape = "key,piid,recipient(display_name,uei),total_contract_value" # Keep adding shape = "key,piid,recipient(display_name,uei),total_contract_value,award_date,fiscal_year" ``` ### 2. Use Shapes for Large Queries The bigger the query, the more important shaping becomes: ```python # Small query - shaping optional contracts = client.list_contracts(limit=5) # Medium query - shaping recommended contracts = client.list_contracts( shape="key,piid,recipient(display_name),total_contract_value", limit=100 ) # Large query - shaping highly recommended contracts = client.list_contracts( shape="key,piid,recipient(display_name),total_contract_value", limit=1000 ) ``` ### 3. Reuse Common Shapes Define shapes as constants for reuse: ```python # Define your common shapes SHAPES = { 'list': "key,piid,recipient(display_name),total_contract_value", 'detail': "key,piid,description,recipient(*),awarding_office(*),total_contract_value,award_date", 'analysis': "key,fiscal_year,total_contract_value,obligated,award_date", 'geographic': "key,piid,place_of_performance(city_name,state_code)" } # Use them contracts = client.list_contracts(shape=SHAPES['list'], limit=100) contract_detail = client.list_contracts(shape=SHAPES['detail'], limit=1) ``` ### 4. Document Your Shapes When using custom shapes in production, document why you chose those fields: ```python # Dashboard summary shape # - key: Contract identifier # - piid: Display to users # - recipient.display_name: Main label # - total_contract_value: Summary metric DASHBOARD_SHAPE = "key,piid,recipient(display_name),total_contract_value" contracts = client.list_contracts(shape=DASHBOARD_SHAPE, limit=50) ``` ## Field Reference ### Common Contract Fields **Identifiers:** - `key` - Unique contract identifier - `piid` - Procurement Instrument Identifier - `award_id` - Award identifier **Basic Info:** - `description` - Contract description - `award_date` - Date awarded - `fiscal_year` - Fiscal year **Financial:** - `total_contract_value` - Total contract value - `obligated` - Total obligated amount (note: field is `obligated`, not `total_obligated`) - `award_amount` - Initial award amount **Parties:** - `recipient(...)` - The vendor/recipient - `awarding_agency(...)` - The agency awarding the contract - `funding_agency(...)` - The agency funding the contract **Classification:** - `naics(code,description)` - Industry classification - `psc(code,description)` - Product/Service code **Location:** - `place_of_performance(...)` - Where work is performed - `recipient_location(...)` - Vendor location ### Common Entity Fields **Basic:** - `uei` - Unique Entity Identifier - `cage_code` - Commercial and Government Entity code - `legal_business_name` - Official business name - `display_name` - Display name - `dba_name` - Doing Business As name **Classification:** - `business_types` - Array of business type codes - `primary_naics` - Primary NAICS code - `naics_codes` - All NAICS codes **Contact:** - `email_address` - Email - `entity_url` - Website - `physical_address(...)` - Physical address - `mailing_address(...)` - Mailing address **Financial:** - `federal_obligations(*)` - Expansion for total/active federal obligations ## Performance Comparison Here's what you can expect when using shapes: | Use Case | Fields Returned | Payload Size | vs. Full Response | |----------|----------------|--------------|-------------------| | Full response | ~200 fields | 2.4 MB | Baseline | | Dropdown | 3-4 fields | 180 KB | 92% smaller | | List view | 6-8 fields | 320 KB | 87% smaller | | Detail view | 20-30 fields | 780 KB | 68% smaller | | Analysis | 8-10 fields | 250 KB | 90% smaller | ## Troubleshooting ### Fields Not Appearing If fields aren't showing up in the response: 1. **Check your shape syntax** - Make sure parentheses match and commas are correct 2. **Field doesn't exist** - The field might not exist for that record 3. **Typo** - Double-check field names (they're case-sensitive) ```python # ❌ Wrong shape = "key,piid recipient(display_name)" # Missing comma # βœ… Correct shape = "key,piid,recipient(display_name)" ``` ### Unexpected Structure If the structure isn't what you expected: ```python # Shape specifies nested structure contracts = client.list_contracts( shape="key,recipient(display_name,uei)", limit=1 ) # Access nested fields contract = contracts.results[0] print(contract['recipient']['display_name']) # Nested access print(contract['recipient']['uei']) # Use .get() for safety display_name = contract.get('recipient', {}).get('display_name', 'Unknown') ``` ## Examples by Resource Type ### Contracts ```python # Minimal for lists "key,piid,recipient(display_name),total_contract_value" # For analysis (use 'obligated', not 'total_obligated') "key,fiscal_year,award_date,total_contract_value,obligated,naics(code)" # For geographic analysis (use city_name; congressional_district not available) "key,piid,place_of_performance(city_name,state_code)" # Full detail (use awarding_office for agency breakdown) "key,piid,description,recipient(*),awarding_office(*),total_contract_value,award_date,naics(*),psc(*)" ``` ### Entities ```python # Minimal for lookups "uei,legal_business_name,cage_code,business_types" # For vendor research (entity physical_address uses state_or_province_code, not state_code) "uei,legal_business_name,dba_name,business_types,physical_address(city,state_or_province_code),primary_naics" # Full profile "uei,legal_business_name,dba_name,cage_code,business_types,physical_address(*),email_address,entity_url" ``` ### Forecasts ```python # Minimal "id,title,anticipated_award_date,fiscal_year" # With classification "id,title,anticipated_award_date,fiscal_year,naics_code,status" ``` ### Opportunities ```python # Minimal "opportunity_id,title,solicitation_number,response_deadline" # With details "opportunity_id,title,solicitation_number,description,response_deadline,active,naics_code,psc_code" ``` ## Next Steps - **Try the examples** - Copy and paste these examples to get started - **Experiment** - Start with minimal shapes and add fields as needed - **Profile your queries** - Use network tools to see the size difference - **Define patterns** - Create reusable shapes for your common queries For more help, see: - [API Reference](api-reference.md) - Method parameters, [ShapeConfig table](api-reference.md#shapeconfig-predefined-shapes), and field context - [Developer Guide](https://github.com/makegov/tango-python/blob/main/docs/DEVELOPERS.md) - Dynamic models, predefined shapes in depth, and SDK conformance (for maintainers) - [Quick Start Guide](https://github.com/makegov/tango-python/blob/main/docs/quick_start.ipynb) - Interactive examples --- # Webhooks Guide This guide covers everything `tango-python` provides for **building, testing, and operating webhook integrations against the Tango API**: signing helpers, a local receiver, a command-line tool, and management commands for the underlying endpoints and alerts. If you only need the SDK method signatures, see [`API_REFERENCE.md` Β§ Webhooks](api-reference.md#webhooks). For the API-level contract (signing scheme, event taxonomy, retry behavior), see the [Tango Webhooks Partner Guide](https://docs.makegov.com/webhooks-user-guide/). --- ## Contents - [Install](#install) - [Concepts in 60 seconds](#concepts-in-60-seconds) - [Quickstart: zero to receiving](#quickstart-zero-to-receiving) - [CLI reference](#cli-reference) - [`tango webhooks listen`](#tango-webhooks-listen) - [`tango webhooks simulate`](#tango-webhooks-simulate) - [`tango webhooks trigger`](#tango-webhooks-trigger) - [`tango webhooks fetch-sample`](#tango-webhooks-fetch-sample) - [`tango webhooks list-event-types`](#tango-webhooks-list-event-types) - [`tango webhooks endpoints`](#tango-webhooks-endpoints) - [Programmatic use](#programmatic-use) - [Signature verification in your handler](#signature-verification-in-your-handler) - [`WebhookReceiver` in pytest fixtures](#webhookreceiver-in-pytest-fixtures) - [`simulate.sign` and `simulate.deliver`](#simulatesign-and-simulatedeliver) - [Common workflows](#common-workflows) - [Troubleshooting](#troubleshooting) --- ## Install The signing helpers ship with the default install: ```bash pip install tango-python ``` The CLI (`tango webhooks ...`) and the local receiver class are gated behind an optional extra: ```bash pip install 'tango-python[webhooks]' ``` This adds [`click`](https://palletsprojects.com/projects/click) as a runtime dependency. The base SDK install stays unchanged. After installing the extra, the `tango` console script is on your `PATH`: ```bash tango webhooks --help ``` --- ## Concepts in 60 seconds Tango webhooks have two pieces of state: | Concept | What it is | Tango term | |---|---|---| | **Endpoint** | The URL Tango POSTs to, plus a generated signing secret | `WebhookEndpoint` | | **Alert** | A saved-search filter saying *which matches* to deliver | `WebhookAlert` (filter subscription) | | **Delivery** | A single signed POST Tango makes when a matching event fires | (the request itself) | A typical setup: 1. **Create an endpoint** (`POST /api/webhooks/endpoints/`) with the public URL of your handler. Tango returns a `secret` β€” save it; it's used to sign every delivery. 2. **Create one or more alerts** (`POST /api/webhooks/alerts/`) describing the saved-search matches you want delivered (e.g. opportunities matching `naics=541511`). Each alert maps to one of five `alerts.*.match` event types. 3. **Tango POSTs** to your endpoint when matching events fire. The body is JSON; the header `X-Tango-Signature: sha256=` is the HMAC-SHA256 of the raw body bytes keyed by your endpoint's secret. 4. **Your handler verifies the signature**, parses the body, and acts on it. --- ## Quickstart: zero to receiving Assumes you have a `TANGO_API_KEY` and want to receive entity-update webhooks for a specific UEI. ### 1. See what you can subscribe to ```bash export TANGO_API_KEY=... tango webhooks list-event-types # alerts.opportunity.match New/updated opportunity matched a saved alert # alerts.contract.match New/updated contract matched a saved alert # alerts.entity.match Entity matched a saved alert # alerts.grant.match Grant matched a saved alert # alerts.forecast.match Forecast matched a saved alert # alerts.exclusion.match SAM.gov exclusion matched a saved alert # alerts.dibbs_rfq.match DLA DIBBS RFQ matched a saved alert # alerts.dibbs_rfp.match DLA DIBBS RFP matched a saved alert # alerts.sled_opportunity.match State/local/education solicitation matched a saved alert # alerts.contract_appeal.match CBCA/ASBCA appeal decision matched a saved alert # alerts.federal_register.match Federal Register document matched a saved alert # alerts.ebuy_request.match GSA eBuy request matched a saved alert ``` This list is served by the API, so it is always current β€” the SDK does not hardcode event types anywhere. Always trust `list-event-types` over any list written down here. Two things that surprise people: - **DIBBS awards are not alertable.** There is no `alerts.dibbs_award.match`; only RFQs and RFPs emit alerts. - **Nothing fires when a record merely lapses β€” except SLED.** An exclusion reaching its termination date, or an RFQ/RFP passing its close date, emits no event: open/closed and in-force are derived at query time, so no stored row changes. Poll with `list_exclusions(active=...)` / `list_dibbs_rfqs(open=...)` if you need to observe expiry. `sled_opportunity` is the exception, and the only one. A SLED solicitation's liveness is a stored `status` column that Tango recomputes every fifteen minutes rather than deriving per request, so a deadline passing **is** a write and `alerts.sled_opportunity.match` can follow it. There is no `sled_forecast` query type β€” a forecast has no deadline, so nothing transitions β€” and SLED revisions and attachments are not separately alertable: subscribe to `sled_opportunity` and filter on `change_seen_after` or `revision_kind`. ### 2. See what a payload looks like ```bash tango webhooks fetch-sample --event-type alerts.entity.match ``` Prints the canonical JSON shape Tango will deliver. No POST, no signature β€” just the body. ### 3. Run a local receiver In one shell, start a listener with a chosen secret: ```bash export TANGO_WEBHOOK_SECRET=dev_secret tango webhooks listen --port 8011 ``` In another shell, drive it with the canonical sample, signed locally: ```bash tango webhooks simulate \ --secret $TANGO_WEBHOOK_SECRET \ --event-type alerts.entity.match \ --to http://127.0.0.1:8011/tango/webhooks ``` The listener should print a `verified` delivery with the alerts.entity.match body. You now have a feedback loop: edit your handler, re-run `simulate`, see the result. ### 4. Wire up the real Tango β†’ your handler path When you're ready for end-to-end testing against Tango itself, expose your local listener via a tunnel (`ngrok http 8011`, `cloudflared tunnel`, etc.) and register that public URL with Tango, then create an alert via the SDK: ```bash # Use the public URL the tunnel gave you. tango webhooks endpoints create --name dev --url https://.ngrok.io/tango/webhooks # Save the `secret` from the response β€” that's what your handler uses to verify. ``` ```python # Create an alert (filter subscription) via the SDK from tango import TangoClient client = TangoClient() client.create_webhook_alert( name="watch UEI ABC123", query_type="entity", filters={"uei": "ABC123"}, ) ``` To force a real test delivery from Tango (without waiting for an actual event): ```bash tango webhooks trigger ``` You should see a `verified` delivery in your local listener with the signature value generated by Tango β€” not by `simulate`. --- ## CLI reference All commands live under `tango webhooks`. Options that talk to Tango's API (`--api-key`, `--base-url`) read `TANGO_API_KEY` and `TANGO_BASE_URL` if not passed explicitly. ### `tango webhooks listen` Run a local HTTP receiver. Verifies signatures, optionally forwards each delivery downstream, prints a one-line summary plus the JSON body for each delivery. ```bash tango webhooks listen \ --port 8011 \ --host 127.0.0.1 \ --path /tango/webhooks \ --secret $TANGO_WEBHOOK_SECRET \ --forward-to http://127.0.0.1:4242/wh ``` Options: - `--port` (default `8011`) - `--host` (default `127.0.0.1` β€” loopback only, by design) - `--path` (default `/tango/webhooks`) - `--secret` / `TANGO_WEBHOOK_SECRET` β€” if empty, signatures are not verified (the listener accepts everything; useful for inspecting payloads when you don't have the right secret yet) - `--forward-to URL` β€” mirror each delivery to a downstream URL, preserving body bytes and the `X-Tango-Signature` header - `--require-signature / --allow-unsigned` β€” override the default policy (default: require when `--secret` is set) Press Ctrl+C to stop. Rejected (signature-mismatch) deliveries are still printed with the label `UNVERIFIED` so you can debug what arrived. ### `tango webhooks simulate` Sign a payload locally with the same scheme Tango uses, then either print the signed request or POST it to a receiver. **Without `--to`** β€” just print the headers + body a real Tango delivery would have: ```bash tango webhooks simulate --secret dev_secret --event-type alerts.entity.match ``` Output includes `delivered: false`, the headers (`Content-Type`, `X-Tango-Signature`), and the JSON payload. **With `--to`** β€” also POST the signed body to a receiver: ```bash tango webhooks simulate \ --secret dev_secret \ --event-type alerts.entity.match \ --to http://127.0.0.1:8011/tango/webhooks ``` Output includes `delivered: true`, the receiver's status code, and the receiver's response body. Three sources for the payload (mutually exclusive): | Flag | Source | When to use | |---|---|---| | `--event-type X` | Fetches the canonical sample for `X` from Tango | You want a realistic body without setting up an alert | | `--payload-file PATH` | Reads a JSON file | You're testing a specific shape (regression, edge case) | | *(neither)* | A built-in placeholder envelope | Smoke-testing the wiring | ### `tango webhooks trigger` Ask Tango to send a real test delivery to your configured endpoint. Wraps `POST /api/webhooks/endpoints/test-delivery/`. Requires `--api-key`. ```bash tango webhooks trigger tango webhooks trigger --endpoint-id ``` Output is JSON: `success`, `status_code` (the HTTP code Tango got from your endpoint), `response_time_ms`, `endpoint_url`, `message`, `error`. Exit code is non-zero if delivery failed. ### `tango webhooks fetch-sample` Print the canonical sample payload for one event type, or the full mapping if `--event-type` is omitted. Wraps `GET /api/webhooks/endpoints/sample-payload/`. Read-only. ```bash tango webhooks fetch-sample --event-type alerts.entity.match tango webhooks fetch-sample # all event types ``` ### `tango webhooks list-event-types` List every event type Tango supports with a one-line description. ```bash tango webhooks list-event-types ``` ### `tango webhooks endpoints` Manage **where Tango delivers**. ```bash tango webhooks endpoints list [--page N] [--limit N] tango webhooks endpoints get ENDPOINT_ID tango webhooks endpoints create --name NAME --url URL [--inactive] tango webhooks endpoints delete ENDPOINT_ID [--yes] ``` `create` returns the generated `secret` once β€” save it. `--name` is required and must be unique per user (uniqueness is enforced on `(user, name)`, so you can have multiple endpoints with distinct names). `delete` prompts for confirmation; `--yes` skips. `--inactive` registers the endpoint disabled (no deliveries until you re-enable it). ### Managing alerts Alerts (filter subscriptions) are the canonical way to control what Tango delivers. There is no CLI subgroup for them β€” use the SDK directly: ```python from tango import TangoClient client = TangoClient() client.list_webhook_alerts() client.get_webhook_alert("ALERT_UUID") client.create_webhook_alert( name="watch UEI ABC123", query_type="entity", filters={"uei": "ABC123"}, ) client.update_webhook_alert("ALERT_UUID", name="Renamed") client.delete_webhook_alert("ALERT_UUID") ``` For multi-endpoint accounts, pass `endpoint=` to `create_webhook_alert` to pin which endpoint the alert delivers to. --- ## Programmatic use The CLI is built on top of small importable pieces. You can use them directly in your own code β€” most usefully, in tests. ### Signature verification in your handler `verify_signature` is pure stdlib (no SDK dependencies, no `click`). Call it on the raw request body, not on a re-serialized parsed body β€” the HMAC is computed over exact bytes. ```python from tango.webhooks import verify_signature # In your Flask / FastAPI / Django / Starlette / whatever handler: def handle_webhook(request): body = request.body # raw bytes signature = request.headers.get("X-Tango-Signature") if not verify_signature(body, secret=ENDPOINT_SECRET, signature_header=signature): return 401, {"error": "invalid_signature"} payload = json.loads(body) # ... act on the events ... return 200, {"ok": True} ``` `verify_signature` returns `False` for missing/empty/malformed headers β€” it never raises. Comparison is constant-time (`hmac.compare_digest`). ### `WebhookReceiver` in pytest fixtures The CLI's `listen` command is a thin wrapper around `tango.webhooks.WebhookReceiver`, which is a context-manager-friendly local HTTP server. Use it directly in tests to verify your code emits webhook calls correctly, or to drive your handler with realistic deliveries. ```python from tango import WebhookReceiver # WebhookReceiver is exported from the top-level tango package from tango.webhooks import generate_signature, verify_signature import httpx def test_my_handler_processes_entity_update(): with WebhookReceiver(secret="test_secret").run() as rx: # Trigger whatever in your code-under-test should send a webhook # (e.g. a publisher, or in this case a manual POST). body = b'{"events":[{"event_type":"alerts.entity.match","alert_id":"ABC"}]}' sig = generate_signature(body, "test_secret") # generate_signature returns the wire form ("sha256=") β€” assign # directly to the header without wrapping. httpx.post(rx.url, content=body, headers={"X-Tango-Signature": sig}) assert len(rx.deliveries) == 1 assert rx.deliveries[0].verified assert rx.deliveries[0].body_json["events"][0]["uei"] == "ABC" ``` `WebhookReceiver` options: - `secret: str = ""` β€” shared secret. Empty means "don't verify." - `path: str = "/tango/webhooks"` β€” URL path to accept. - `host: str = "127.0.0.1"` / `port: int = 0` β€” bind address. `0` lets the OS pick a free port. - `forward_to: str | None = None` β€” mirror each delivery to a downstream URL. - `max_history: int = 256` β€” cap on the in-memory `deliveries` deque. - `on_delivery: Callable[[Delivery], None] | None = None` β€” fires for every recorded delivery, including signature-failed ones. - `require_signature: bool | None = None` β€” override default (require iff `secret` is set). Each `Delivery` has: `received_at`, `path`, `signature_header`, `body_bytes`, `body_json`, `verified`, `remote_addr`, `forward_status`, `forward_error`. ### `simulate.sign` and `simulate.deliver` `simulate.sign` is the offline counterpart β€” it produces the exact wire form a Tango delivery would have, so you can drive your handler from a unit test: ```python from tango.webhooks import sign signed = sign({"events": [{"event_type": "alerts.entity.match"}]}, secret="s") assert signed.headers["X-Tango-Signature"].startswith("sha256=") # Use `signed.body` as the raw bytes and `signed.headers` directly: response = my_app.test_client().post( "/webhooks", data=signed.body, headers=signed.headers ) ``` `simulate.deliver` does the same but POSTs the result to a URL β€” `WebhookReceiver` works as a target: ```python from tango.webhooks import simulate from tango import WebhookReceiver with WebhookReceiver(secret="s").run() as rx: result = simulate.deliver(target_url=rx.url, payload={...}, secret="s") assert result.status_code == 200 ``` --- ## Common workflows ### "I'm starting fresh β€” set me up to receive entity updates" ```bash export TANGO_API_KEY=... # 1. Confirm event types tango webhooks list-event-types # 2. Stand up a tunnel so Tango can reach you ngrok http 8011 & # 3. Register your endpoint tango webhooks endpoints create --name dev --url https://.ngrok.io/tango/webhooks # (save the `secret` from the response into TANGO_WEBHOOK_SECRET) # 4. Create an alert via the SDK python -c ' from tango import TangoClient TangoClient().create_webhook_alert( name="entities", query_type="entity", filters={"uei": ""} )' # 5. Run the listener pointed at your downstream handler tango webhooks listen --port 8011 --secret $TANGO_WEBHOOK_SECRET \ --forward-to http://localhost:4242/wh # 6. Force a test delivery tango webhooks trigger ``` ### "I want to develop my handler offline" You don't need a Tango account or any tunnel: ```bash # Run the handler however you normally would on, e.g., :4242 tango webhooks listen --port 8011 --secret dev --forward-to http://127.0.0.1:4242/wh # In another shell, drive it. Use Tango-shaped bodies if you have an API key: tango webhooks simulate --secret dev --event-type alerts.entity.match \ --to http://127.0.0.1:8011/tango/webhooks # Or use a custom shape from a file (no API key required): tango webhooks simulate --secret dev --payload-file ./fixtures/edge.json \ --to http://127.0.0.1:8011/tango/webhooks ``` ### "I want to test my handler in CI, no network" In pytest, use `WebhookReceiver` and `simulate.deliver` together β€” both are pure-Python and don't talk to Tango: ```python from tango.webhooks import simulate from tango import WebhookReceiver def test_handler_round_trip(): with WebhookReceiver(secret="s").run() as rx: result = simulate.deliver( target_url=rx.url, payload={"events": [{"event_type": "alerts.entity.match", "alert_id": "X"}]}, secret="s", ) assert result.status_code == 200 assert rx.deliveries[0].verified ``` ### "I need to inspect what bytes Tango actually sends" ```bash tango webhooks simulate --secret $TANGO_WEBHOOK_SECRET --event-type alerts.entity.match # Prints { "delivered": false, "headers": {...}, "sent_payload": {...} } ``` This is the shape your handler will receive β€” including the exact `X-Tango-Signature` value it should verify. --- ## Troubleshooting **Signature always fails.** Verify on raw bytes, not on a re-serialized parsed body. The HMAC is over exact bytes; reformatting whitespace or reordering keys breaks it. Most web frameworks expose the raw body separately from a parsed JSON shortcut β€” use the raw one. **`tango: command not found`.** Install the extra: `pip install 'tango-python[webhooks]'`. The console script is registered only when `click` is available. **Listener prints `WARNING: no --secret provided`.** You started `listen` without `--secret` and without `TANGO_WEBHOOK_SECRET` set. Every delivery will be accepted with `verified=False`. Useful for inspecting payloads when you don't have the secret yet, but unsafe in any shared environment. **`fetch-sample` returns 401.** Set `TANGO_API_KEY` (or pass `--api-key`). `fetch-sample` reads from Tango's API. **`endpoints create` returns 400 or "endpoint already exists".** Endpoint names are unique per user β€” if you've already created one with that `--name`, either pick a different name or use `endpoints list` to find the existing one and reuse it. **`simulate --event-type X` fails with HTTP 4xx.** Tango doesn't recognize the event type. Run `list-event-types` to see the current list. **`trigger` returns `success: false`.** Tango reached your endpoint but got a non-2xx response. Check `endpoint_url` and `response_body` in the output, then look at your handler's logs. --- --- description: "The full Tango webhooks protocol β€” filter subscriptions, payload format, signing, retries, and the circuit breaker β€” for teams building a receiver." tags: [webhooks, api, guide] updated: 2026-10-30 --- # Tango – Webhooks Partner Guide Welcome! This guide walks you through enabling and consuming outbound webhooks from Tango so your application can react to fresh federal-spending data without polling our API. Jump to: - [Examples](#examples) --- ## 1. What you get Tango pushes a JSON payload to your server whenever new data matches a saved filter β€” a **filter alert**. Today this includes: - Awards / contracts - Opportunities - Entities - Grants - Forecasts - Near–real-time: you'll be notified minutes after Tango's ingestion cycle finishes. - Lightweight: one payload lists the IDs that changed and a small summary per match β€” pull full details from the existing REST API as needed. - **Filter-based**: define a saved query (the same filters you'd pass to the API) and receive an event whenever new or updated rows match. - **Reliability features**: automatic circuit breaker pattern for endpoint health management and intelligent retry strategies. > Note (Awards): For correctness, awards webhooks are published **after award bundling/materialization** so a webhook will not arrive before the corresponding award is queryable via the API. ### 1.1 When events are published ("data is ready") We intentionally publish events only once the underlying data is queryable via the API. - **Contracts** (`alerts.contract.match`): published once new contracts are queryable via the API. - **Opportunities** (`alerts.opportunity.match`): published after each opportunities refresh. - **Entities** (`alerts.entity.match`): published after each entities refresh (including DSBS updates). - **Grants** (`alerts.grant.match`): published after each grants refresh. - **Forecasts** (`alerts.forecast.match`): published after each forecasts refresh. - **Exclusions** (`alerts.exclusion.match`): published when a matching SAM.gov exclusion is newly issued, revised, or lifted. - **DIBBS RFQs** (`alerts.dibbs_rfq.match`): published when a matching DIBBS request for quote is newly posted or updated. - **DIBBS solicitations** (`alerts.dibbs_rfp.match`): published when a matching DIBBS solicitation (RFP/IFB) is newly posted or updated. - **eBuy requests** (`alerts.ebuy_request.match`): published when a matching GSA eBuy request under **your own linked Schedule contracts** is newly posted or updated. Matching uses the contract links of the account that owns the webhook endpoint, so an alert never surfaces a request outside them. A request closing does not fire β€” eBuy stops listing it rather than marking it closed. - **State & local solicitations** (`alerts.sled_opportunity.match`): published when a matching SLED solicitation is newly posted, revised, or **closes**. Unlike the resources above, a SLED closing *is* a change to the record β€” `status` is a stored column that Tango recomputes every fifteen minutes β€” so a subscription can follow a deadline passing. - **Contract appeals** (`alerts.contract_appeal.match`): published when a matching CBCA or ASBCA decision is newly listed or changes. Two changes worth knowing: a decision **leaving** a board's listing is a write (`listed` flips to `false`), and so is a decision **gaining its extracted text** β€” so a subscription can follow either, including on plans that cannot read `decision_text` itself. - **Federal Register** (`alerts.federal_register.match`): published when a matching Federal Register document is newly published or changes. A comment period closing is **not** a change β€” `comments_open` is evaluated at query time β€” so a `comments_open=true` alert tells you when a document opens for comment, not when its period ends. - **Award announcements** (`alerts.award_announcement.match`): published when a matching [award announcement](../api-reference/award-announcements.md) first appears or changes, including a correction being applied. Withdrawn announcements do not match unless the alert sets `include_withdrawn` to `true`. **A very large refresh can delay alerts by hours.** When one ingestion run changes millions of records at once (a bulk reload of award history, for example), Tango works through the change in bounded slices instead of all at once, so alerts behind it arrive hours late rather than minutes. While an alert catches up, its `last_checked_at` trails the current time, and a broad alert can receive several events in a row for the same `alert_id` β€” one per slice that matched, each carrying up to 500 new and 500 modified matches. A `daily` or `custom` alert only runs on its schedule, so a large enough backlog can take more than one of its scheduled runs to clear. ### 1.2 Filter subscriptions (alerts) Filter subscriptions let you create persistent monitoring rules based on **query filters**. For example, "alert me when new opportunities matching NAICS 541512 appear at HHS" or "notify me of new contracts awarded to small businesses in Virginia." You define a **query type** (the resource to monitor) and a set of **filters** (the same query parameters you would use on the corresponding API endpoint). Tango periodically evaluates your filters against new and updated data; when matches are found, Tango delivers a webhook to your endpoint with `alerts..match` events. #### Available query types | Query type | Resource monitored | Filters from | | --- | --- | --- | | `opportunity` | Contract opportunities | `/api/opportunities/` filters | | `contract` | Contracts | `/api/contracts/` filters | | `idv` | IDVs | `/api/idvs/` filters | | `ota` | OTAs | `/api/otas/` filters | | `otidv` | OTIDVs | `/api/otidvs/` filters | | `entity` | Entities | `/api/entities/` filters | | `grant` | Grants | `/api/grants/` filters | | `forecast` | Forecasts | `/api/forecasts/` filters | | `exclusion` | SAM.gov exclusions | `/api/exclusions/` filters | | `dibbs_rfq` | DIBBS requests for quote | `/api/dibbs/rfqs/` filters | | `dibbs_rfp` | DIBBS solicitations (RFP/IFB) | `/api/dibbs/rfps/` filters | | `ebuy_request` | GSA eBuy requests under your own linked contracts | `/api/ebuy/requests/` filters | | `sled_opportunity` | State, local and education solicitations (Beta) | `/api/sled/opportunities/` filters | | `contract_appeal` | CBCA and ASBCA contract appeal decisions | `/api/contract_appeals/` filters | | `federal_register` | Federal Register documents | `/api/federal_register/` filters | | `award_announcement` | Award announcements | `/api/news/award_announcements/` filters | #### Alert event types When a filter subscription matches, the delivered event uses the `alerts.*` namespace. There are thirteen: - `alerts.opportunity.match` - `alerts.contract.match` β€” also emitted for `idv`, `ota`, and `otidv` query types - `alerts.entity.match` - `alerts.grant.match` - `alerts.forecast.match` - `alerts.exclusion.match` - `alerts.dibbs_rfq.match` - `alerts.dibbs_rfp.match` - `alerts.ebuy_request.match` - `alerts.sled_opportunity.match` - `alerts.contract_appeal.match` - `alerts.federal_register.match` - `alerts.award_announcement.match` If you subscribe to `idv`, `ota`, or `otidv`, matches arrive as `alerts.contract.match` events; inspect `query_type` on the event to distinguish. **Award alerts follow the government's change date, not Tango's.** A `contract`, `idv`, `ota` or `otidv` alert matches an award only when FPDS last modified it on or after the moment you created the alert. When Tango reprocesses older awards on its side, such as during a data reload, those awards are not reported to you. An award with no FPDS last-modified date, which is true of some records from before 1998, never matches. FPDS publishes a change about a day after it is made, so a change made shortly before you created the alert is not reported even if it reaches Tango afterwards; query the matching `/api//` endpoint for anything older. **A record simply reaching a date is usually not a change.** An exclusion passing its termination date, or a DIBBS RFQ/RFP passing its closing date, does not emit an alert β€” open/closed and in-force/lifted are derived at query time, so no underlying record changes. Alerts fire only when a matching record is newly posted, revised, or lifted. **DIBBS awards are not alertable** (there is no `dibbs_award` query type); subscribe to `dibbs_rfq` or `dibbs_rfp` to follow solicitations. **[Financial-assistance awards](../api-reference/assistance.md) are not alertable** either: there is no query type for `/api/assistance/`, and `grant` alerts follow Grants.gov opportunities, not grant awards. **`sled_opportunity` is the exception.** A state solicitation's liveness is a stored `status` column that Tango recomputes every fifteen minutes, not a query-time derivation, so a deadline passing *is* a write and a subscription can follow it. There is no `sled_forecast` query type (a forecast has no deadline, so nothing transitions), and SLED revisions and attachments are not separately alertable β€” subscribe to `sled_opportunity` and filter on `change_seen_after` or `revision_kind`. **`contract_appeal` is the other exception, for a different reason.** A board removing a decision from its listing, and a decision gaining its extracted text, are both writes to the record rather than derivations, so a subscription follows either. Nothing here expires on a clock. #### Frequency options | Frequency | Description | Tier requirement | | --- | --- | --- | | `realtime` | Evaluated after each ingestion cycle | All tiers | | `daily` | Evaluated once per day | All tiers | | `custom` | Custom cron expression (5-field) | Pro+ (Small and above) | For a weekly cadence, use a `custom` cron expression (e.g. `0 8 * * 1` for every Monday at 08:00 UTC). #### Tier limits Filter subscriptions are available to **all tiers**, including Free: | Tier | Max filter subscriptions | | --- | --- | | Free | 1 | | Small | 5 | | Medium | 10 | | Large | 25 | | Enterprise | custom | #### Convenience API: `/api/webhooks/alerts/` The alerts API provides a simpler shape for creating and managing filter subscriptions: **Create an alert:** ```txt POST /webhooks/alerts/ Content-Type: application/json ``` ```json { "name": "HHS IT services opportunities", "query_type": "opportunity", "filters": { "agency": "7500", "naics": "541512" }, "frequency": "daily", "endpoint": "" } ``` Returns **201 Created** with the alert details. If a subscription with the same `query_type` + `filters` already exists, returns **200 OK** with the existing alert (dedup). **Filters are checked when you create an alert.** If Tango can tell a filter would never fire, or would match more than you asked for, the create fails with **400** instead of saving the alert. Three things are rejected: - **Unknown filter keys.** Every key must be a filter the alert's `query_type` supports, even when it sits next to valid ones β€” an unsupported key would be ignored when the alert runs, so the alert would match more than you intended. Date-range filters take their `_after` / `_before` forms: `response_deadline_after` is accepted, a bare `response_deadline` is not. - **An agency that matches nothing.** For `agency` on `opportunity` and `federal_register` alerts, and `awarding_agency` / `funding_agency` on `contract`, `idv`, `ota` and `otidv` alerts, at least one `|`-separated value must match an organization. Each value is resolved on its own (see [Agency search](../guides/patterns/agency-search.md)), so a value that partly matches is accepted. `forecast`, `grant` and `exclusion` alerts fall back to matching the agency text on each record, so any agency name passes this check. - **An empty or unmatchable agency value.** On the agency filters above, the `forecast`, `grant` and `exclusion` ones included, a value longer than 150 characters or one with no agency in it (`|||`, an empty string, `null`) is rejected. `sled_opportunity`'s `agency` is a plain substring match on the buyer's text, so neither agency check applies to it. The body's `filter_definition` list carries one message per problem: ```json { "filter_definition": [ "Unknown filter key(s) for query_type 'opportunity': naics_cod. Unknown keys are ignored when the alert runs, so it would match more than intended.", "Agency filter 'agency': No agency found matching 'ZZZQX'. Please check the agency name and try again." ] } ``` The other two agency messages read `Agency filter '': longer than 150 characters, so it can never match.` and `Agency filter '': no agency value to match.` A filter where no key is recognized at all gets a single message listing some of the filters that `query_type` does support. These checks run only when an alert is created. Its filters can't be changed afterwards, so renaming, pausing, resuming or changing the schedule is never blocked by them, including on an alert saved before the checks existed. The agency check only catches a value that matches nothing. Agency resolution is fuzzy, so a misspelling can still resolve to a different agency β€” run the filter against the matching `/api//` endpoint before creating the alert (see [Recipes](recipes/index.md)). !!! info "When `endpoint` is required" The `endpoint` field is **required** if your account has more than one webhook endpoint configured (the server returns 400 otherwise so deliveries can't go to the wrong receiver). Accounts with a single endpoint may omit it β€” Tango routes to that endpoint automatically. List your endpoints with `GET /api/webhooks/endpoints/` or `client.list_webhook_endpoints()` in the SDKs. > **Tip β€” multi-value filters:** Use `|` (pipe) to match **any** of several values. The same syntax works on every filter that accepts multiple values (`naics`, `psc`, agencies, set-asides, etc.) β€” including the resource-ID filters described in [Following specific resources](#following-specific-resources) below. > > ```json > "filters": {"naics": "541511|541512"} > ``` > > One known exception: `/api/contracts/`'s `uei` filter is single-value only. To watch multiple vendors, create one alert per vendor β€” see the [vendor watchlist recipe](recipes/vendor-watchlist.md). #### Following specific resources Every alertable resource you can `GET` by its detail endpoint can also be **followed** by that same identifier in an alert. Pass the detail-endpoint ID as a filter and you'll be notified when that resource (or any of a set of them) is created or modified. | `query_type` | Filter key | Example value | | ----------------------------------------- | ---------------- | -------------------------------------------------------- | | `opportunity` | `opportunity_id` | `"\|\|"` | | `contract` / `idv` / `ota` / `otidv` | `key` | `"\|\|"` | | `grant` | `grant_id` | `"123\|456\|789"` | | `forecast` | `id` | `"12\|34\|56"` | The filter name matches the detail-endpoint lookup field for each resource β€” `GET /api/contracts/{key}/` β†’ `"key": "..."`, `GET /api/opportunities/{opportunity_id}/` β†’ `"opportunity_id": "..."`, and so on. Single-value or pipe-OR (`id1|id2|id3`) both work; up to **500 IDs per filter**. ```json { "name": "Follow my watchlist", "query_type": "contract", "filters": {"key": "||"}, "frequency": "realtime" } ``` **Prefer one alert with many IDs over many alerts with one ID each.** A grouped alert is one cron evaluation, one indexed query, and one delivery per tick β€” and it counts as a single subscription against your tier limit (see [Tier limits](#tier-limits)). One-alert-per-thing burns through your subscription budget quickly and produces more inbound traffic to your endpoint. > **Note β€” `entity`:** the `uei` filter on `entity` alerts is still single-value (see the multi-value tip above). To watch several vendors, create one entity alert per UEI, or use the [vendor watchlist recipe](recipes/vendor-watchlist.md). **List alerts:** ```txt GET /webhooks/alerts/ ``` Response: ```json { "count": 1, "next": null, "previous": null, "results": [ { "alert_id": "e4c4...", "name": "HHS IT services opportunities", "query_type": "opportunity", "filters": {"agency": "7500", "naics": "541512"}, "frequency": "daily", "cron_expression": null, "status": "active", "created_at": "2026-03-14T12:00:00Z", "last_checked_at": null, "match_count": 0 } ] } ``` **Update an alert:** ```txt PATCH /webhooks/alerts/{alert_id}/ ``` You can update `name`, `frequency`, `cron_expression`, and `is_active`. Filters and query type cannot be changed after creation (delete and recreate instead). **Resuming a paused alert starts it from the moment you resume.** Set `is_active` to `false` to pause and `true` to resume. Records created or changed while the alert was paused are not delivered when it comes back. If you need that period, query the matching `/api//` endpoint with the same filters. **Delete an alert:** ```txt DELETE /webhooks/alerts/{alert_id}/ ``` #### Dedup behavior If you create a filter subscription with the same `query_type` and filter parameters as an existing one (for the same endpoint), the API returns the existing subscription instead of creating a duplicate. The dedup is based on a SHA-256 hash of the canonical filter representation. #### Keeping filters focused Filter matching runs against Tango's data-lake change feed β€” only the records that changed since your alert's last check are evaluated, so a broad filter never overloads the platform and alerts are never paused, throttled, or rejected for matching too many records. A broad filter can still deliver more events to *your* endpoint than you want to process. To keep deliveries focused: - Add NAICS or PSC constraints if monitoring broad agencies (e.g. don't monitor "all of DOD" β€” try "DOD IT services", i.e. DOD + NAICS 541512). - Split one broad alert into several focused ones (e.g. "all opportunities" β†’ "opportunities by agency"). - Add keyword constraints (e.g. `keywords=cybersecurity` to reduce noise). - Lower the frequency from `realtime` to `daily` (fewer, larger deliveries over the same underlying data). #### Current status The filter subscription API is fully functional for creating, listing, updating, and deleting alerts. A background task evaluates filter subscriptions on their configured schedule (realtime, daily, or custom cron) and delivers matches automatically. --- ## 2. Access requirements Filter subscriptions are available to **all tiers**, including Free, with per-tier caps on how many you can create simultaneously (see the table in Β§1.2 β€” Tier limits). No tier upgrade is required to start using webhooks. --- ## 3. On-boarding checklist 1. **Provide a callback URL** β€” a publicly reachable `https://` endpoint that accepts HTTP POSTs. Recommended path: `/tango/webhooks`. 2. **Receive your shared secret** β€” Tango generates a 32-byte hex secret (64 hex chars) and shares it out-of-band. You'll use this to verify signatures. 3. **Test your endpoint** β€” use the test delivery endpoint (Β§5.5) to verify connectivity. 4. **Create one or more filter alerts** β€” define a `query_type` + `filters` per saved query you want to monitor. See Β§1.2 (Convenience API) and the [recipes](recipes/index.md). > **Note** We create the initial Webhook Endpoint record for you. All subsequent management of subscriptions/alerts is done via the Subscription API below. --- ## 4. Security & authenticity Every POST from Tango includes an HMAC-SHA-256 signature: ```txt X-Tango-Signature: sha256= ``` The digest is computed over the raw request body using your secret. Verify it like so (Python snippet): ```python import hmac, hashlib, os, flask, json SECRET = os.environ["TANGO_WEBHOOK_SECRET"] app = flask.Flask(__name__) @app.post("/tango/webhooks") def recv(): body = flask.request.get_data() sig = flask.request.headers.get("X-Tango-Signature", "")[7:] # strip "sha256=" if not hmac.compare_digest( hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest(), sig): return "Invalid signature", 401 payload = json.loads(body) # ... handle events ... return "ok", 200 ``` If you respond with any **2xx** status, Tango marks the delivery as successful. Non-2xx responses and time-outs are retried (at-least-once delivery). Current retry limits are error-aware: - 4xx: up to 2 attempts total - 5xx: up to 5 attempts total - network errors/timeouts: up to 7 attempts total --- ## 5. Subscription API Base URL: `https://tango.dev/api/webhooks/` Auth: **API Key** – send `X-API-KEY: ` (or an OAuth2 bearer token via `Authorization: Bearer `) ### 5.0 Discover supported event types Tango exposes a discovery endpoint so clients can validate configurations without hard-coding event types: ```txt GET /webhooks/event-types/ ``` Response: ```json { "event_types": [ { "event_type": "alerts.contract.match", "description": "A new or modified contract matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.opportunity.match", "description": "A new or modified opportunity matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.entity.match", "description": "A new or modified entity matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.grant.match", "description": "A new or modified grant matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.forecast.match", "description": "A new or modified forecast matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.exclusion.match", "description": "A new, revised, or lifted SAM.gov exclusion matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.dibbs_rfq.match", "description": "A new or modified DIBBS request for quote matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.dibbs_rfp.match", "description": "A new or modified DIBBS solicitation (RFP/IFB) matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.ebuy_request.match", "description": "A new or modified GSA eBuy request visible under your linked contracts matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.sled_opportunity.match", "description": "A new, revised, or newly closed state, local or education solicitation matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.contract_appeal.match", "description": "A new or modified CBCA or ASBCA contract appeal decision matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.federal_register.match", "description": "A new or modified Federal Register document matched a saved filter alert.", "schema_version": 1 }, { "event_type": "alerts.award_announcement.match", "description": "A new or modified award announcement matched a saved filter alert.", "schema_version": 1 } ] } ``` > Note: Only some event types may be actively emitted at any given time. If you create an alert for a query type that has no matching new data, you simply won't receive events until matches appear. ### 5.1 List current alerts / filter subscriptions ```txt GET /webhooks/alerts/ ``` Response ```json { "count": 1, "next": null, "previous": null, "results": [ { "alert_id": "e4c4…", "name": "Track DOD IT services > $1M", "query_type": "contract", "filters": {"funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000"}, "frequency": "realtime", "cron_expression": null, "status": "active", "created_at": "2024-06-01T12:00:00Z", "last_checked_at": "2024-06-01T18:00:00Z", "match_count": 14 } ] } ``` ### 5.3 Update an existing alert ```txt PATCH /webhooks/alerts/{alert_id}/ ``` Updatable fields: `name`, `frequency`, `cron_expression`, `is_active`. `filters` and `query_type` are immutable β€” delete and recreate to change them. A resumed alert (`is_active: true`) matches from the moment it resumes and skips the paused period (see [Β§1.2](#convenience-api-apiwebhooksalerts)). ### 5.4 Delete an alert ```txt DELETE /webhooks/alerts/{alert_id}/ ``` If you delete every alert, you will stop receiving webhooks until you create at least one new one. > Note: You must maintain at least one active alert to receive webhooks. ### 5.5 Test webhook delivery ```txt POST /webhooks/endpoints/test-delivery/ ``` Sends a test webhook to your endpoint to verify connectivity. Returns detailed information about the delivery attempt. Response (success): ```json { "success": true, "status_code": 200, "response_time_ms": 145, "message": "Test delivery successful! Response time: 145ms. Your webhook endpoint is configured correctly." } ``` Response (failure): ```json { "success": false, "status_code": 500, "message": "Test delivery failed with status 500. Please check your endpoint implementation and ensure it returns 2xx status codes.", "response_body": "" } ``` ### 5.6 Get sample payload ```txt GET /webhooks/endpoints/sample-payload/?event_type=alerts.contract.match ``` Returns a sample webhook payload for testing your handler implementation. Notes: - `GET /webhooks/endpoints/sample-payload/` (no params) returns samples for all supported event types. - `GET /webhooks/endpoints/sample-payload/?event_type=` returns a single sample. Response: ```json { "event_type": "alerts.contract.match", "sample_delivery": { "timestamp": "2026-05-13T00:36:46.157804", "events": [ { "event_type": "alerts.contract.match", "created_at": "2026-05-13T00:36:46.157779", "subscription_id": "11111111-2222-3333-4444-555566667777", "new_ids": ["MATCH_001", "MATCH_002"], "modified_ids": [] } ] }, "signature_header": "X-Tango-Signature: sha256=", "note": "The signature is generated using HMAC-SHA256 with your endpoint's secret key." } ``` !!! warning "Preview vs production payload shape" The `/webhooks/endpoints/sample-payload/` endpoint emits a **simplified preview** β€” no `delivery_id`, no `matches.new[]` summary objects, just `new_ids` / `modified_ids`. **Real deliveries from the dispatcher carry the richer shape documented in Β§6**, including `delivery_id`, the `matches.new` / `matches.modified` arrays with per-record summary fields, and the echoed `filters` / `query_type`. Build your receiver against Β§6, not against this sample. (Server-side reconciliation of the two shapes is tracked separately.) A `claude_routine` endpoint receives neither shape; see [Β§5.7](#57-deliver-to-an-authenticated-destination-incl-claude-code-routines). ### 5.7 Deliver to an authenticated destination (incl. Claude Code routines) By default Tango sends only its own headers (`Content-Type`, `X-Tango-Signature`, `User-Agent`), so it can deliver to any receiver that doesn't require authentication. To deliver to a destination that *does* require auth β€” for example, firing a Claude Code routine when an alert matches β€” attach **custom request headers** to your webhook endpoint. Custom headers live on the **endpoint**, not on the alert. Setting one up is a two-step flow: **Step 1 β€” create the endpoint with its headers.** ```txt POST /webhooks/endpoints/ ``` ```json { "name": "Claude routine", "callback_url": "https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire", "destination_type": "claude_routine", "auth_token": "sk-ant-oat01-…" } ``` `destination_type: "claude_routine"` is a convenience preset: supply your OAuth token as `auth_token` and Tango fills in the headers a Claude Code routine requires (`Authorization: Bearer …`, `anthropic-version`, `anthropic-beta`). The preset fills the headers, not the URL: put the routine ID in the `callback_url` path yourself. Any `custom_headers` you send alongside the preset are merged over its headers, so an explicit value wins. The preset is checked on create and on any `PATCH` that sends `destination_type: "claude_routine"`, and each of these is a `400`: - **Wrong `callback_url` shape.** With `destination_type: "claude_routine"`, the `callback_url` path must end in `/claude_code/routines/{routine_id}/fire`. A URL missing the routine ID or the `/fire` segment is rejected rather than left to fail at delivery time. - **Missing `auth_token`.** The preset requires `auth_token`. - **`auth_token` without the preset.** `auth_token` is only accepted with `destination_type: "claude_routine"`; for any other destination, put the header in `custom_headers`. - **Encryption not configured.** If the server has no header-encryption key configured, Tango refuses to store any custom header (preset or not) rather than keep it in plaintext. !!! warning "A `claude_routine` endpoint does not receive the Β§6 payload" A Claude Code routine's `/fire` endpoint reads a single `text` string and ignores every other field, so Tango sends `{"text": ""}` instead of the [Β§6](#6-payload-format) envelope: a one-line summary (for example `2 new matches from a Tango webhook alert.`) followed by the matched events as JSON, truncated to stay under the `/fire` size limit. There is no `delivery_id`, `events[]`, or `matches` object, and the Β§5.5 test delivery sends the same `{"text": …}` shape. Β§6 and the "build your receiver against Β§6" advice don't apply to this destination: the routine receives the text as its prompt context. !!! warning "`claude_routine` deliveries are fire-once" Unlike the [at-least-once delivery](#delivery-guarantee) guarantee that covers other destinations, `claude_routine` deliveries are never retried on failure β€” the routine's `/fire` endpoint has no idempotency key, so a retry could double-fire the routine. A transient failure therefore drops the trigger silently instead of retrying. !!! warning "The `anthropic-beta` value goes stale" Anthropic rotates the `anthropic-beta` value the `/fire` endpoint accepts, and a stale value gets a `400` before the routine runs. Tango writes the preset's current value into the endpoint's stored headers when you create or `PATCH` it with `destination_type: "claude_routine"`; it does not refresh that stored value afterwards. So when Anthropic rotates the value, an existing endpoint keeps sending the old one, and because routine deliveries are fire-once, every trigger is dropped with no retry and nothing but the failed delivery to show for it. If your routine stops firing, `PATCH` the endpoint again with `destination_type: "claude_routine"` and your `auth_token` (Step 1's fields) to pick up the value Tango currently ships, then run the Β§5.5 test delivery to confirm a `200`. If Tango's value is itself out of date, add `"custom_headers": {"anthropic-beta": ""}` to that `PATCH`, taking the value from Anthropic's [routine `/fire` API docs](https://platform.claude.com/docs/en/api/claude-code/routines-fire); an explicit header overrides the preset's. For any other authenticated destination, send the headers directly instead of using the preset: ```json { "name": "Partner API", "callback_url": "https://example.com/hooks/tango", "custom_headers": { "Authorization": "Bearer …", "X-Partner-Id": "acme" } } ``` **Step 2 β€” create an alert that points at the endpoint** (see Β§1.2), passing the endpoint's `id` as the `endpoint` field. Behavior and constraints: - **Write-only.** Header values are stored encrypted and are **never returned** by the API. `GET`/`LIST` responses omit them; there is no way to read a stored value back. - **Tango's headers win.** `Content-Type`, `User-Agent`, and the signature/host headers are controlled by Tango; a custom header with one of those names is ignored. `Host` and `X-Tango-Signature` are reserved and rejected outright. - **Validated on the way in.** Custom headers are checked at create/update time β€” invalid header names, control characters (including CR/LF) in values, more than 25 headers, or values over 8 KB are rejected with a `400`, so a malformed header can't silently break every delivery later. - **Updating.** `PATCH` with a new `custom_headers` map (or `destination_type` + `auth_token`) replaces the stored headers; rotate a token the same way. Send `"custom_headers": {}` to clear them entirely. Omitting the field leaves existing headers untouched. - **Test it.** Use Β§5.5 test delivery β€” it sends the same custom headers (and, for `claude_routine`, the same `{"text": …}` body) a live delivery would, so a `200` confirms your auth works end to end. !!! note "Token expiry" OAuth tokens such as `sk-ant-oat01-…` can expire. Tango does not refresh them automatically β€” once a token expires the destination will reject every delivery until you `PATCH` the endpoint with a fresh token. --- ## 6. Payload format A single delivery looks like: ```json { "timestamp": "2026-05-11T18:20:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.contract.match", "created_at": "2026-05-11T18:20:12.482Z", "alert_id": "e4c4...-...-...", "query_type": "contract", "filters": {"funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000"}, "matches": { "new_count": 2, "modified_count": 0, "new": [ {"id": "CONT_AWD_...", "piid": "W15QKN24C1234", "total_contract_value": 1450000, "recipient_legal_business_name": "ACME CORP"}, {"id": "CONT_AWD_...", "piid": "FA8773-24-C-...", "total_contract_value": 2300000, "recipient_legal_business_name": "BETA INDUSTRIES LLC"} ], "modified": [], "new_ids": ["CONT_AWD_...", "CONT_AWD_..."], "modified_ids": [] }, "checked_at": "2026-05-11T18:20:12.000Z" } ] } ``` The `new_ids` / `modified_ids` arrays are deprecated but still sent; prefer `matches.new` / `matches.modified` which carry summary objects per match. ### 6.1 Per-event fields | Field | Type | Notes | | --- | --- | --- | | `event_type` | string | One of the thirteen `alerts..match` types listed in [Β§1.1](#11-when-events-are-published-data-is-ready) | | `alert_id` | UUID | Stable id of the alert that produced this match | | `query_type` | string | `contract` / `idv` / `ota` / `otidv` / `opportunity` / `entity` / `grant` / `forecast` / `exclusion` / `dibbs_rfq` / `dibbs_rfp` / `ebuy_request` / `sled_opportunity` / `contract_appeal` / `federal_register` / `award_announcement` | | `filters` | object | Echo of the alert's saved filters | | `matches.new` | array | Newly-matched records (summary objects, not full API rows) | | `matches.modified` | array | Existing records whose key fields changed | | `matches.new_count` / `matches.modified_count` | int | Counts of the above | | `checked_at` | ISO8601 | When the evaluator scanned for matches | Match summary objects always key the resource's primary id as `id` β€” for every `query_type`, including `entity` (where the value is the UEI) β€” plus a small set of high-signal fields that vary by `query_type`. Pull the full record from the corresponding `/api//` endpoint when you need more. Key facts: - **Batched** β€” events are grouped per endpoint per dispatch run. - **At-least-once** β€” retries can cause duplicates; your handler must be idempotent. If you need a de-dupe key, prefer the top-level `delivery_id` (UUID, stable across retries of the same dispatch). - **Server-side filtered** β€” only events matching your alerts are sent. ## Examples These are copy/paste alert payloads for common use cases. For full how-tos with receiver code and pitfalls, see the [recipes](recipes/index.md). ### Track DOD IT-services contracts over $1M ```json { "name": "DOD IT services > $1M", "query_type": "contract", "filters": { "funding_agency": "DOD", "naics": "541512", "obligated_gte": "1000000" }, "frequency": "realtime" } ``` ### Watch HHS opportunities in NAICS 541512 ```json { "name": "HHS opportunities β€” IT consulting (541512)", "query_type": "opportunity", "filters": { "agency": "7500", "naics": "541512" }, "frequency": "realtime" } ``` Match summaries carry `id`, `latest_notice_title`, `solicitation_number`, `naics_code`, `response_deadline` and `awardee` (`null` unless SAM has posted an award notice for the opportunity); fetch the rest from `/api/opportunities/{opportunity_id}/`. ### Track entity registrations changing in your pipeline ```json { "name": "Pipeline entities β€” registration changes", "query_type": "entity", "filters": { "uei": "ABC123XYZ456" }, "frequency": "daily" } ``` (Entities currently take a single `uei` per alert β€” for multi-entity tracking, create one alert per UEI.) ### Watch cybersecurity grants by CFDA ```json { "name": "DHS cybersecurity grants", "query_type": "grant", "filters": { "agency": "DHS", "cfda_number": "97.067" }, "frequency": "daily" } ``` ### Monitor upcoming Air Force IT acquisitions in the forecast ```json { "name": "Air Force forecasts β€” IT (541512 + nearby)", "query_type": "forecast", "filters": { "agency": "AF", "naics_starts_with": "5415" }, "frequency": "custom", "cron_expression": "0 8 * * 1" } ``` ### Follow board decisions on a theme you litigate ```json { "name": "ASBCA β€” differing site conditions", "query_type": "contract_appeal", "filters": { "board": "asbca", "search": "differing site conditions" }, "frequency": "daily" } ``` Match summaries carry `id`, `board`, `docket_numbers`, `appellant`, `decision_date` and `decision_type`; fetch the rest from `/api/contract_appeals/{uuid}/`. ### Follow proposed rules under a CFR part ```json { "name": "40 CFR 52 β€” proposed rules open for comment", "query_type": "federal_register", "filters": { "type": "Proposed Rule", "cfr_title": "40", "cfr_part": "52", "comments_open": "true" }, "frequency": "daily" } ``` Match summaries carry `id`, `document_number`, `publication_date`, `type`, `title` and `comments_close_on`; fetch the rest from `/api/federal_register/{uuid}/`. ### Follow large official award announcements ```json { "name": "Official announcements of $100M or more", "query_type": "award_announcement", "filters": { "source": "official_release", "amount_min": "100000000" }, "frequency": "daily" } ``` Match summaries carry `id`, `source`, `published_date`, `title`, `amount` and `action_type`; fetch the rest from `/api/news/award_announcements/{uuid}/`. ### Follow eBuy requests under one SIN ```json { "name": "eBuy β€” 54151S", "query_type": "ebuy_request", "filters": { "sin": "54151S", "status": "Open" }, "frequency": "daily" } ``` Match summaries carry `id` (the eBuy request id), `title`, `request_type`, `buyer_agency`, `issue_date` and `close_date`; fetch the rest from `/api/ebuy/requests/{rfq_id}/`. The alert only matches requests under the contracts linked to the account that owns the webhook endpoint. --- ## 8. Best practices on your side 1. **Make your handler idempotent** β€” Tango guarantees at-least-once delivery, so your endpoint may receive the same event more than once. Deduplicate on `delivery_id` (see [Delivery guarantee](#delivery-guarantee)). 2. **Return 200 quickly** β€” enqueue the work in your own job queue and respond; do not block processing. 3. **Test your endpoint first** β€” use the test delivery endpoint to verify connectivity before going live. 4. **Harden the endpoint** β€” HTTPS only, accept `POST` only, max-payload 256 KB. 5. **Store the last successful timestamp** β€” helps spot missed deliveries. 6. **Use exponential back-off when pulling details** β€” Tango's public API has rate limits; stagger follow-up fetches if you receive a large batch. 7. **Tighten your filters** β€” broad filters generate large match batches; narrow `filters` to what you actually act on. 8. **Monitor endpoint health** β€” Tango uses circuit breaker patterns to protect both systems from cascading failures. --- ## 9. Reliability features ### Delivery guarantee Tango webhooks provide **at-least-once delivery**. This means: - Every event that matches one of your alerts **will** be delivered to your endpoint (assuming it is reachable). - In rare cases (e.g., a transient failure between sending the HTTP request and recording its success), the **same event may be delivered more than once**. Each webhook request includes a stable `delivery_id` (UUID) that uniquely identifies the dispatch. Use this as an idempotency key on your side to safely deduplicate: ```python # Example: skip already-processed deliveries delivery_id = payload["delivery_id"] if already_processed(delivery_id): return HttpResponse(status=200) process(payload) mark_processed(delivery_id) ``` **Why not exactly-once?** Guaranteeing exactly-once delivery over HTTP is not possible without cooperation from the consumer. Tango prevents duplicate *internal* delivery records via database constraints, but the HTTP POST itself can be retried if acknowledgment is lost. Designing your webhook handler to be idempotent ensures correct behavior regardless of delivery count. ### Circuit Breaker Pattern Tango implements automatic circuit breaker protection for webhook endpoints: - **Automatic failure detection** β€” After repeated failures (currently: 5 consecutive failures), the circuit opens - **Cool-down** β€” While open, deliveries are skipped for a short period (currently: 5 minutes) - **Recovery testing** β€” After cool-down, Tango allows a single probe delivery (half-open) - **Automatic recovery** β€” Upon success, normal operation resumes; upon failure, the circuit re-opens (currently: 10 minute cool-down) - **Resource protection** β€” Prevents wasting resources on consistently failing endpoints This ensures both Tango and your systems remain stable even during outages. ### Retry Strategy Failed webhooks are retried with: - **Error-aware retry limits** β€” Retry caps differ by error type: - Client errors (4xx): up to 2 attempts total - Server errors (5xx): up to 5 attempts total - Network errors/timeouts: up to 7 attempts total --- ## 10. Troubleshooting | Symptom | Most likely cause | Next steps | | --- | --- | --- | | Receive 401 from Tango on the alerts API | Missing/invalid API key | Ensure `X-API-KEY: ` header (or `Authorization: Bearer ` for OAuth2) | | Webhook payloads stop arriving | Circuit breaker activated due to failures | Fix endpoint issues; circuit will auto-recover after cool-down | | Test delivery fails | Endpoint connectivity issues | Check HTTPS cert, firewall rules, response time | | Signature mismatch | Using wrong secret or modified body | Re-sync secret; ensure you hash the **raw bytes** exactly | | Not receiving expected events | Filter doesn't match upstream data | Run the same filter against `/api//` first β€” if it returns nothing there, no events will fire | | Receiving too many events | Filter too broad | Tighten `filters`; lower `frequency` (e.g. `daily` instead of `realtime`); split into multiple narrower alerts | | Creating an alert returns 400 `Unknown filter key(s) …` | A key the alert's `query_type` doesn't support, often a typo or a date-range filter without `_after` / `_before` | Use the key exactly as the matching `/api//` endpoint takes it (Β§1.2) | | Creating an alert returns 400 `No agency found matching '…'` | An agency filter value matches no organization | Check the spelling, or look the agency up with [Agency search](../guides/patterns/agency-search.md); at least one pipe-separated value must match | | Creating an alert returns 400 `longer than 150 characters` or `no agency value to match` | The agency value is over 150 characters, or holds no agency (only separators, empty, or `null`) | Shorten the list (split it across alerts if needed), or drop the empty filter | | Alerts arrive hours late after a big data refresh | A single ingestion run changed millions of records, and alerts work through it in slices (Β§1.1) | Nothing to do; `last_checked_at` on the alert shows how far it has caught up | | Nothing arrived for the period an alert was paused | Resuming starts the alert from the moment it resumes | Query the matching `/api//` endpoint for that period | | An award alert skipped an award that matches its filters | FPDS last modified the award before the alert was created (Β§1.2) | Query `/api/contracts/` (or `/api/idvs/`, `/api/otas/`, `/api/otidvs/`) with the same filters | Need help? Email [support@makegov.com](mailto:support@makegov.com) with your endpoint URL & the approximate timestamp of the last delivery you saw. --- Happy shipping! πŸš€ --- --- description: "A recipe for streaming new contracts in one or more NAICS codes, with optional agency, set-aside, and dollar-floor filters." tags: [awards, naics, webhooks, cookbook] updated: 2026-08-18 --- # Awards by NAICS β€” stream new contracts in your industry codes Get a webhook whenever new contracts land in one or more NAICS codes you care about. Optionally narrow by agency, set-aside, or dollar floor. ## The 1-line answer Create a single filter alert on `query_type=contract` with the NAICS codes you want β€” use `|` to OR multiple codes into one alert. ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "IT consulting NAICS β€” 541511 / 541512 / 541519", "query_type": "contract", "filters": { "naics": "541511|541512|541519" }, "frequency": "realtime" }' ``` That's it. One alert covers any number of NAICS codes. ## Step 1 β€” Verify the filter against the contracts API ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?naics=541511|541512|541519&ordering=-award_date&limit=5" ``` If this returns recent contracts in your codes, you're good. ## Step 2 β€” Create the alert === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "IT consulting NAICS", "query_type": "contract", "filters": { "naics": "541511|541512|541519", "obligated_gte": "100000" }, "frequency": "realtime" }' ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) alert = client.create_webhook_alert( name="IT consulting NAICS", query_type="contract", filters={ "naics": "541511|541512|541519", "obligated_gte": "100000", }, frequency="realtime", ) print(alert.alert_id, alert.status) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const alert = await client.createWebhookAlert({ name: "IT consulting NAICS", query_type: "contract", filters: { naics: "541511|541512|541519", obligated_gte: "100000", }, frequency: "realtime", }); console.log(alert.alert_id, alert.status); ``` ## Step 3 β€” Refine with optional filters Stack any of these on top of `naics` to narrow the alert. All filters are AND-combined. | Filter | Notes | | --- | --- | | `funding_agency` / `awarding_agency` | Vector-backed agency match β€” `"DOD"`, `"Navy"`, `"NAVSEA"` all work. Pick the role you actually care about. | | `psc` | Six-digit PSC code; same `\|` multi-value syntax as `naics`. | | `set_aside` | `SBA`, `8A`, `WOSB`, `SDVOSB`, etc. Multi-value via `\|`. | | `obligated_gte` / `obligated_lte` | Dollar thresholds. | | `recipient_state` / `place_of_performance` | Geographic filters. | | `ordering` | Doesn't apply to alerts (the evaluator processes new matches as they arrive). | Example with all the dials turned: ```json { "name": "DOD IT services > $1M, small business", "query_type": "contract", "filters": { "funding_agency": "DOD", "naics": "541511|541512|541519", "obligated_gte": "1000000", "set_aside": "SBA|8A|WOSB|SDVOSB" }, "frequency": "realtime" } ``` ## Step 4 β€” Receive `alerts.contract.match` events ```json { "timestamp": "2026-05-12T18:20:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.contract.match", "alert_id": "e4c4...-...-...", "query_type": "contract", "filters": { "naics": "541511|541512|541519", "obligated_gte": "100000" }, "matches": { "new_count": 3, "modified_count": 0, "new": [ {"id": "CONT_AWD_...", "piid": "W15QKN24C1234", "total_contract_value": 1450000, "recipient_legal_business_name": "ACME CORP"}, {"id": "CONT_AWD_...", "piid": "FA8773-24-C-...", "total_contract_value": 230000, "recipient_legal_business_name": "BETA INDUSTRIES LLC"}, {"id": "CONT_AWD_...", "piid": "N00033-24-D-...", "total_contract_value": 5400000, "recipient_legal_business_name": "GAMMA SOLUTIONS INC"} ], "modified": [] }, "checked_at": "2026-05-12T18:20:12.000Z" } ] } ``` For the full receiver implementation (signature verification, idempotency, fast 2xx), see [Stream contract awards in real time](../../guides/how-to/stream-awards.md#step-2-build-the-receiver). ## Limitations - **One alert per saved query.** If you want different downstream routing per NAICS, create separate alerts and dispatch on `alert_id` in your receiver. - **Tier caps apply.** Free 1 / Small 5 / Medium 10 / Large 25 simultaneous alerts. - **Realtime is "after each ingestion cycle"** β€” FPDS ingest runs roughly twice daily. Realtime delivers within minutes of each refresh, not within minutes of upstream FPDS publication. - **`naics_starts_with` is not a contracts filter.** Contracts only support exact `naics`. If you need a NAICS prefix, list the codes explicitly with `|`. ## Related - [Webhooks user guide](../index.md) β€” protocol reference - [Stream contract awards in real time](../../guides/how-to/stream-awards.md#step-2-build-the-receiver) β€” full how-to including receiver code - [Contracts API reference](../../api-reference/contracts.md) β€” full filter list --- --- description: "A recipe for monitoring upcoming agency procurement forecasts by industry, agency, and fiscal year." tags: [forecasts, webhooks, cookbook] updated: 2026-08-18 --- # Forecast pipeline β€” monitor upcoming agency opportunities Get a webhook when new procurement forecasts post that match your industry / agency / fiscal-year window. Forecasts are agency-published lists of opportunities they *plan* to release β€” useful for capture planning months ahead of the actual solicitation. Tango ingests forecasts from HHS, DHS, GSA, COMMERCE, DOE, TREASURY, DOI, DOL, DOT, VA, and NRC. See the [Forecasts data dictionary](../../data-dictionary/forecasts.md#forecasts-we-track) for the current list. ## The 1-line answer Create a filter alert on `query_type=forecast`. Filters are the same query parameters you'd pass to `/api/forecasts/`. ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "VA IT services forecast β€” FY26", "query_type": "forecast", "filters": { "agency": "VA", "naics_starts_with": "5415", "fiscal_year": "2026" }, "frequency": "custom", "cron_expression": "0 8 * * 1" }' ``` That's it. The `0 8 * * 1` cron re-evaluates every Monday at 08:00 UTC and POSTs `alerts.forecast.match` events when new forecasts match. ## Step 1 β€” Verify the filter against the forecasts API ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/forecasts/?agency=VA&naics_starts_with=5415&fiscal_year=2026&ordering=anticipated_award_date&limit=5" ``` If this returns the forecasts you expect, the alert will fire when new ones land. ## Step 2 β€” Create the alert === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "VA + DHS β€” IT consulting forecasts FY26", "query_type": "forecast", "filters": { "agency": "VA", "naics_starts_with": "5415", "fiscal_year": "2026", "award_date_after": "2026-04-01", "award_date_before": "2026-12-31" }, "frequency": "custom", "cron_expression": "0 8 * * 1" }' ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) alert = client.create_webhook_alert( name="VA β€” IT consulting forecasts FY26", query_type="forecast", filters={ "agency": "VA", "naics_starts_with": "5415", # NAICS prefix β€” matches 541511, 541512, 541519, etc. "fiscal_year": "2026", "award_date_after": "2026-04-01", "award_date_before": "2026-12-31", }, frequency="custom", cron_expression="0 8 * * 1", # every Monday at 08:00 UTC ) print(alert.alert_id, alert.status) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const alert = await client.createWebhookAlert({ name: "VA β€” IT consulting forecasts FY26", query_type: "forecast", filters: { agency: "VA", naics_starts_with: "5415", // NAICS prefix fiscal_year: "2026", award_date_after: "2026-04-01", award_date_before: "2026-12-31", }, frequency: "custom", cron_expression: "0 8 * * 1", // every Monday at 08:00 UTC }); console.log(alert.alert_id, alert.status); ``` ## Step 3 β€” Available forecast filters These are the keys accepted by `/api/forecasts/` and therefore by `query_type=forecast` alerts. | Filter | Notes | | --- | --- | | `agency` | Agency acronym (e.g. `VA`, `DHS`, `HHS`, `GSA`). | | `source_system` | Source system identifier β€” useful when an agency publishes forecasts via multiple feeds. | | `naics_code` | Exact NAICS match. | | `naics_starts_with` | NAICS prefix match (e.g. `5415` for any 5415xx). | | `fiscal_year` | Exact fiscal year. | | `fiscal_year_gte` / `fiscal_year_lte` | Fiscal year range. | | `award_date_after` / `award_date_before` | Anticipated award date range (`YYYY-MM-DD`). | | `modified_after` / `modified_before` | Date the forecast was last modified in Tango. | | `status` | Forecast status (case-insensitive partial match). | | `title` | Substring match on title. | | `search` | Full-text search over title/description (vector-backed). | !!! note "Filter names matter" NAICS filtering uses **`naics_code`** (exact) or **`naics_starts_with`** (prefix) β€” there is no plain `naics` filter on `/api/forecasts/`. There is also **no `set_aside` filter** on forecasts β€” that's a SAM/FPDS-side concept not present in agency forecast publications. For full filter docs, see the [Forecasts API reference](../../api-reference/forecasts.md#filtering). ## Step 4 β€” Receive `alerts.forecast.match` events ```json { "timestamp": "2026-05-12T08:00:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.forecast.match", "alert_id": "e4c4...-...-...", "query_type": "forecast", "filters": { "agency": "VA", "naics_starts_with": "5415", "fiscal_year": "2026" }, "matches": { "new_count": 2, "modified_count": 0, "new": [ {"id": "...", "title": "VistA Modernization Phase IV", "source_system": "VA", "anticipated_award_date": "2026-09-30"}, {"id": "...", "title": "Health Data Lake Refresh", "source_system": "VA", "anticipated_award_date": "2026-08-15"} ], "modified": [] }, "checked_at": "2026-05-12T08:00:12.000Z" } ] } ``` Pull full forecast details from `/api/forecasts/{id}/` (or via `client.get_forecast(id)` / `client.getForecast(id)`) when you need more than the summary fields. ## Limitations - **No `set_aside` filter on forecasts.** Forecasts don't expose a set-aside dimension; that's an FPDS/SAM concept that only shows up downstream when the actual opportunity / award posts. - **Forecast cadences are slow.** Most agencies refresh forecasts monthly or quarterly. A weekly `custom` cron (e.g. `0 8 * * 1`) is typically the right cadence; `realtime` works but won't actually fire more often than the underlying refresh. Note: `custom` cron requires Small tier or above β€” on Free, use `daily`. - **Coverage varies by agency.** Only the 11 source agencies listed above are ingested today. Filtering on `agency=DOJ` returns nothing because Tango doesn't ingest DOJ forecasts. - **Tier caps apply.** Free 1 / Small 5 / Medium 10 / Large 25 simultaneous alerts. ## Related - [Webhooks user guide](../index.md) β€” protocol reference - [Forecasts API reference](../../api-reference/forecasts.md) β€” full filter list - [Forecasts data dictionary](../../data-dictionary/forecasts.md) β€” field-by-field reference, including which agencies are tracked - [Recipes index](index.md) --- --- description: "A recipe for tracking new Grants.gov opportunities at chosen agencies, optionally narrowed by CFDA number or applicant type." tags: [grants, agencies, webhooks, cookbook] updated: 2026-08-18 --- # Grants by agency β€” track new grant opportunities Get a webhook when new grant opportunities post at agencies you care about, optionally narrowed by CFDA number, applicant type, or response window. ## The 1-line answer Create a filter alert on `query_type=grant`. Filters are the same query parameters you'd pass to `/api/grants/`. ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "DHS cybersecurity grants", "query_type": "grant", "filters": { "agency": "DHS", "cfda_number": "97.067" }, "frequency": "daily" }' ``` That's it. Tango re-evaluates daily and POSTs `alerts.grant.match` events when new grants match. ## Step 1 β€” Verify the filter against the grants API ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/grants/?agency=DHS&cfda_number=97.067&ordering=-posted_date&limit=5" ``` If this returns the grants you expect, the alert will fire when new ones land. ## Step 2 β€” Create the alert === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "DHS cybersecurity grants β€” open in next 60d", "query_type": "grant", "filters": { "agency": "DHS", "cfda_number": "97.067", "applicant_types": "00", "response_date_after": "2026-05-12", "response_date_before": "2026-07-12" }, "frequency": "daily" }' ``` === "Python (tango-python)" ```python import os from datetime import date, timedelta from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) today = date.today() sixty_days = today + timedelta(days=60) alert = client.create_webhook_alert( name="DHS cybersecurity grants β€” open in next 60d", query_type="grant", filters={ "agency": "DHS", "cfda_number": "97.067", "applicant_types": "00", # State governments "response_date_after": today.isoformat(), "response_date_before": sixty_days.isoformat(), }, frequency="daily", ) print(alert.alert_id, alert.status) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const today = new Date().toISOString().slice(0, 10); const sixtyDays = new Date(Date.now() + 60 * 24 * 3600 * 1000) .toISOString() .slice(0, 10); const alert = await client.createWebhookAlert({ name: "DHS cybersecurity grants β€” open in next 60d", query_type: "grant", filters: { agency: "DHS", cfda_number: "97.067", applicant_types: "00", // State governments response_date_after: today, response_date_before: sixtyDays, }, frequency: "daily", }); console.log(alert.alert_id, alert.status); ``` ## Step 3 β€” Available grant filters These are the keys accepted by `/api/grants/` and therefore by `query_type=grant` alerts. | Filter | Notes | | --- | --- | | `search` | Full-text search across title and description (vector-backed). | | `agency` | Substring match on agency abbreviation. `"DHS"` matches `DHS-FEMA`, `DHS-CISA`, etc. | | `opportunity_number` | Exact opportunity number. | | `cfda_number` | CFDA number, **substring** match (e.g. `"97.067"`). | | `status` | Opportunity status (case-insensitive choice). | | `applicant_types` | Eligibility / applicant type code (case-insensitive choice). | | `funding_categories` | Funding category codes. | | `funding_instruments` | Funding instrument codes. | | `posted_date_after` / `posted_date_before` | Posted date range (`YYYY-MM-DD`). | | `response_date_after` / `response_date_before` | Application deadline range (`YYYY-MM-DD`). | !!! note "Filter names matter" The filter is `cfda_number` (not `cfda`) and `applicant_types` (not `eligibility`). Using the wrong key returns 400. For full filter docs, see the [Grants API reference](../../api-reference/grants.md#filtering). ## Step 4 β€” Receive `alerts.grant.match` events ```json { "timestamp": "2026-05-12T08:00:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.grant.match", "alert_id": "e4c4...-...-...", "query_type": "grant", "filters": { "agency": "DHS", "cfda_number": "97.067" }, "matches": { "new_count": 2, "modified_count": 1, "new": [ {"id": "...", "opportunity_number": "DHS-26-CISA-067-001", "title": "Cybersecurity Grant Program FY26", "agency_code": "DHS-CISA"}, {"id": "...", "opportunity_number": "DHS-26-CISA-067-002", "title": "State and Local Cybersecurity Pilot", "agency_code": "DHS-CISA"} ], "modified": [ {"id": "...", "opportunity_number": "DHS-25-CISA-067-014", "title": "...", "agency_code": "DHS-CISA"} ] }, "checked_at": "2026-05-12T08:00:12.000Z" } ] } ``` Pull full grant details from `/api/grants/{grant_id}/` (or via the SDK's `client.get_grant(grant_id)` / `client.getGrant(grantId)`) when you need more than the summary fields. ## Limitations - **No multi-value `agency` shortcut.** `agency` is a substring match; if you need to watch DHS *and* HHS, create two alerts (or use `search=` with a broader term). - **Polling-friendly cadences.** Grants don't post every minute β€” `daily` (or a `custom` weekly cron on Small+) is usually plenty. `realtime` works but most agencies refresh on a daily cycle anyway. - **Tier caps apply.** Free 1 / Small 5 / Medium 10 / Large 25 simultaneous alerts. ## Related - [Webhooks user guide](../index.md) β€” protocol reference - [Grants API reference](../../api-reference/grants.md) β€” full filter list - [Recipes index](index.md) --- --- description: "Index of webhook alert recipes, plus the shared prerequisites and OR/AND filter syntax they build on." tags: [webhooks, cookbook] updated: 2026-09-21 --- # Recipes β€” webhook alerts Filter-based webhook alerts let Tango re-evaluate a saved query on a schedule and POST you the matches as `alerts..match` events. These recipes are end-to-end how-tos for the most common monitoring use cases. ## What's in this section | Recipe | Goal | | --- | --- | | [Vendor watchlist](vendor-watchlist.md) | Get notified when specific UEIs win new contracts. | | [Awards by NAICS](awards-by-naics.md) | Stream new contracts in one or more NAICS codes (with optional agency / set-aside / dollar-floor refinements). | | [Track entity changes](track-entity-changes.md) | Monitor SAM.gov registration updates β€” status flips, address moves, NAICS reassignment, socioeconomic re-cert. | | [Grants by agency](grants-by-agency.md) | Track new grant opportunities at one or more agencies, optionally filtered by CFDA + applicant type. | | [Forecast pipeline](forecast-pipeline.md) | Monitor upcoming opportunities in agency procurement forecasts (HHS, DHS, GSA, COMMERCE, DOE, TREASURY, DOI, DOL, DOT, VA, NRC). | ## Prerequisites All recipes assume: - An active Tango account on any tier (filter alerts are available on Free) - An API key (`X-API-KEY`) β€” see [Authentication](../../getting-started/authentication.md) - A configured webhook endpoint β€” Tango provisions the endpoint record for you; ask support if you don't have one yet - Your shared signing secret stored as `TANGO_WEBHOOK_SECRET` server-side ## SDK quick reference Each recipe shows three side-by-side variants. The snippets below are **templates** β€” substitute your own `name`, `query_type`, and `filters`. See [`webhooks-user-guide.md`](../index.md#convenience-api-apiwebhooksalerts) for the full canonical schema, including when the optional `endpoint` field is required. === "curl" ```bash # Template β€” replace the placeholders with your alert spec. curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "", "query_type": "", "filters": { "": "" }, "frequency": "realtime" }' ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) alert = client.create_webhook_alert( name="...", query_type="...", filters={"...": "..."}, frequency="realtime", ) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY }); const alert = await client.createWebhookAlert({ name: "...", query_type: "...", filters: { "...": "..." }, frequency: "realtime", }); ``` ## OR vs AND filter syntax - Within a single filter, **OR** is `|` β€” `naics: "541511|541512"` matches either. - Across multiple filters, the API takes the **AND** β€” `agency: "DHS"` + `naics: "541512"` matches only DHS opportunities in 541512. - One known exception: the `uei` filter on `/api/contracts/` is single-value only. Multi-vendor watchlists need one alert per UEI β€” see the [vendor-watchlist recipe](vendor-watchlist.md). ## Test the filter against the API first Always verify your filter returns the data you expect against the underlying API before turning it into an alert. If `/api//?` returns nothing, the alert will never fire. ```bash # Same filters you'd pass to the alert curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?funding_agency=DOD&naics=541512" ``` ## Related - [Webhooks user guide](../index.md) β€” protocol details, payload format, retry/circuit-breaker, security - [Stream contract awards in real time](../../guides/how-to/stream-awards.md) β€” the canonical contract-monitoring how-to with full receiver code - [Search opportunities by NAICS](../../guides/how-to/search-opportunities-naics.md) β€” opportunity filtering walkthrough --- --- description: "A recipe for monitoring SAM.gov entity registration changes β€” status flips, address moves, re-certifications β€” for vendors in a pipeline." tags: [entities, webhooks, cookbook] updated: 2026-08-18 --- # Track entity changes β€” monitor SAM.gov registration updates Get a webhook when a vendor in your pipeline updates their SAM.gov registration β€” status flips (Active ↔ Inactive), address moves, NAICS reassignment, socioeconomic re-certification, CAGE updates. These changes can make or break proposal eligibility, set-aside qualification, and partner-vetting workflows, and they're invisible to award-side monitoring until a contract actually posts. This is the entity-record companion to the [vendor watchlist](vendor-watchlist.md) recipe. Vendor-watchlist tracks **new contracts** for a known UEI (`query_type=contract`); this recipe tracks **changes to the entity record itself** (`query_type=entity`). ## The 1-line answer Create a filter alert on `query_type=entity`. Filters are the same query parameters you'd pass to `/api/entities/`. ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "Pipeline vendor β€” ACME Corp registration", "query_type": "entity", "filters": { "uei": "ABC123XYZ4567" }, "frequency": "daily" }' ``` That's it. Tango re-evaluates daily and POSTs `alerts.entity.match` events when the entity record changes (or first appears, if the UEI is brand-new in SAM). !!! warning "One alert per vendor β€” `uei` is single-value" The `/api/entities/` `uei` filter is **exact-match, single-value only** (`lookup_expr="iexact"`). To watch N vendors by UEI, create N alerts β€” one per UEI. Same constraint as the [vendor-watchlist recipe](vendor-watchlist.md). For *attribute-based* watches (e.g. "all small businesses in 541512 in Maryland"), see the second example below β€” that pattern uses `naics` / `socioeconomic` / `state` instead of `uei` and only needs one alert. ## Step 1 β€” Verify the filter against the entities API ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/entities/?uei=ABC123XYZ4567" ``` If this returns the entity record you expect, the alert will fire on changes. If it returns nothing, double-check the UEI β€” Tango only ingests entities present in SAM.gov. ## Step 2 β€” Create the alert (track a portfolio by UEI) === "curl" ```bash for uei in ABC123XYZ4567 DEF456UVW7890 GHI789RST0123; do curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d "{ \"name\": \"Pipeline entity β€” $uei\", \"query_type\": \"entity\", \"filters\": { \"uei\": \"$uei\" }, \"frequency\": \"daily\" }" done ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) pipeline = [ ("ACME Corp", "ABC123XYZ4567"), ("Beta Industries", "DEF456UVW7890"), ("Gamma LLC", "GHI789RST0123"), ] for label, uei in pipeline: alert = client.create_webhook_alert( name=f"Pipeline entity β€” {label}", query_type="entity", filters={"uei": uei}, frequency="daily", ) print(alert.alert_id, alert.status, label) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const pipeline = [ { label: "ACME Corp", uei: "ABC123XYZ4567" }, { label: "Beta Industries", uei: "DEF456UVW7890" }, { label: "Gamma LLC", uei: "GHI789RST0123" }, ]; for (const { label, uei } of pipeline) { const alert = await client.createWebhookAlert({ name: `Pipeline entity β€” ${label}`, query_type: "entity", filters: { uei }, frequency: "daily", }); console.log(alert.alert_id, alert.status, label); } ``` `daily` is the right frequency for entity tracking β€” SAM.gov refreshes nightly, so re-checking more often just adds deliveries without surfacing more changes. Use `realtime` only if you specifically need same-cycle delivery once SAM data lands in Tango. ## Step 3 β€” Filter by attribute, not identity Sometimes you want to discover *new* entities matching a profile, not watch a known list. For example: "alert me when a new small business registers in NAICS 541512 in Maryland." That's one alert with no `uei`: === "curl" ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "New MD small businesses in 541512", "query_type": "entity", "filters": { "naics": "541512", "socioeconomic": "A2", "state": "MD" }, "frequency": "daily" }' ``` === "Python (tango-python)" ```python alert = client.create_webhook_alert( name="New MD small businesses in 541512", query_type="entity", filters={ "naics": "541512", "socioeconomic": "A2", # SBA Small Business "state": "MD", }, frequency="daily", ) ``` === "Node (@makegov/tango-node)" ```typescript const alert = await client.createWebhookAlert({ name: "New MD small businesses in 541512", query_type: "entity", filters: { naics: "541512", socioeconomic: "A2", // SBA Small Business state: "MD", }, frequency: "daily", }); ``` Available `EntityFilter` keys (see the [Entities API reference](../../api-reference/entities.md) for the full list): | Filter | Notes | | --- | --- | | `uei` | Exact UEI (`iexact`, single value). | | `cage_code` (alias `cage`) | CAGE code (`iexact`). Pick one or the other β€” sending both is rejected. | | `name` | Substring match on `legal_business_name` (min length 2). | | `naics` | NAICS code; matches against the entity's registered NAICS list. | | `psc` | PSC code; matches against the entity's registered PSC list. | | `socioeconomic` | Business-type code (e.g. `A2` small business, `27` woman-owned, `XX` 8(a)). | | `state` | Physical-address state code (e.g. `MD`, `VA`). | | `zip_code` | Physical-address ZIP (exact). | | `purpose_of_registration_code` | SAM purpose-of-registration code (e.g. `Z2` All Awards). | | `total_awards_obligated_gte` / `_lte` | Lifetime contract+subaward total (USD); IDV/OTA excluded. | | `search` | Full-text search across name + UEI + CAGE (min length 2). | ## Step 4 β€” Receive `alerts.entity.match` events Tango POSTs a signed JSON batch to your endpoint. Entity events split matches into **`new`** (first-time-registered UEIs that match your filter) and **`modified`** (existing records whose SAM data changed since the last check): ```json { "timestamp": "2026-05-12T06:05:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.entity.match", "alert_id": "e4c4...-...-...", "query_type": "entity", "filters": { "uei": "ABC123XYZ4567" }, "matches": { "new_count": 0, "modified_count": 1, "new": [], "modified": [ { "id": "ABC123XYZ4567", "legal_business_name": "ACME Corporation", "registration_status": "Active" } ] }, "checked_at": "2026-05-12T06:05:12.000Z" } ] } ``` The summary fields delivered for `query_type=entity` are: `id` (the UEI), `legal_business_name`, and `registration_status`. To see *what changed* (which field flipped), pull the full record from `/api/entities/{uei}/` (or `client.get_entity(uei)` / `client.getEntity(uei)`) and diff against your last-known copy on the receiver side β€” Tango doesn't ship a field-level diff in the alert payload. For the full receiver implementation (signature verification, idempotency, fast 2xx, error handling), see [Stream contract awards in real time](../../guides/how-to/stream-awards.md#step-2-build-the-receiver) β€” the receiver shape is identical, only the event type and summary fields change. ## Step 5 β€” Manage the alert ```bash # List your alerts curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts/" # Pause a vendor without deleting curl -X PATCH -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts//" \ -d '{"is_active": false}' # Remove a vendor permanently curl -X DELETE -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts//" ``` `name`, `frequency`, `cron_expression`, and `is_active` are updatable. `query_type` and `filters` are immutable β€” to change the watched UEI, delete and recreate. ## Troubleshooting | Symptom | Cause | What to do | | --- | --- | --- | | Alert re-fires every day with the same `modified` UEI and nothing visibly changed | SAM bumps `modified` timestamps on full-record refresh even when no field flipped. The evaluator picks up `modified >= last_checked_at` regardless of what changed. | Diff the full record against your last-known copy on the receiver side; if no fields you care about changed, drop the event. | | First-ever evaluation fires for a UEI you've watched before in another tool | The `matches.new` bucket on the first run reflects records *created* in Tango since the lookback cutoff (default 24h on first eval) β€” not "first time you've ever seen this entity." A UEI freshly ingested into Tango lands in `new` even if it's been in SAM for years. | Treat `matches.new` on a brand-new alert as "Tango first saw this," not "SAM first saw this." For the latter, check `entity.created_date` from the full record. | | Status flip happens twice within one check window (Active β†’ Inactive β†’ Active) | The evaluator sees the net state at evaluation time, not the intermediate flip. Two flips in 24h with `frequency=daily` look like no change at all. | If you need every transition, use `frequency=realtime` (5-minute eval cadence) and accept the higher delivery volume. | | `cage` and `cage_code` rejected together | The filter accepts `cage` as an alias for `cage_code`; sending both at once is rejected with 400. | Pick one. They filter the same column. | | `state=MD` returns nothing for a vendor you know is in Maryland | `state` filters on the **physical address** state, not the mailing address. Some entities register the two separately. | Verify with `curl ".../api/entities/?uei="` and check `physical_address.state_or_province_code`. | | Alert never fires even though SAM clearly updated | Check `last_checked_at` on the alert (`GET /api/webhooks/alerts//`). If it's recent but no events were delivered, the SAM ingestion pipeline may not have refreshed yet β€” Tango ingests SAM nightly. | Wait one full ingestion cycle, then re-check. If still nothing, ping support with the `alert_id`. | ## Limitations - **`uei` is single-value.** One alert per vendor when watching by UEI. See the warning at the top. - **No field-level diff in the payload.** You get the post-change summary; compute the diff on your side from the full record. - **Tier caps apply.** Free 1 / Small 5 / Medium 10 / Large 25 simultaneous alerts across all alert types combined. - **Daily is usually the right cadence.** SAM refreshes nightly. `realtime` works but won't surface changes faster than the underlying data refresh. ## Related - [Vendor watchlist](vendor-watchlist.md) β€” track new **contracts** for known UEIs (the contract-side complement to this recipe) - [Webhooks user guide](../index.md) β€” protocol details, payload format, retry/circuit-breaker, security - [Entities API reference](../../api-reference/entities.md) β€” full filter list for `query_type=entity` - [Recipes index](index.md) --- --- description: "A recipe for getting notified when specific vendor UEIs win new contracts, using one filter alert per vendor." tags: [entities, contracts, webhooks, cookbook] updated: 2026-08-18 --- # Vendor watchlist β€” track new contracts from specific UEIs Get a webhook every time a vendor on your watchlist wins a new contract. ## The 1-line answer Create one filter alert per vendor UEI on `query_type=contract`. Tango re-evaluates each filter against `/api/contracts/` and POSTs `alerts.contract.match` events when matches appear. ```bash curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d '{ "name": "Vendor watchlist β€” ACME Corp", "query_type": "contract", "filters": { "uei": "ABC123XYZ4567" }, "frequency": "realtime" }' ``` That's it. Repeat for each vendor in your watchlist. !!! warning "One alert per vendor β€” `uei` is single-value" The `/api/contracts/` API's `uei` filter is **exact-match, single-value only**. There is no `|` multi-value support on this filter today. To watch N vendors, create N alerts β€” one per UEI. *Future:* If multi-value `uei` lands on `/api/contracts/`, this recipe collapses to a single alert per watchlist with `uei: "UEI1|UEI2|UEI3"`. Tracked as a backlog enhancement; no ETA. ## Step 1 β€” Verify each UEI returns data For each vendor on your list, prove the filter works against the contracts API first. ```bash curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/contracts/?uei=ABC123XYZ4567&ordering=-award_date&limit=5" ``` If this returns the recent contracts you expect, the alert will fire on new ones. If it returns nothing, double-check the UEI is correct and the vendor has FPDS history. ## Step 2 β€” Create one alert per vendor === "curl" ```bash for uei in ABC123XYZ4567 DEF456UVW7890 GHI789RST0123; do curl -X POST -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts/" \ -d "{ \"name\": \"Vendor watchlist β€” $uei\", \"query_type\": \"contract\", \"filters\": { \"uei\": \"$uei\" }, \"frequency\": \"realtime\" }" done ``` === "Python (tango-python)" ```python import os from tango import TangoClient client = TangoClient(api_key=os.environ["TANGO_API_KEY"]) vendors = [ ("ACME Corp", "ABC123XYZ4567"), ("Beta Industries", "DEF456UVW7890"), ("Gamma LLC", "GHI789RST0123"), ] for label, uei in vendors: alert = client.create_webhook_alert( name=f"Vendor watchlist β€” {label}", query_type="contract", filters={"uei": uei}, frequency="realtime", ) print(alert.alert_id, alert.status, label) ``` === "Node (@makegov/tango-node)" ```typescript import { TangoClient } from "@makegov/tango-node"; const client = new TangoClient({ apiKey: process.env.TANGO_API_KEY! }); const vendors = [ { label: "ACME Corp", uei: "ABC123XYZ4567" }, { label: "Beta Industries", uei: "DEF456UVW7890" }, { label: "Gamma LLC", uei: "GHI789RST0123" }, ]; for (const { label, uei } of vendors) { const alert = await client.createWebhookAlert({ name: `Vendor watchlist β€” ${label}`, query_type: "contract", filters: { uei }, frequency: "realtime", }); console.log(alert.alert_id, alert.status, label); } ``` Each alert returns **201 Created** on first run, **200 OK** on subsequent runs (dedup on `query_type` + `filters`). ## Step 3 β€” Receive `alerts.contract.match` events Tango POSTs a signed JSON batch to your endpoint. The match summary uses the **delivered** shape (richer than the API's sample-payload echo): ```json { "timestamp": "2026-05-12T18:20:14Z", "delivery_id": "8c5e3f6a-...-9b21", "events": [ { "event_type": "alerts.contract.match", "alert_id": "e4c4...-...-...", "query_type": "contract", "filters": { "uei": "ABC123XYZ4567" }, "matches": { "new_count": 1, "modified_count": 0, "new": [ { "id": "CONT_AWD_W15QKN24C1234_9700_-NONE-_-NONE-", "piid": "W15QKN24C1234", "total_contract_value": 2450000, "recipient_legal_business_name": "ACME CORP" } ], "modified": [] }, "checked_at": "2026-05-12T18:20:12.000Z" } ] } ``` Use `matches.new` and `matches.modified` for the per-record summary. Pull full contract details from `/api/contracts/{id}/` when you need more than the summary fields. For the full receiver implementation (signature verification, idempotency, fast 2xx, error handling), see [Stream contract awards in real time](../../guides/how-to/stream-awards.md#step-2-build-the-receiver). ## Step 4 β€” Manage the watchlist ```bash # List your alerts curl -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts/" # Pause a vendor without deleting curl -X PATCH -H "X-API-KEY: $TANGO_API_KEY" \ -H "Content-Type: application/json" \ "https://tango.dev/api/webhooks/alerts//" \ -d '{"is_active": false}' # Remove a vendor permanently curl -X DELETE -H "X-API-KEY: $TANGO_API_KEY" \ "https://tango.dev/api/webhooks/alerts//" ``` `name`, `frequency`, `cron_expression`, and `is_active` are updatable. `query_type` and `filters` (which include `uei`) are immutable β€” to change the watched UEI, delete and recreate. ## Limitations - **`uei` is single-value on `/api/contracts/`.** One alert per vendor. See the warning at the top of this page. - **Tier caps apply.** Free tier gets 1 alert total; Small 5; Medium 10; Large 25. A 5-vendor watchlist requires Small or higher. - **Only contracts.** This recipe covers `query_type=contract`. To watch a vendor's *registration changes* (DSBS updates, address changes, etc.) instead, use `query_type=entity` with `uei` β€” same N-alerts pattern applies. - **Following specific contracts (not vendors)?** If your watchlist is a fixed set of *contracts* β€” not a vendor's whole contract history β€” use the `key` filter instead: `{"query_type": "contract", "filters": {"key": "||"}}`. One alert, up to 500 contracts per filter. See [Following specific resources](../index.md#following-specific-resources) in the user guide. - **No multi-vendor consolidation.** All alerts deliver to the same endpoint, but each vendor's matches arrive in their own event (one per alert per dispatch). Group on the receiver side via `alert_id` if you need to fan out by vendor in your downstream system. ## Related - [Webhooks user guide](../index.md) β€” full protocol reference - [Stream contract awards in real time](../../guides/how-to/stream-awards.md#step-2-build-the-receiver) β€” receiver implementation, signature verification, common pitfalls - [Contracts API reference](../../api-reference/contracts.md) β€” full filter list for `query_type=contract`