Integration Examples

1. Plan Verification Workflow

Step 1: Check your plan level

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/me"

Response: {"plan":"developer","email":"[email protected]"}

Step 2: Build the query

Multi-filter search (every plan supports all filters; paid plans get higher page size and rate limit):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/opportunities/search?agency=defense&notice_type=Award%20Notice&value_min=1000000"

Single-filter search:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://govconapi.com/api/v1/opportunities/search?naics=541330&state=CA"

2. Pagination Best Practices

Efficient pagination within a filtered query:

To keep a local mirror in sync, use /opportunities/delta with a since cursor (it returns only changed records). /search pagination is intended for paging through filtered result sets, not full-corpus backfill. For an initial historical backfill, page a date-filtered search (the free trial reaches the last 90 days).

offset=0
limit=100
total_collected=0
filter="naics=541330"   # narrows the pull; every filter is optional

while true; do
  response=$(curl -s -H "Authorization: Bearer YOUR_API_KEY" \
    "https://govconapi.com/api/v1/opportunities/search?${filter}&limit=$limit&offset=$offset")

  has_next=$(echo "$response" | jq -r '.pagination.has_next')
  data_length=$(echo "$response" | jq '.data | length')

  total_collected=$((total_collected + data_length))
  echo "Collected $total_collected records..."

  if [ "$has_next" != "true" ] || [ "$data_length" -eq 0 ]; then
    break
  fi

  offset=$((offset + limit))
  sleep 0.1
done

Note: Be respectful of the API with small delays between requests

4. Working with Attachments

Option 1: Filter for opportunities with attachments (Developer plan):

import requests

API_KEY = "your_api_key"
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get(
    "https://govconapi.com/api/v1/opportunities/search?has_attachments=true&limit=20",
    headers=headers
)
results = response.json()

Option 2: Get attachments for specific opportunity:

import requests

# From search results
notice_id = results['data'][0]['notice_id']

# Get attachments via dedicated endpoint
attachments = requests.get(
    f"https://govconapi.com/api/v1/opportunities/{notice_id}/attachments",
    headers=headers
).json()

# Download files (SAM.gov URLs, no auth needed)
for url in attachments['attachments']:
    file_response = requests.get(url)
    # Save file to disk
    with open(f"attachment_{attachments['attachments'].index(url)}.pdf", "wb") as f:
        f.write(file_response.content)

Option 3: Use existing field in search response:

import requests

# Attachments already included in search response
for opp in results['data']:
    if opp.get('resource_links_array'):
        print(f"Opportunity {opp['notice_id']} has {len(opp['resource_links_array'])} attachments")
        for url in opp['resource_links_array']:
            file_response = requests.get(url)
            # Process attachment directly

Which approach to use? Use resource_links_array from search results when processing multiple opportunities. Use the /attachments endpoint only if you need attachments for one specific opportunity without fetching the full record.

Feature Reference

Plan Restrictions Summary

All search filters (NAICS, PSC, state, keywords, agency, dates, location, amounts, set-aside, has_attachments, etc.) are available on every plan, including the 14-day free trial. The larger page size (1,000 vs 100) and the 1,000/hour rate limit require the Developer plan.

Current Database Stats (Live)

• Contract Opportunities: Loading...
• Data Current As Of: Loading...

Loaded live from /api/v1/status: per-source counts + freshness for every dataset. Send your API key for exact counts.

Federal Contracting Officers Directory

Need direct contact with government buyers? Our sister site contacts.govconapi.com provides verified contact information for federal contracting officers with phone numbers, emails, agency details, and recent procurement activity.

Need Help?

Questions or issues? Contact [email protected]

API Status: https://govconapi.com/health

Interactive Docs: https://govconapi.com/docs (auto-generated from OpenAPI schema)