Search (name + filters)

Filter-based entity search. Every filter works on every plan, including the free trial (changed 2026-09-12: the filters used to require Pro). The DSBS replacement: programmatic NAICS x state x certification x active-status filtering across the SAM directory.

Parameters

• q - Name substring (2-250 chars, case-insensitive, trigram-indexed). Any plan (including the free trial).
• naics - 6-digit NAICS code, no Y/N suffix. Matches both primary_naics and any code in naics_codes[]. This is SAM's self-reported code (including the firm's own per-NAICS Y small-business flag).
• naics_small - 6-digit NAICS code (a non-6-digit value returns 400). Restricts to firms that are SBA-small for that NAICS per the SBA Dynamic Small Business Search (DSBS): SBA's authoritative small-business determination, distinct from the self-reported naics flag above. Matches the ~604K DSBS small-business registrants, so large primes are never returned. Echoed in the query block.
• state - 2-character US state code.
• business_type - 2-3 character SAM business-type code (e.g. 8W = WOSB, QF = SDVOSB, 27 = Self-Cert SDB). Unknown codes return 400.
• active_only - true restricts to registration_status='A'.
• limit - Results per page. Default 100; maximum 100 on the free trial and 1,000 on paid plans. Over the maximum returns 402.
• offset - Pagination offset (default 0).
• fields - Comma-separated response fields. uei always included. Example: fields=uei,legal_business_name,primary_naics. See Response Shaping.

At least one of q / naics / naics_small / state / business_type / active_only must be provided.

Response

The row array is returned under BOTH results AND data (identical contents). Either key is safe to read.

{
  "query": {"q": null, "naics": "541330", "naics_small": null, "state": "CA", "business_type": "8W", "active_only": true},
  "pagination": {"limit": 20, "offset": 0, "total": 487, "has_next": true},
  "results": [
    {
      "uei": "...",
      "legal_business_name": "ACME ENGINEERING LLC",
      "dba_name": null,
      "registration_status": "A",
      "registration_expiration_date": "2026-08-12",
      "primary_naics": "541330",
      "business_types": ["27", "2X", "8W", "A2", "LJ"],
      "business_types_labels": [
        "Self Certified Small Disadvantaged Business",
        "For Profit Organization",
        "Women-Owned Small Business (WOSB)",
        "Woman-Owned Business",
        "Limited Liability Company"
      ],
      "physical_city": "OAKLAND",
      "physical_state": "CA",
      "physical_country": "USA"
    }
  ],
  "data": [ "...same rows as results above..." ]
}

Examples

# Any plan: name search
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/entities/search?q=KAMPI&limit=5"

# multi-filter (any plan)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/entities/search?state=CA&business_type=8W&active_only=true"

# Pro: name + SBA-small-for-NAICS (DSBS). "defense" firms that are SBA-small for 541512.
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/entities/search?q=defense&naics_small=541512&limit=1"

The naics_small example returns 303 firms (the SAM directory holds far more "defense" firms, this is the subset SBA rates as small for 541512):

{
  "query": {"q": "defense", "naics": null, "naics_small": "541512", "state": null, "business_type": null, "active_only": false},
  "pagination": {"limit": 1, "offset": 0, "total": 303, "total_is_estimate": false, "has_next": true},
  "results": ["...one entity row per the shape above..."]
}

A bare naics_small filter (no q) matches a large slice of the directory, so its total is capped and returned as an estimate (total_is_estimate: true); page forward on has_next.

Errors: 400 (no params provided OR unknown business_type), 401, 402 (Pro filter without contacts_access), 422 (validation), 429.

Note: Results are ranked by name similarity when q is provided; filter-only searches are ordered by legal_business_name. SBA-certified codes (A6=8(a), XX=HUBZone, A4=SBA-SDB) are essentially absent from this dataset; the closest available signals are self-cert variants (27, 8W, QF).