SAM.gov Public APIs – Public Data Connector Prototype

This technical guide outlines the integration of SAM.gov public APIs into a data connector prototype. It covers the core implementation workflows for entity identity resolution, historical contract tracking, exclusion screening, and procurement intelligence.

SAM.gov Public APIs – Public Data Connector Prototype

Introduction to SAM.gov APIs

SAM.gov provides public APIs for direct access to federal entity data, contract awards, exclusions, procurement opportunities, and bulk data downloads. These APIs allow teams to seamlessly integrate official government data into analytics platforms, compliance tools, or market intelligence systems.

Important Notes:

  • Most APIs require a Public API Key obtained from your SAM.gov account (Account Details page).
  • Rate limits vary by account type: Non-federal users without a role are limited to 10 requests/day; users with roles or system accounts can reach 1,000–10,000 requests/day.
  • Some data may include Dun & Bradstreet (D&B) information with usage restrictions.
  • For prototypes, always use public data and respect GSA terms of service.

1. SAM.gov Entity Management API

Official Documentation: https://open.gsa.gov/api/entity-api/

Description: Retrieves public entity registration information including UEI, legal business name, registration status, UEI status, creation/expiration dates, public display flag, and more. Supports Public, FOUO, and Sensitive data depending on your account permissions.

Main Endpoint: GET https://api.sam.gov/entity-information/v3/entities (v4 also available)

Key Query Parameters

  • api_key: Required – Your Public API Key
  • ueiSAM: Unique Entity Identifier (single 12-character or up to 100 values)
  • cageCode: 5-character CAGE code (single or up to 100 values)
  • samRegistered: Yes / No (default Yes)
  • registrationStatus: ID Assigned, Active, Expired, etc.
  • ueiStatus: Active, Inactive, etc.
  • legalBusinessName, dbaName: Partial or complete business name search
  • physicalAddressCity, physicalAddressStateCode, physicalAddressCountryCode, physicalAddressZipCode
  • Date filters (single date or range [MM/DD/YYYY,MM/DD/YYYY]): registrationDate, activationDate, updateDate, registrationExpirationDate, ueiCreationDate, ueiExpirationDate
  • publicDisplayFlag: Y / N
  • includeSections: entityRegistration, entityOverview, entityGeneralInformation, etc.
  • page, size: Pagination
  • q: Free text search (supports advanced operators)

Example cURL

curl -X GET "https://api.sam.gov/entity-information/v3/entities?api_key=YOUR_API_KEY&samRegistered=No&includeSections=entityRegistration&size=10"
Entity Management API Example

2. SAM.gov Contract Awards API

Official Documentation: https://open.gsa.gov/api/contract-awards/

Description: Provides detailed federal contract award records (Awards & IDVs) including awardee information, obligated dollars, awarding agency, NAICS/PSC codes, competition details, and more. Supports Revealed and Unrevealed data.

Main Endpoint: GET https://api.sam.gov/contract-awards/v1/search

Key Query Parameters

  • api_key: Required
  • limit: Max 100 records per page (default 10)
  • offset: Pagination
  • uei / awardeeUniqueEntityId: UEI of awardee (up to 100 values)
  • awardeeCageCode: CAGE code (up to 100 values)
  • dollarsObligated, totalDollarsObligated: Single value or range [min,max]
  • Date parameters (single or range [MM/DD/YYYY,MM/DD/YYYY]): lastModifiedDate, dateSigned, approvedDate, createdDate, closedDate, periodOfPerformanceStartDate, etc.
  • naicsCode, productOrServiceCode: NAICS & PSC codes (up to 100 values)
  • contractingDepartmentCode, contractingSubtierCode, contractingOfficeCode
  • piid, modificationNumber, solicitationID
  • piidAggregation=yes (requires piid)
  • deletedStatus=yes
  • includeSections: contractId, coreData, awardDetails, awardeeData, nasaSpecific
  • q: Free text search
  • format: csv / json (for asynchronous bulk extract) and more...

Example cURL

curl -X GET "https://api.sam.gov/contract-awards/v1/search?api_key=YOUR_API_KEY&lastModifiedDate=[01/01/2025,]&dollarsObligated=[0.0,100000000.99]&contractingDepartmentCode=9700"
Contract Awards API Example

3. SAM.gov Exclusions API

Official Documentation: https://open.gsa.gov/api/exclusions-api/

Description: Search for entities and individuals that have been debarred, suspended, or excluded from federal contracting.

Main Endpoint: GET https://api.sam.gov/entity-information/v4/exclusions

Key Query Parameters

  • api_key: Required
  • q: Free text search (supports AND, OR, :, =, wildcard *)
  • ueiSAM / samUEI
  • cageCode
  • classification: Firm, Individual, Special Entity, Vessel
  • exclusionType, exclusionProgram, excludingAgencyCode
  • stateProvince, country, zipCode, addressLine1, addressLine2
  • Date filters (single or range): activationDate, creationDate, updateDate, terminationDate
  • page, size (size max 10)
  • includeSections: exclusionDetails, exclusionIdentification, exclusionActions, etc.

Example cURL

curl -X GET "https://api.sam.gov/entity-information/v4/exclusions?api_key=YOUR_API_KEY&classification=Firm&stateProvince=VA"
Exclusions API Example

4. SAM.gov Get Opportunities Public API

Official Documentation: https://open.gsa.gov/api/get-opportunities-public-api/

Description: Search for active contracting opportunities, solicitations, pre-solicitations, and award notices.

Main Endpoint: GET https://api.sam.gov/opportunities/v2/search

Key Query Parameters

  • api_key: Required
  • postedFrom and postedTo: Required (MM/DD/YYYY format, max 365 days range)
  • title: Keyword search in title
  • noticeType / ptype: p (Pre-solicitation), a (Award), r (Solicitation), etc.
  • solnum, noticeid
  • organizationName, state, zip
  • active: Yes / No
  • limit (max 1000), offset: Pagination

Example cURL

curl -X GET "https://api.sam.gov/opportunities/v2/search?limit=10&api_key=YOUR_API_KEY&postedFrom=01/01/2025&postedTo=05/10/2025&title=Driving"
Get Opportunities API Example

5. SAM.gov Entity/Exclusions Extracts Download API

Official Documentation: https://open.gsa.gov/api/sam-entity-extracts-api/

Description: Download large monthly or daily bulk ZIP files containing complete public entity or exclusion datasets in flat file format.

Main Endpoint: GET https://api.sam.gov/data-services/v1/extracts

Key Query Parameters

  • api_key: Required
  • fileName: Exact filename (e.g. SAM_PUBLIC_MONTHLY_V2_YYYYMMDD.ZIP)
  • fileType: ENTITY or EXCLUSION
  • sensitivity: PUBLIC, FOUO, SENSITIVE (default PUBLIC)
  • frequency: MONTHLY or DAILY (default MONTHLY)
  • charset: ASCII or UTF8
  • date: Specific extract date (MM/DD/YYYY or MM/YYYY)

Example cURL

curl -X GET "https://api.sam.gov/data-services/v1/extracts?api_key=YOUR_API_KEY&fileName=SAM_PUBLIC_MONTHLY_V2_20220403.ZIP"
Entity/Exclusions Extracts API Example

Conclusion & Best Practices

These SAM.gov APIs are highly valuable for public data ingestion. Start with Entity Management and Contract Awards for most prototype use cases. Always handle pagination properly, store your API key securely, and monitor rate limits. Refer to the official documentation for the complete and most up-to-date list of parameters.

Use tools like Postman and the provided screenshots for testing.