Requests and responses
Every endpoint follows the same conventions for request bodies, ids, timestamps, empty values, and deletes. Read this page once and the rest of the API should hold no surprises.
Request bodies
Send JSON with a Content-Type: application/json header. Bodies can be at most 1 MB, and every write takes a single record, so you won't come close.
Request bodies are strict. A field the endpoint doesn't list returns 400 bad_request instead of being ignored, so a typo fails loudly rather than silently doing nothing.
A PATCH changes only the fields you send. Fields you leave out keep their values. Send at least one field.
curl "$GOVDASH_API_URL/v1/opportunities/$OPPORTUNITY_ID" \
-X PATCH \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Content-Type: application/json" \
-d '{ "description": "Recompete of the 2021 award." }'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}`,
{
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
"Content-Type": "application/json",
},
body: JSON.stringify({ description: "Recompete of the 2021 award." }),
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.patch(
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"],
},
json={'description': 'Recompete of the 2021 award.'},
)
response.raise_for_status()
print(response.json())Objects
Every resource comes back as a JSON object with an id and an object field that names its type:
{
// The record's id. An opaque string.
"id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
// What kind of record this is: "opportunity", "contract", "person", ...
"object": "opportunity",
// The team that owns the record.
"team_id": "8e2d4b6a-1f3c-4a5e-b7d9-0c2e4f6a8b1d",
// When GovDash created and last changed the record.
"created_at": "2026-10-01T14:02:11.000Z",
"updated_at": "2026-10-28T09:15:40.000Z",
// ...the resource's own fields
}The API reference shows every field of every object, with a comment on each one.
Ids are opaque
Treat every id as an opaque string. Don't parse it, don't build one yourself, and don't assume a format, length, or prefix. Resources may use different id formats, including UUIDs and prefixed strings. Compare ids as exact strings, and store them in a text column.
The ids in these docs are examples. They won't exist on your team.
Timestamps
Timestamps are ISO 8601 strings in UTC, such as 2026-10-28T09:15:40.000Z. Fields you send, such as an opportunity's due_date, accept any ISO 8601 timestamp with a time zone, such as 2026-12-15T17:00:00Z or 2026-12-15T12:00:00-05:00.
Empty values
A field with no value is null. It isn't left out. For example, an opportunity without a due date has "due_date": null.
The exception is expandable fields, which are left out unless you ask for them. See Expanding responses.
Deletes
How a delete finishes depends on how much it has to clean up.
| Response | Endpoints | What it means |
|---|---|---|
202 Accepted | Opportunities, contracts, documents | GovDash queued the delete and finishes it in the background. The record can still appear until it does. |
204 No Content | Agencies, companies, people, agents | The record is gone when the response arrives. |
These responses have no body, except a document delete, which returns the document's id and "status": "deleting". Deleting a record that's already gone returns 404 not_found, which you can treat as success.
Team scope
A key reads and writes the records of the team it was created on. Records on other teams, and records above the key's classification ceiling, behave as if they don't exist. See Classification.