Quickstart
In this guide you'll create an API key, retrieve one opportunity, list your team's opportunities, and create a new one. It takes about five minutes.
You need:
- Permission to manage team members. Only members with that permission can open the developer pages and create keys.
curl, Node.js 20 or later, or Python 3 withrequests.
1. Create a service account
A service account identifies an integration in GovDash. Changes made with its API keys are attributed to that account, and its role controls which records the integration can read or change.
- Open Developer settings in GovDash.
- Click Create service account.
- Enter a name, such as the system that will call the API, and pick a role. Pick the narrowest role that covers your integration.
- Click Create.
- 1Open Developer
- 2Name it and pick a role
- 3The account joins your team
2. Create an API key
- In the service account's row, click API keys.
- Click Create key.
- Name the key and choose an expiration. The default is 90 days; you can also choose 30 days, 180 days, or no expiry.
- Click Create key, then copy the key from the Copy your API key dialog.
- 1Open the account's API keys
- 2Create a key
- 3Name it and choose an expiration
- 4Copy the key now
Warning
GovDash shows the key once. After you click I've copied it, you can't see it again. If you lose it, create a new key and revoke the old one.
Keys start with gd_live_. Store yours in an environment variable along with the base URL:
export GOVDASH_API_KEY="gd_live_..."
export GOVDASH_API_URL="https://api.govdash.us"
export GOVDASH_API_VERSION="2026-11-17"Developer settings shows the base URL for your environment. Pin GOVDASH_API_VERSION to the version you tested; change it when you deliberately upgrade.
3. Retrieve an opportunity
Use the id from a list response, or copy just the id segment from an opportunity's URL in GovDash, not the entire URL. The API uses the same ids as the app. For example, if your opportunity's id is 1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31, set:
export OPPORTUNITY_ID="1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31"Replace that example id with one from your team. If you don't have one yet, list opportunities first.
curl "$GOVDASH_API_URL/v1/opportunities/$OPPORTUNITY_ID" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/opportunities/${process.env.OPPORTUNITY_ID}`,
{
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.get(
f"{os.environ['GOVDASH_API_URL']}/v1/opportunities/{os.environ['OPPORTUNITY_ID']}",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())A 200 returns the opportunity:
{
"id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
"object": "opportunity",
"team_id": "8e2d4b6a-1f3c-4a5e-b7d9-0c2e4f6a8b1d",
"created_at": "2026-10-01T14:02:11.000Z",
"updated_at": "2026-10-28T09:15:40.000Z",
"title": "Cloud migration support",
"description": null,
"phase": { "id": "5a7c9e1b-2d4f-4b6a-8c0e-3f5a7b9d1c2e", "name": "Qualify" },
"solicitation_number": null,
"agency_id": null,
"estimated_value": null,
"due_date": null,
"posted_date": null,
"source_url": null,
"classification": "UNCLASSIFIED"
}If you get something else:
401means GovDash didn't accept the key. Check that you copied all of it and sent it asAuthorization: Bearer <key>.404means the opportunity isn't visible to this key. The id might be wrong, belong to another team, or be classified above what the key can read.
See Errors for every status the API returns.
4. List opportunities
curl "$GOVDASH_API_URL/v1/opportunities?limit=5" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/opportunities?limit=5`,
{
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.get(
f"{os.environ['GOVDASH_API_URL']}/v1/opportunities?limit=5",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())Lists return the most recently updated opportunities first. Every list endpoint returns the same shape: a page of edges, each holding one object as its node, and a pageInfo that tells you whether there's another page.
{
"edges": [
{
// One opportunity, with the same fields as the response above.
"node": {
"id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
"object": "opportunity",
"title": "Cloud migration support",
// ...
},
"cursor": "eyJ2IjoxLCJhZnRlciI6IjFjOWY3YTUyIn0",
},
// ...up to `limit` edges
],
"pageInfo": {
// true means there's another page. Pass endCursor as `cursor` to get it.
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "eyJ2IjoxLCJhZnRlciI6IjFjOWY3YTUyIn0",
"endCursor": "eyJ2IjoxLCJhZnRlciI6IjFjOWY3YTUyIn0",
},
}See Pagination to walk through every page.
5. Create an opportunity
title and classification are required. Titles must be unique within your team.
curl "$GOVDASH_API_URL/v1/opportunities" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Content-Type: application/json" \
-d '{
"title": "API test opportunity",
"classification": "UNCLASSIFIED"
}'const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/opportunities`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
"Content-Type": "application/json",
},
body: JSON.stringify({
title: "API test opportunity",
classification: "UNCLASSIFIED",
}),
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.post(
f"{os.environ['GOVDASH_API_URL']}/v1/opportunities",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
json={'title': 'API test opportunity', 'classification': 'UNCLASSIFIED'},
)
response.raise_for_status()
print(response.json())A 201 returns the new opportunity. Sending the same title again returns 409 conflict and creates nothing.
Next steps
- Clean up the test record with
DELETE /v1/opportunities/{id}. It returns202and finishes in the background. - Read Requests and responses for the conventions every endpoint shares.
- Work through the examples.
- Browse every endpoint in the API reference.