Response Fields

Response source attribution (universal)

Every /api/v1/* response carries a top-level _sources array naming where the data came from. Endpoints that compose multiple sources list each one (so a Pro /companies/{uei} call that returns both subaward and FPDS enrichment carries ["sam_entities", "sam_opportunities", "usaspending_ffata", "usaspending_fpds"]). Customers reading _sources know exactly what to verify upstream when something looks off, without consulting per-endpoint documentation.

In the response examples throughout this guide, _sources is sometimes elided for brevity: it is omitted when the value is the obvious single-source case for that endpoint (e.g. ["sam_opportunities"] on opportunities responses). Assume the field is present on every authenticated /api/v1/* response unless an example explicitly omits it. The /api/v1/federal-hierarchy/* reference-data endpoints are the exception: they currently do not carry _sources.

Identifier	Meaning
sam_opportunities	sam.gov contract notices (the opportunities table), serves /opportunities/*, /awards/*, /delta
sam_entities	sam.gov entity registry, serves /entities/* and the base data on /companies/{uei}
sam_exclusions	SAM exclusions extract, serves /exclusions/*
usaspending_fpds	FPDS prime contract transactions from USAspending, serves /contracts/* and FPDS enrichment blocks on other endpoints
usaspending_ffata	FFATA Section 2 subaward records from USAspending, serves /subawards/* and subaward enrichment blocks on other endpoints
derived_duns_uei_crosswalk	FFATA-derived crosswalk used by the public DUNS↔UEI lookup
derived_vendor_risk	Computed signal stack served by /vendor-risk/*

Pro enrichment fields (universal pattern)

Pro-tier responses on /companies/{uei}, /entities/{uei}, /vendor-risk/{uei}, and /exclusions/{uei_sam} include enrichment blocks that compose FPDS prime contract activity and FFATA subaward activity for a single UEI. The same shapes appear in multiple places, so the field reference is given once here and cross-linked from each endpoint section.

• Per-recipient FPDS aggregates on /companies/{uei} and /entities/{uei}: fpds_obligated_total (float, net federal action obligation summed across all prime contract transactions in the FY2025-onward window (since 2024-10-01)), fpds_distinct_contracts (int, distinct contract_award_unique_key), fpds_transaction_count (int, every base award and modification), fpds_first_action_date and fpds_latest_action_date (ISO date, activity bounds). On /companies/{uei} only: fpds_top_naics (array of up to 5 objects, each {code, description, transaction_count, value}, sorted desc by value) and fpds_top_agencies (array of up to 5 objects, each {name, transaction_count, value}, awarding sub-agency by total $), fpds_top_agency_share_pct (the single largest top-level department's share of FPDS obligations, 0-100; null on a non-positive base), and fpds_top_department (that department's name, so the share is a named, department-level dependency). Each top_* object also carries a deprecated n field with the same value as transaction_count; new code should read transaction_count.
• Per-recipient FFATA subaward aggregates on /companies/{uei}, /entities/{uei}: sub_revenue_total (float, total FFATA dollars received as a sub), top_paying_primes (array of up to 10 objects, each {uei, name, total, subaward_count}). On /companies/{uei} only: prime_revenue_share (float, FPDS prime obligations / (FPDS prime + sub revenue) ratio).
• contract_exposure block on /vendor-risk/{uei}: {fpds_obligated_total, fpds_distinct_contracts, fpds_transaction_count, fpds_first_action_date, fpds_latest_action_date, top_agencies: [{name, value, transaction_count}], window_days}. Descriptive only; not part of triage rules.
• subaward_exposure block on /vendor-risk/{uei}: {as_prime: {total_paid_to_subs, distinct_sub_vendors, subaward_count, first_subaward_date, last_subaward_date, top_subs: [{uei, name, total, subaward_count}]}, as_sub: {total_received_from_primes, distinct_primes, subaward_count, first_subaward_date, last_subaward_date, top_primes: [{uei, name, total, subaward_count}]}, window_days}. Both sides of the FFATA flow.
• recent_contract_actions block on /exclusions/{uei_sam}: {lookback_days, total_obligated_recent, transaction_count, distinct_contracts, distinct_agencies, most_recent_action_date, most_recent_action_amount, most_recent_awarding_agency, most_recent_piid, top_paying_agencies: [{name, value, transaction_count}]}. The compliance question: is this excluded UEI still receiving direct prime contract obligations?
• recent_sub_payments block on /exclusions/{uei_sam}: {lookback_days, total_received, subaward_count, distinct_primes, most_recent_subaward_date, most_recent_subaward_amount, most_recent_paying_prime: {uei, name}, top_paying_primes: [{uei, name, total, subaward_count}]}. The "are clean primes still paying this excluded vendor as a sub?" question.

All blocks are silently omitted on Free / Developer keys; Pro callers (contacts_access=true) receive them inline so they don't need a second round-trip. The blocks always return the zero shape (empty arrays, zero counts) when no records exist for the UEI in the window, so client code can safely read fields without per-call None checks.