---
title: "Screen a federal contractor by UEI or CAGE"
method: GET
path: "/api/v1/procurement/screen"
tags: ["Procurement"]
---

# Screen a federal contractor by UEI or CAGE

`GET /api/v1/procurement/screen`

## Request

- Base URL: `https://fonteum.com`
- URL: `https://fonteum.com/api/v1/procurement/screen`
- Auth: HTTP bearer

Screen one US federal entity against the currently loaded SAM.gov registration and exclusion data, USASpending award data, and available FAPIIS and FAR 4.18 fields. Returned blocks identify available source and date metadata and include a 'confirm at SAM.gov' pointer; provenance fields can be null.

Provide exactly one of `uei` or `cage`. Pass `as_of=YYYY-MM-DD` to query retained SAM or procurement history where rows have been banked; this is not universal replay for every entity or date. A zero-exclusion or unknown-identifier result is returned only when SAM serving coverage reconciles to a comparable attested artifact; otherwise HTTP 503 carries `exclusion_determination: indeterminate` and the coverage evidence.

Defamation-safe: no risk score, no 'fraudulent' / 'likely excluded' label, no derived verdict; confirmed UEI/CAGE matches only; opt-out entities withheld; public-tier federal data only (no FOUO). Screening aid, not a certification.

Requires `Authorization: Bearer fnt_...` and uses the key's configured limits.

## Query parameters

- `uei` string
- `cage` string
- `as_of` string, date

## Response `200`

Screening result with dated facts and available per-source provenance. A zero-active-exclusion, unknown-identifier, or opted-out result is HTTP 200 only when the endpoint's SAM coverage guard reports internally reconciled `current`; otherwise the fail-closed response is HTTP 503.

- object
  - `data` object
    - `query` object
    - `mode` 'current' | 'as_of_history'
    - `screened` boolean
    - `record_found` boolean
    - `entity_coverage` 'ingested' | 'not_ingested'
    - `registration` object, nullable
    - `exclusions` object[]
    - `exclusion_summary` object
    - `exclusion_coverage` ExclusionCoverage
      - `status` 'current' | 'coverage_stale' | 'indeterminate', required
      - `sources` object, required
      - `message` string, required
    - `exclusion_coverage_status` 'current' | 'coverage_stale' | 'indeterminate'
    - `exclusion_determination` 'match' | 'no_match' | 'indeterminate'
    - `awards` object
    - `fapiis` object[]
    - `ownership` object[]
    - `provenance` object
    - `data_as_of` string
    - `confirm_at` string
    - `disclaimer` string
    - `notes` string[]
  - `meta` ResponseMeta
    - `request_id` string, required
    - `api_version` 'v1', required
    - `data_freshness` union, required: One source block or an array of source blocks. Fields keep content-change, publisher-release, artifact-snapshot, coverage, check, and observation timestamps separate; only a proved canonical content transition can make last_refreshed non-null.
      - DataFreshness
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
      - DataFreshness[]
        - `source` string, required
        - `last_refreshed` string, date-time, nullable, required: Timestamp of the most recent proved content change. Null when canonical content evidence is unavailable, invalid, or conflicted.
        - `source_release_date` string, date-time, nullable: Publisher-issued release date represented by the response. Coverage and static artifact dates use their own fields and never advance last_refreshed.
        - `artifact_snapshot_date` string, date-time, nullable: Fonteum or static aggregate artifact snapshot represented by the response; not a publisher release or content-change timestamp.
        - `coverage_date` string, date-time, nullable: Source-data coverage date or period boundary; not a publisher release or content-change timestamp.
        - `last_checked_at` string, date-time, nullable: Latest workflow or source check, separate from content freshness.
        - `last_observed_at` string, date-time, nullable: Latest source_snapshots ledger observation, separate from content freshness.
        - `timestamp_basis` 'content_change', nullable: Present only when last_refreshed is backed by a proved canonical content transition.
        - `evidence_status` 'proved' | 'unavailable' | 'invalid' | 'conflicted' | 'error'
        - `next_refresh_eta` string, date-time, nullable
        - `cadence` string
    - `methodology_url` string, uri, required
    - `limitations_url` string, uri, required
    - `documentation_url` string, uri
    - `geo_scope_note` string
    - `pagination` object
      - `total` integer
      - `page` integer
      - `per_page` integer
    - `freshness` FreshnessBlock[]: Typed per-source stored-observation timing: snapshot date, configured target, and a computed age state. This measures the stored observation against Fonteum's configured target, not upstream publisher freshness. A `current` state requires a dated stored snapshot; an unconfirmable date renders `unknown`.
      - `source_id` string, required
      - `snapshot` string, date, nullable, required: Source publication date; null when unavailable (state then `unknown`).
      - `last_checked` string, date-time, required: Serve-time — the only `now` field.
      - `sla_days` integer, nullable
      - `sla_hours` integer, nullable
      - `age_hours` integer, nullable
      - `age_days` integer, nullable
      - `within_sla` boolean, nullable
      - `state` 'current' | 'degraded' | 'stale' | 'unknown', required
    - `freshness_policy` FreshnessPolicy: Present only when the request set `max_staleness`. Reports whether each consulted stored source observation met the caller's age bar; it does not assert that the upstream publisher released newer data.
      - `requested` true, required
      - `max_staleness` string, required
      - `max_staleness_hours` number, required
      - `mode` 'flag' | 'reject', required
      - `stale` boolean, required
      - `stale_sources` object[], required
        - `source_id` string
        - `state` 'current' | 'degraded' | 'stale' | 'unknown'
        - `age_hours` integer, nullable
        - `reason` 'exceeds_max_staleness' | 'freshness_unknown'
    - `attestation` TrustMark, required: Re-checkable attribution attached to v1 response metadata. The chain-head value is a 32-byte content hash, not an Ed25519 signature. Per-snapshot witness signatures use a separately scoped evidence object and never occupy this contract.
      - `attested_by` 'Fonteum', required
      - `standard` 'W3C-VC-2.0', required
      - `content_credential` 'C2PA-aligned Content Credentials for facts', required
      - `source` string, nullable, required
      - `as_of` string, nullable, required
      - `attestation_id` integer, nullable, required: Snapshot id when a specific snapshot is in scope; otherwise the live chain-head link index.
      - `chain_head_hash` string, nullable, required: Current chain-head content hash. This field is deliberately not named or represented as a signature.
      - `recheck_url` string, uri, required
      - `key_url` string, uri, required: Signing-key directory used by separately exposed chain and witness evidence.
      - `docs_url` string, uri, required

## Other responses

- `400`: Malformed request — missing/both identifiers, bad UEI/CAGE, or bad as_of.
- `429`: Rate limit exceeded.
- `503`: SAM exclusion coverage is stale or cannot be reconciled to an attested source artifact. No negative exclusion determination was made.

---

[API](https://skmtc.dev/fonteum/apis/fonteum-api.md) · [All operations](https://skmtc.dev/fonteum/apis/fonteum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fonteum/apis/fonteum-api/revisions/334e6e179d0d?raw)