Skip to content

Opportunities Data Dictionary

This document describes the fields available in the Opportunities API endpoints (/api/opportunities/). For filtering, ordering, and pagination, see the Opportunities API Reference.

Overview

Opportunities represent SAM.gov contract opportunity notices aggregated by parent opportunity (one opportunity can have multiple notices over time). Each opportunity has an opportunity_id. Data is sourced from SAM.gov.

Note: The full set of fields is available via the shape query parameter. See Response Shaping for details.

Update Frequency

Opportunity data is refreshed from SAM.gov on a regular sync cadence (typically 20–60 minutes).

Fields

Field Type Description Source
opportunity_id UUID Primary identifier for the opportunity in Tango (parent notice). Tango / SAM.gov
latest_notice_id UUID The Tango notice_id of the latest notice associated with this opportunity (when available). Tango
active Boolean Whether the opportunity is active. Tango (derived)
archive_date DateTime Archive date for the opportunity (derived from SAM.gov notice archive metadata when present). Tango / SAM.gov
agency_id String Agency code associated with the opportunity (when available). Tango / SAM.gov
award_amount String Award amount from the opportunity's own award notice, as SAM publishes it (a string, not a number). null unless SAM posted an award notice. SAM.gov
award_count Integer On a solicitation, the total number of award opportunities linked back to it (not capped). null when none are linked. Tango (derived)
award_date Date Award date from the opportunity's own award notice. SAM.gov
award_number String Award number when awarded. SAM.gov
awarded Boolean true when the opportunity carries an award number or has award notices linked back to it. Never null. Independent of active. Tango (derived)
awardee String Awardee name from the opportunity's own award notice. SAM.gov
awardee_uei String Awardee UEI from the opportunity's own award notice. SAM.gov
awards Array On a solicitation, up to ten of the most recent linked awards. Use expansion for subfields; see below. Tango (derived)
department_id String Department code associated with the opportunity (when available). Tango / SAM.gov
description String Opportunity description (from latest notice). SAM.gov
first_notice_date DateTime First notice date. SAM.gov
last_notice_date DateTime Last notice date. SAM.gov
meta Object Metadata: notices_count, attachments_count, files_count, links_count, notice_type. Use expansion for subfields. The three attachment counts are explained in Attachments: files and links. Tango
naics_code String NAICS code. SAM.gov
office Object Contracting office. Use expansion for office_code, office_name, agency_code, agency_name, department_code, department_name. SAM.gov
office_id String Office code associated with the opportunity (when available). Tango / SAM.gov
place_of_performance Object Place of performance. Use expansion for street_address, city, state, zip, country. SAM.gov
primary_contact Object Primary contact (expand for subfields). SAM.gov
secondary_contact Object Secondary contact. SAM.gov
psc_code String Product/Service Code. SAM.gov
response_deadline DateTime Response deadline. SAM.gov
sam_url String Canonical SAM.gov opportunity URL. Tango (derived)
set_aside String Set-aside code. Use expansion set_aside(code,description) for the structured form. SAM.gov
solicitation_number String Solicitation number. SAM.gov
solicitation_opportunity_id UUID On an award, the opportunity_id of the solicitation it was made under. null when the award notice does not reference its solicitation. Tango (derived)
title String Opportunity title (from latest notice). SAM.gov

Expansions (via shape)

  • attachments – attachment_id, file_size, mime_type, name, posted_date, resource_id, type, url, plus the Pro+ sub-fields doc_role, doc_role_alt and extracted_text (each returned only when named explicitly — none ride attachments(*)). type is file or link; see Attachments: files and links.
  • awards – opportunity_id, notice_id, award_number, award_date, award_amount, awardee, awardee_uei for up to ten of the most recent linked awards (award_count is the total)
  • office – office and agency fields
  • agency – code, name, abbreviation
  • department – code, name, abbreviation, description, cgac, website, congressional_justification
  • latest_notice – notice_id, link
  • place_of_performance – address fields
  • meta – notices_count, attachments_count, files_count, links_count, notice_type (with nested notice_type(code, type))

An opportunity's or notice's attachments list holds two different kinds of thing, and each row's type says which one it is. Everything in this section applies to both /api/opportunities/ and /api/notices/.

type What it is What you get
file A document attached to the notice. name, mime_type, file_size and url. Files are the only attachments with extracted text (extracted_text) and a document role (doc_role), both Pro+ sub-fields.
link A URL the notice lists, pointing somewhere else: another procurement system's page for the same solicitation, a portal landing page, or standard reference material. A url, usually no name, and a file_size of 0. A link never has extracted text.

About a third of attachments are links (34% on notices posted in 2026), and almost all links have no name (98%). So a notice can report several attachments and have no documents at all.

files_count / file_count and links_count / link_count need API version 5.9.0 or later; GET /api/version reports what you are calling.

Resource Total Files Links
Opportunities meta.attachments_count meta.files_count meta.links_count
Notices attachment_count file_count link_count
  • The total counts every attachment, links included. It is unchanged by the two newer fields.
  • files_count / file_count is the number of attachments with type file. It counts files attached, not files whose text was successfully extracted.
  • links_count / link_count is the number with type link.
  • Files plus links need not equal the total. An attachment whose type is missing or is anything other than file or link counts only in the total.
  • null means not yet counted, not zero. The file and link counts are integers that are filled in as records are processed, so treat null as unknown.

