# SAM.gov

> 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.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://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`):**

| Code       | Description                                                 |
| ---------- | ----------------------------------------------------------- |
| `SBA`      | Total Small Business Set-Aside (FAR 19.5)                   |
| `SBP`      | Partial Small Business Set-Aside (FAR 19.5)                 |
| `8A`       | 8(a) Set-Aside (Competitive)                                |
| `8AN`      | 8(a) Set-Aside (Sole Source)                                |
| `HZC`      | HUBZone Set-Aside (Competitive)                             |
| `HZS`      | HUBZone Set-Aside (Sole Source)                             |
| `SDVOSBC`  | Service-Disabled Veteran-Owned Small Business (Competitive) |
| `SDVOSBS`  | Service-Disabled Veteran-Owned Small Business (Sole Source) |
| `WOSB`     | Women-Owned Small Business (Competitive)                    |
| `WOSBSS`   | Women-Owned Small Business (Sole Source)                    |
| `EDWOSB`   | Economically Disadvantaged WOSB (Competitive)               |
| `EDWOSBSS` | Economically Disadvantaged WOSB (Sole Source)               |
| `LAS`      | Local Area Set-Aside                                        |
| `IEE`      | Indian Economic Enterprise                                  |
| `ISBEE`    | Indian Small Business Economic Enterprise                   |
| `BI`       | Buy Indian                                                  |
| `VSA`      | Veteran-Owned Small Business (Competitive)                  |
| `VSS`      | Veteran-Owned Small Business (Sole Source)                  |

**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:**

```json
{
  "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:**

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

**Example — paginate through large result sets:**

```json
{
  "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

| Status | Meaning                                                                                                                                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Success                                                                                                                                                                                                           |
| `400`  | Bad request — invalid parameter values, missing `postedFrom`/`postedTo`, date range exceeds 1 year, invalid date format (must be `MM/dd/yyyy`), `limit` or `offset` out of range, or `ncode` longer than 6 digits |
| `404`  | No data found for the given filters                                                                                                                                                                               |
| `500`  | Internal server error                                                                                                                                                                                             |

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.