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.

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 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):

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 for the full field list and Response Shaping for syntax.

Examples:

# 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.

Report an issue with this page