SAM.gov

Authentication Type: API Key Description: Search federal government contract opportunities on SAM.gov using the Opportunities API v2. Filter by posted date, procurement type, set-aside, NAICS code, agency, and more.

Authentication

To authenticate, you need a SAM.gov public API key:

1. Sign in or register at SAM.gov
2. Go to Account Details → Public API Key
3. Generate or copy your key

The API key is passed as the api_key query parameter on every request. Your key is stored securely in Cotera's credential manager — never share it or hard-code it in prompts.

Search Opportunities

Search Opportunities

Search for federal contract opportunities on SAM.gov using flexible filters.

Operation Type: Query (Read)

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

Alpha environment: A staging endpoint is also available at https://api-alpha.sam.gov/opportunities/v2/search. Use the same parameters and API key. The alpha environment may receive newer features before production.

Date format: All date parameters use MM/dd/yyyy (e.g., "07/01/2024").

Date range limit: postedFrom and postedTo must be within the same calendar year (max 1-year range). Exceeding this returns a 400 error.

Parameters:

• postedFrom string (required): Start of the posted-date range. Format MM/dd/yyyy.
• postedTo string (required): End of the posted-date range. Format MM/dd/yyyy. Must be within 1 year of postedFrom.
• ptype string (nullable): Procurement type code(s). Comma-separate multiple values. Common codes:
  • o — Solicitation
  • p — Presolicitation
  • k — Combined synopsis/solicitation
  • r — Sources sought
  • s — Special notice
  • g — Sale of surplus property
  • i — Intent to bundle requirements
  • a — Award notice
  • j — Justification and approval
  • m — Modification/amendment
  • u — Justification (sole source)
  • n — Fair opportunity / limited sources
  • l — Fair opportunity justification
• solnum string (nullable): Solicitation number filter
• noticeid string (nullable): Notice ID filter
• title string (nullable): Keyword search in notice title
• state string (nullable): Two-letter US state code for place of performance (e.g., "VA", "CA")
• status string (nullable): Opportunity status. Options: "active" (default), "inactive", "archived", "cancelled", "deleted"
• zip string (nullable): ZIP code for place of performance
• organizationCode string (nullable): Agency/organization code
• organizationName string (nullable): Agency/organization name keyword filter
• typeOfSetAside string (nullable): Set-aside type code (see set-aside values below)
• typeOfSetAsideDescription string (nullable): Set-aside description keyword filter
• ncode string (nullable): NAICS code (up to 6 digits, e.g., "541512")
• ccode string (nullable): PSC (Product and Service Code) / classification code
• rdlfrom string (nullable): Response deadline start filter. Format MM/dd/yyyy.
• rdlto string (nullable): Response deadline end filter. Format MM/dd/yyyy.
• limit number: Results per page. Maximum 1000. Default 10.
• offset number: Number of results to skip (for pagination). Default 0.

Set-aside type codes (typeOfSetAside):

Returns:

• totalRecords number: Total matching opportunities across all pages
• limit number: Limit used in the request
• offset number: Offset used in the request
• opportunitiesData array: List of matching opportunity objects
  • noticeId string (nullable): Unique notice identifier
  • title string (nullable): Opportunity title
  • solicitationNumber string (nullable): Solicitation number
  • fullParentPathName string (nullable): Full agency hierarchy path (display names, e.g., "DEPT OF DEFENSE.DEPT OF THE ARMY")
  • fullParentPathCode string (nullable): Full agency hierarchy path (agency codes)
  • postedDate string (nullable): Date the notice was posted
  • type string (nullable): Notice type description (e.g., "Solicitation")
  • baseType string (nullable): Base notice type
  • archiveType string (nullable): Archive type: auto15, auto30, autocustom, or manual
  • archiveDate string (nullable): Date the notice will be or was archived
  • typeOfSetAside string (nullable): Set-aside type code
  • typeOfSetAsideDescription string (nullable): Set-aside description
  • responseDeadLine string (nullable): Proposal/response deadline (note: SAM.gov spells this responseDeadLine)
  • naicsCode string (nullable): NAICS code
  • classificationCode string (nullable): PSC/classification code
  • active string (nullable): Whether the opportunity is active ("Yes" or "No")
  • description string (nullable): Full opportunity description text
  • organizationType string (nullable): Organization type
  • uiLink string (nullable): Direct URL to the opportunity on SAM.gov
  • additionalInfoLink string (nullable): Additional information URL

Example — search for active IT solicitations in Virginia:

{
  "postedFrom": "01/01/2024",
  "postedTo": "12/31/2024",
  "ptype": "o",
  "state": "VA",
  "ncode": "541512",
  "status": "active",
  "limit": 25,
  "offset": 0
}

Example — search for 8(a) set-aside opportunities:

{
  "postedFrom": "06/01/2024",
  "postedTo": "12/31/2024",
  "typeOfSetAside": "8A",
  "limit": 50,
  "offset": 0
}

Example — paginate through large result sets:

{
  "postedFrom": "01/01/2024",
  "postedTo": "06/30/2024",
  "limit": 1000,
  "offset": 1000
}

Pagination

SAM.gov paginates results using limit and offset:

• totalRecords in the response is the total count of matching opportunities
• limit max is 1000 per request
• To retrieve page 2 of 1000 results: set offset: 1000
• Example for page N (0-indexed): offset = N * limit

Error Reference

Common 400 causes:

• postedFrom or postedTo missing or in wrong format (must be MM/dd/yyyy, not ISO 8601)
• Date range between postedFrom and postedTo exceeds 1 year
• limit exceeds 1000 or is non-positive
• offset is negative
• ncode contains more than 6 digits

Authentication errors:

• Missing api_key: returns 400 or 403
• Invalid api_key: returns 403

Description errors:

• If a notice description is unavailable, description will be null

Common Use Cases

Government contracting pipeline:

Search for active solicitations in your agency target list, filter by NAICS code, and monitor new opportunities daily by sliding the date window forward.

Set-aside opportunity tracking:

Filter by typeOfSetAside codes (e.g., SDVOSBC, 8A, WOSB) to find opportunities reserved for specific small business categories.

Proposal deadline management:

Use rdlfrom and rdlto to find opportunities with response deadlines in an upcoming window, then track responseDeadLine for each result.

Agency spend analysis:

Search by organizationName or organizationCode to enumerate all opportunities from a target agency and aggregate by naicsCode, classificationCode, or set-aside type.