Skip to content

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.
excluding_agency_code Code of the agency that created the exclusion. Multi-value: use | 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=. Exclusions are a flat resource: there are no expandable relations (no * expansions).

  • 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, and provenance dates.

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