Response Shaping

Search and list endpoints accept a fields query parameter to return only the columns you need. Reduces payload size dramatically when you only care about a few fields out of dozens.

Syntax: comma-separated list of field names from the response shape.

# Default, returns all 59 fields per opportunity record
curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/opportunities/search?naics=541512&limit=20"

# With ?fields=, returns only the 4 columns requested (~95% smaller response)
curl -H "Authorization: Bearer $KEY" \
  "https://govconapi.com/api/v1/opportunities/search?naics=541512&limit=20&fields=notice_id,title,posted_date,response_deadline"

Supported endpoints:

• GET /api/v1/opportunities/search, primary key always included: notice_id
• GET /api/v1/exclusions/search, primary key: uei_sam
• GET /api/v1/awards/search, primary key: notice_id
• GET /api/v1/companies/search, primary key: uei
• GET /api/v1/companies/{uei}/awards, primary key: notice_id
• GET /api/v1/entities/search, primary key: uei
• GET /api/v1/subawards/search, primary key always included: subaward_sam_report_id
• GET /api/v1/companies/{uei}/subawards, primary key: subaward_sam_report_id
• GET /api/v1/companies/{uei}/prime-relationships, primary key: subaward_sam_report_id

Behavior:

• The endpoint's primary key column is always included so you can correlate response rows to your query, even if you don't list it.
• If you list an unknown field, you get 400 Bad Request with the valid field names for that endpoint. No silent typos.
• Omit fields= entirely to get the full default response shape (backwards compatible).
• Works alongside all other query parameters (filters, sort, pagination).

When to use it: any time you're paginating through results and only need a subset of columns. Common cases: building a search-results UI (need 4-6 columns, not 59); ETL pipelines (need stable identifiers + a few timestamps); monitoring (need notice_id, title, last_seen).