Quick Start Guide¶
Get up and running with the Tango API in 5 minutes or less.
Prerequisites¶
- Basic knowledge of HTTP and JSON
- A web browser or API client (like Postman, Insomnia, or curl)
- Optional: Programming language of your choice (Python, JavaScript, etc.)
Step 1: Get Your API Key¶
- Visit Tango Web Interface
- Sign up for an account or log in
- Navigate to your API keys section
- Create a new API key
- Copy your API key (you'll need it for all requests)
Note: The API requires authentication for all access. Anonymous access is not supported. You'll need an API key for any usage.
Step 2: Make Your First API Call¶
Pull the five most recently awarded federal contracts:
curl -H "X-API-KEY: your-api-key-here" \
"https://tango.makegov.com/api/contracts/?limit=5&ordering=-award_date"
import requests
headers = {"X-API-KEY": "your-api-key-here"}
response = requests.get(
"https://tango.makegov.com/api/contracts/",
params={"limit": 5, "ordering": "-award_date"},
headers=headers,
)
data = response.json()
for contract in data["results"]:
print(contract["piid"], contract["recipient"]["display_name"], contract["obligated"])
const params = new URLSearchParams({ limit: "5", ordering: "-award_date" });
const response = await fetch(`https://tango.makegov.com/api/contracts/?${params}`, {
headers: { "X-API-KEY": "your-api-key-here" },
});
const data = await response.json();
for (const contract of data.results) {
console.log(contract.piid, contract.recipient.display_name, contract.obligated);
}
Step 3: Explore the Response¶
You'll get a paginated response shaped like this:
{
"count": 9824315,
"next": "https://tango.makegov.com/api/contracts/?limit=5&ordering=-award_date&cursor=cD0yMDI2LTA1LTEx",
"previous": null,
"results": [
{
"key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-",
"piid": "47QSWA24P0BWF",
"recipient": {
"display_name": "ACME Corporation",
"uei": "ZMXAHH8M8VL8"
},
"award_date": "2026-05-11",
"obligated": 1500000.00,
"description": "IT Services Contract"
}
]
}
Step 4: Try a More Complex Query¶
Now let's find active opportunities in a specific industry and agency:
curl -H "X-API-KEY: your-api-key-here" \
"https://tango.makegov.com/api/opportunities/?naics=541512&active=true&agency=DOD&ordering=response_deadline&limit=5"
import requests
headers = {"X-API-KEY": "your-api-key-here"}
response = requests.get(
"https://tango.makegov.com/api/opportunities/",
params={
"naics": "541512",
"active": "true",
"agency": "DOD",
"ordering": "response_deadline",
"limit": 5,
},
headers=headers,
)
for opp in response.json()["results"]:
print(opp["response_deadline"], opp["opportunity_id"], opp["title"])
const params = new URLSearchParams({
naics: "541512", active: "true", agency: "DOD",
ordering: "response_deadline", limit: "5",
});
const response = await fetch(`https://tango.makegov.com/api/opportunities/?${params}`, {
headers: { "X-API-KEY": "your-api-key-here" },
});
for (const opp of (await response.json()).results) {
console.log(opp.response_deadline, opp.opportunity_id, opp.title);
}
This query:
- Filters by NAICS
541512(Computer Systems Design Services) - Restricts to DOD opportunities
- Returns only currently-biddable opportunities (
active=true) - Orders by response deadline (soonest first)
- Limits to 5 results
For more on multi-value filters, agency resolution, and webhook subscriptions for new opportunities, see the Search opportunities by NAICS guide.
Step 5: Understand the Response Format¶
Most list endpoints return paginated responses. The count may be exact or approximate depending on the endpoint (see Result counts) — check the X-Results-CountType response header to know which:
{
"count": 1250,
"next": "https://tango.makegov.com/api/opportunities/?...&page=2",
"previous": null,
"results": [
{
"opportunity_id": "75D30126R00012",
"title": "Cyber Workforce Development Services",
"naics_code": 541512,
"psc_code": "D316",
"set_aside": "SBA",
"response_deadline": "2026-06-14T17:00:00Z",
"first_notice_date": "2026-05-08T15:32:11Z",
"active": true,
"sam_url": "https://sam.gov/opp/75D30126R00012/view",
"office": {
"office_code": "FA7014",
"office_name": "FA7014 AFDW PK",
"agency_code": "5700",
"agency_name": "Department of the Air Force"
},
"meta": {
"notices_count": 5,
"notice_type": {"code": "o", "type": "Solicitation"}
}
}
]
}
Step 6: Use Response Shaping to Customize Your Data¶
Response shaping lets you request only the specific fields you need, reducing data transfer and speeding up your application.
Basic Shaping Example¶
Instead of receiving all fields, request just what you need using the shape parameter:
curl -H "X-API-KEY: your-api-key-here" \
"https://tango.makegov.com/api/contracts/?shape=key,piid,award_date,recipient(display_name,uei)&limit=5"
This request returns only:
- Contract key
- PIID (contract identifier)
- Award date
- Recipient name and UEI (nested)
Why Use Response Shaping?¶
- Faster responses: Less data to transfer means quicker API calls
- Reduced bandwidth: Only get the fields you actually need
- Cleaner code: Shape the response to match your application's data model
- Flexible expansions: Include related data (offices, transactions, recipients) without separate API calls
Response Example¶
{
"count": 1250,
"results": [
{
"key": "CONT_AWD_47QSWA24P0BWF_4732_-NONE-_-NONE-",
"piid": "47QSWA24P0BWF",
"award_date": "2024-01-15",
"recipient": {
"display_name": "ACME Corporation",
"uei": "ZMXAHH8M8VL8"
}
}
]
}
Learn more about advanced features like flattening, aliasing, and multiple expansions in the Response Shaping Guide.
Common Issues¶
Rate Limit Exceeded¶
If you see a 429 Too Many Requests error, you've hit a rate limit. Check X-RateLimit-Remaining and X-RateLimit-Reset (seconds until reset), and follow the retry guidance in the Rate limits guide.
Authentication Error¶
If you get a 401 Unauthorized error, check that:
- Your API key is correct
- You're including the
X-API-KEYheader - Your API key is active
Invalid Request¶
If you get a 400 Bad Request error, check that:
- Your URL parameters are properly formatted
- Required parameters are included
- Date formats are YYYY-MM-DD