SAM.gov Entities & Exclusions data contract

Provenance

PublisherSAM.gov Entity Management and Exclusions

Sourcehttps://sam.gov/entity-information

API basehttps://api.sam.gov/entity-information/v4

Docshttps://open.gsa.gov/api/entity-api/

Freshness & coverage

FreshnessLive

GeographicUnited States

Temporal… → present — Current public entity registrations and active exclusions returned by SAM.gov.

AuthenticationCredentials required (API key)

Caveats

⚠ Public API-key limits vary by account role.
⚠ A missing record does not prove that an entity does not exist.
⚠ Legacy D&B-supplied fields carry GSA-published attribution and permissible-use limits.

Methods (4)

searchEntities

read

Search public SAM registrations by legal name, UEI, or CAGE code.

Entitiesbusiness, federal-registration

Paginationpage (pageField: page)

FreshnessLive

Input schema

{
  "type": "object",
  "properties": {
    "legalBusinessName": {
      "type": "string",
      "maxLength": 200
    },
    "uei": {
      "type": "string",
      "minLength": 12,
      "maxLength": 12
    },
    "cageCode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5
    },
    "registrationStatus": {
      "type": "string",
      "enum": [
        "A",
        "E"
      ]
    },
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "page": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    }
  },
  "additionalProperties": false
}

Output schema

{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer"
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "page": {
      "type": "integer"
    },
    "source": {
      "type": "string"
    },
    "caveats": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "total",
    "entities",
    "page",
    "source",
    "caveats"
  ],
  "additionalProperties": true
}

At least one identity field is required.

getEntity

read

Retrieve an exact public SAM entity record by UEI.

Required paramsuei

Entitiesbusiness, federal-registration

Paginationnone

FreshnessLive

Input schema

{
  "type": "object",
  "properties": {
    "uei": {
      "type": "string",
      "minLength": 12,
      "maxLength": 12
    }
  },
  "required": [
    "uei"
  ],
  "additionalProperties": false
}

Output schema

{
  "type": "object",
  "properties": {
    "total": {
      "type": "integer"
    },
    "entities": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "page": {
      "type": "integer"
    },
    "source": {
      "type": "string"
    },
    "caveats": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "total",
    "entities",
    "page",
    "source",
    "caveats"
  ],
  "additionalProperties": true
}

searchExclusions

read

Screen active SAM exclusions by name, UEI, or CAGE code.

Entitiesbusiness, federal-exclusion

Paginationpage (pageField: page, limitField: limit)

FreshnessLive

Input schema

{
  "type": "object",
  "properties": {
    "exclusionName": {
      "type": "string",
      "maxLength": 200
    },
    "uei": {
      "type": "string",
      "minLength": 12,
      "maxLength": 12
    },
    "cageCode": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5
    },
    "classification": {
      "type": "string",
      "enum": [
        "Individual",
        "Firm",
        "Vessel",
        "Special Entity Designation"
      ]
    },
    "state": {
      "type": "string"
    },
    "country": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "page": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "additionalProperties": false
}

Output schema

{
  "type": "object",
  "properties": {
    "screeningStatus": {
      "type": "string",
      "enum": [
        "potential_match",
        "no_potential_match"
      ]
    },
    "total": {
      "type": "integer"
    },
    "exclusions": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "page": {
      "type": "integer"
    },
    "limit": {
      "type": "integer"
    },
    "source": {
      "type": "string"
    },
    "caveats": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "screeningStatus",
    "total",
    "exclusions",
    "page",
    "limit",
    "source",
    "caveats"
  ],
  "additionalProperties": true
}

⚠ Name hits remain potential matches until identifiers agree.

Name hits are potential matches until identifiers agree.

getServiceInfo

read

Describe SAM coverage, rate limits, methods, and caveats.

Entitiesservice-metadata

Paginationnone

FreshnessLive (source-level)

Output schema

{
  "type": "object",
  "properties": {
    "service": {
      "type": "string"
    },
    "auth": {
      "type": "string"
    },
    "rateLimits": {
      "type": "object",
      "additionalProperties": true
    },
    "methods": {
      "type": "object",
      "additionalProperties": true
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "service",
    "auth",
    "rateLimits",
    "methods",
    "notes"
  ],
  "additionalProperties": true
}