Best practices
These practices keep an integration correct when requests fail, data changes during a sync, or the API grows. They also keep you well under the rate limits.
Sync incrementally
We're rebuilding webhooks and hope to share the updated API by the end of 2026. Until then, use polling to keep integrations up to date. We'll publish the new event contract here when it is ready.
Use timestamp filters to read changes rather than copying every record on each run:
- On your first run, page through the list. On later runs, set
updated_sinceto your saved checkpoint. - Upsert records in the destination by their GovDash
id. - Capture the first response's
Dateheader as the run's start time. Use the server's clock rather than your own. - After every page has been processed successfully, save that time minus a five-minute overlap as the next checkpoint.
The overlap picks up records that change while you page through results. Seeing a record twice is expected; upserting by id prevents duplicates. Keep the same filters and sort order for every page in a run, and start each new run without a cursor.
See Export opportunities from GovDash for a complete outbound example. Import people into GovDash shows data moving in the other direction.
Deleted records don't appear in updated_since results. Until deletion events are available, periodically reconcile your destination against a complete list if it needs to reflect deletions.
Retry safely
Choose whether to retry from the response and the operation you sent:
| Response | Did the request run? | Retry? |
|---|---|---|
429 rate_limited | No. | Yes, after retry-after. |
503 service_unavailable | No. | Yes, after retry-after. |
500 internal_error | Maybe. | GET: yes, with backoff. For writes, check the result first. |
| Network error or timeout | Maybe. | Same as 500. |
Any other 4xx | No. | No. Fix the request. |
GET has no side effects. A repeated PATCH sets the same field values, but a write may also trigger background work. Check the record before repeating a write after a timeout. A 202 delete is already queued; wait for it to finish instead of resubmitting it.
Agent run idempotency
Idempotency-Key is currently supported only when starting an agent run. Other write endpoints do not use it.
Starting an agent run consumes credits, so send an Idempotency-Key header with a unique value, such as a UUID, and reuse it when you retry. Keys are scoped to your team and kept for 1 hour:
- A retry with the same key and the same body returns the original run with
202and anidempotent-replayed: trueheader. No second run starts. - The same key with a different body returns
422 validation_failed. - The same key while the first request is still running returns
409 conflict. Retry after a moment. - A request that GovDash refuses with an error such as
402or403doesn't keep its key, so you can retry it with the same key. - If the connection drops or the response is a
500, the run may have started, so the key stays reserved and a retry returns409 conflictuntil the key expires. Check the agent's recent runs withGET /v1/agent-runs?agent_id=...before you start another. - If GovDash can't check the key, the request returns
503 service_unavailableand nothing starts. Retry afterretry-after.
Set IDEMPOTENCY_KEY once for this logical run (for example, with export IDEMPOTENCY_KEY="$(uuidgen)") and keep it for retries.
curl "$GOVDASH_API_URL/v1/agents/$AGENT_ID/runs" \
-X POST \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-H "Content-Type: application/json" \
-d '{}'const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const idempotencyKey = process.env.IDEMPOTENCY_KEY
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY once per run")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/agents/${process.env.AGENT_ID}/runs`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
"Idempotency-Key": idempotencyKey,
"Content-Type": "application/json",
},
body: JSON.stringify({}),
},
)
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/agents/{os.environ['AGENT_ID']}/runs",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
"Idempotency-Key": os.environ["IDEMPOTENCY_KEY"],
},
json={},
)
response.raise_for_status()
print(response.json())Other writes
Other POST endpoints can create duplicates when repeated. After a timeout, look for the record you intended to create before sending another request. A 409 conflict may mean the first attempt succeeded, or that a different record already has the same unique name or title. Inspect that record before deciding to reuse or update it.
Use exponential backoff with jitter and a cap on attempts. See Rate limits for a sample.
Handle 409 and 422
409 conflictcan mean a duplicate title or name, an existing reference that blocks deletion, or an agent run request still in progress. Read the message. For a data conflict, modify or remove the conflicting record or reference as appropriate before retrying.422 validation_failedmeans GovDash won't make the change, such as moving an opportunity into a phase whose required fields it doesn't have yet. Logerror.messageand fix the input.- Look up allowed values before you write. Read phase ids from
GET /v1/meta/phasesand custom fields fromGET /v1/meta/custom-fields.
Cache metadata
Phases and custom field definitions change rarely. Read /v1/meta/* once at the start of a sync run, or cache it for a few minutes, rather than before every write. If a write returns 422 for a phase id, refresh the cache and try once more.
Build for additive change
We add to /v1 without a new version (see Stability), so:
- Ignore response fields you don't recognize.
- Handle enum values you don't recognize, such as a new custom field type, with a sensible default instead of failing.
- Don't send fields an endpoint doesn't list. Request bodies are strict, so an extra field returns
400 bad_request. - Treat ids as opaque strings. See Requests and responses.
- Alert on deprecation headers and migrate before the announced timestamp. We intentionally limit the API's surface so we can preserve compatibility and deprecate as little as possible.
Remember that some deletes finish later
Deleting an opportunity, contract, or document returns 202 Accepted and finishes in the background, so the record can still appear for a short time. See Requests and responses.