GovDash
Menu

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:

  1. On your first run, page through the list. On later runs, set updated_since to your saved checkpoint.
  2. Upsert records in the destination by their GovDash id.
  3. Capture the first response's Date header as the run's start time. Use the server's clock rather than your own.
  4. 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:

ResponseDid the request run?Retry?
429 rate_limitedNo.Yes, after retry-after.
503 service_unavailableNo.Yes, after retry-after.
500 internal_errorMaybe.GET: yes, with backoff. For writes, check the result first.
Network error or timeoutMaybe.Same as 500.
Any other 4xxNo.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 202 and an idempotent-replayed: true header. 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 402 or 403 doesn'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 returns 409 conflict until the key expires. Check the agent's recent runs with GET /v1/agent-runs?agent_id=... before you start another.
  • If GovDash can't check the key, the request returns 503 service_unavailable and nothing starts. Retry after retry-after.

Set IDEMPOTENCY_KEY once for this logical run (for example, with export IDEMPOTENCY_KEY="$(uuidgen)") and keep it for retries.

curlcurl
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 '{}'
TypeScriptTypeScript
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())
PythonPython
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 conflict can 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_failed means GovDash won't make the change, such as moving an opportunity into a phase whose required fields it doesn't have yet. Log error.message and fix the input.
  • Look up allowed values before you write. Read phase ids from GET /v1/meta/phases and custom fields from GET /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.