On opportunities the two fields are part of meta(*), so they arrive in both default shapes. On notices file_count and link_count are top-level fields in the default list and detail shapes.

Does this have documents?

Read the file count: meta.files_count on an opportunity, file_count on a notice. It means the same thing on both:

File count Meaning
Greater than 0 Has documents.
0 No documents: the attachments list holds no file rows.
null Not yet counted. Request attachments and look for a row with type file.

Do not use the total for this: it includes links. A record that has not been counted yet reads null, so handle that case rather than treating it as 0.

Checking the attachments list (every API version)

These requests name only fields that exist on every API version:

# An opportunity
/api/opportunities/{opportunity_id}/?shape=opportunity_id,meta(attachments_count),attachments(type,name,file_size,url)

# A notice
/api/notices/{notice_id}/?shape=notice_id,attachment_count,attachments(type,name,file_size,url)

The responses in this section are illustrative. A notice with links only, where every attachment points somewhere else and there is nothing to read:

{
  "notice_id": "0a1b2c3d-1111-4222-8333-444455556666",
  "attachment_count": 3,
  "attachments": [
    {"type": "link", "name": null, "file_size": 0, "url": "https://piee.eb.mil/sol/xhtml/unauth/search/oppMgmtLink.xhtml?solNo=W912DY26R0001"},
    {"type": "link", "name": null, "file_size": 0, "url": "https://pieetraining.eb.mil/wbt/xhtml/wbt/sol/index.xhtml"},
    {"type": "link", "name": null, "file_size": 0, "url": "https://piee.eb.mil/xhtml/unauth/web/homepage/vendorGettingStartedHelp.xhtml"}
  ]
}

A notice with files and links:

{
  "notice_id": "7e8f9a0b-1111-4222-8333-444455556666",
  "attachment_count": 3,
  "attachments": [
    {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"},
    {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"},
    {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"}
  ]
}

With the counts (API version 5.9.0 or later)

Name the count fields only on API version 5.9.0 or later. On an earlier version they do not exist, and a shape that names an unknown field returns a 400; see Validation & limits.

/api/notices/{notice_id}/?shape=notice_id,attachment_count,file_count,link_count,attachments(type,name,file_size,url)

The files-and-links notice above then reports its counts alongside the list:

{
  "notice_id": "7e8f9a0b-1111-4222-8333-444455556666",
  "attachment_count": 3,
  "file_count": 2,
  "link_count": 1,
  "attachments": [
    {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"},
    {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"},
    {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"}
  ]
}

The same request on an opportunity:

/api/opportunities/{opportunity_id}/?shape=opportunity_id,meta(attachments_count,files_count,links_count),attachments(type,name,file_size,url)

The counts arrive under meta:

{
  "opportunity_id": "3c4d5e6f-1111-4222-8333-444455556666",
  "meta": {"attachments_count": 3, "files_count": 2, "links_count": 1},
  "attachments": [
    {"type": "file", "name": "Solicitation.pdf", "file_size": 482113, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/5f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f/download"},
    {"type": "file", "name": "Attachment 1 - Statement of Work.docx", "file_size": 91502, "url": "https://sam.gov/api/prod/opps/v3/opportunities/resources/files/6a1d2e3f4b5c4d6e9f0a1b2c3d4e5f6a/download"},
    {"type": "link", "name": null, "file_size": 0, "url": "https://www.acquisition.gov/browse/index/far"}
  ]
}

Documents hosted on PIEE

Department of Defense notices whose documents are hosted on PIEE (the Procurement Integrated Enterprise Environment) are the most common links-only case. They typically list a link to the PIEE notice page plus standard reference links, such as vendor training and access instructions, as in the first example above.

Where Tango has retrieved the documents from PIEE, they appear as ordinary file rows. For those rows url is the PIEE notice page, not a direct download, because PIEE offers no per-file download address.

State, local and education records count attachments under their own rules; see the SLED data dictionary.

Notice type codes

Opportunities and notices classify the notice “type” using a short code. These values come from SAM.gov, with Tango normalizing them to the codes below:

Code Meaning
a Award Notice
g Sale of Surplus Property
i Consolidate/(Substantially) Bundle
j Justification and Approval (J&A)
k Combined Synopsis/Solicitation
l Fair Opportunity / Limited Sources Justification (deprecated)
m Modification/Amendment/Cancel
o Solicitation
p Pre solicitation
r Sources Sought
s Special Notice
u Justification (J&A)

Data Sources

  • SAM.gov – Contract opportunity notices, offices, contacts, attachments.
  • Tango – opportunity_id, aggregation, sam_url, active, awarded, and the award-to-solicitation linkage (solicitation_opportunity_id, award_count, awards).

Award fields

SAM.gov posts a contract award as a separate award notice, which appears in Tango as its own opportunity. award_date, award_amount, awardee and awardee_uei are filled only where SAM has posted an award notice, and all four come from the same notice.

An award is linked to its solicitation only when SAM's award notice references it. A linked award carries solicitation_opportunity_id, and the solicitation counts it in award_count and lists it in awards. An award notice posted without that reference stays unlinked.

awarded does not change the meaning of active: an award can be posted on a solicitation that is still open (multiple-award vehicles are the common case), so an opportunity can be both active and awarded.

Usage Notes

Report an issue with this page