GovDash
Menu

Expanding responses

Some fields are expensive to load or only matter to some integrations, so responses leave them out by default. Ask for them with the expand[] query parameter, and they're added to the object.

How it works

Pass the name of each field you want in expand[]. To expand more than one, repeat the parameter or separate the names with commas. These are the same:

?expand[]=custom_fields&expand[]=members
?expand[]=custom_fields,members

Expanding a nested field uses a dot, such as expand[]=past_performance.writeups.

Each field you expand counts as one more request against your rate limits.

An endpoint that supports expansion lists its values in the description of its expand[] parameter in the API reference. We add expansions where they help, so check there. A name the endpoint doesn't know returns 400 bad_request with the allowed names in the message:

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request query parameters: unknown expand key \"owner\". Allowed keys: custom_fields, members."
  }
}

Example

Retrieving an opportunity returns its own fields. With expand[]=custom_fields,members, it also includes the values of your team's custom fields and the people on its capture team.

With curl, pass -g so it doesn't treat the brackets as a pattern:

curlcurl
curl -g "$GOVDASH_API_URL/v1/opportunities/$OPPORTUNITY_ID?expand[]=custom_fields,members" \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION"
TypeScriptTypeScript
const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")

const query = new URLSearchParams()
query.append("expand[]", "custom_fields")
query.append("expand[]", "members")

const response = await fetch(
  `${process.env.GOVDASH_API_URL}/v1/opportunities/${process.env.OPPORTUNITY_ID}?${query}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
    },
  },
)
const opportunity = await response.json()
PythonPython
import os

import requests

response = requests.get(
    f"{os.environ['GOVDASH_API_URL']}/v1/opportunities/{os.environ['OPPORTUNITY_ID']}",
    params={"expand[]": ["custom_fields", "members"]},
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
)
opportunity = response.json()
{
  "id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
  "object": "opportunity",
  "title": "Cloud migration support",
  // ...the opportunity's other fields

  // Added by expand[]=custom_fields. One entry per custom field with a value.
  "custom_fields": [
    {
      // Matches `id` in GET /v1/meta/custom-fields.
      "field_id": "2b4d6f8a-0c1e-4a3b-9d5f-7e9a1c3b5d7f",
      "name": "Contract vehicle",
      // The field's type decides the shape of `value`.
      "type": "SELECT",
      "value": "GSA MAS",
    },
  ],
  // Added by expand[]=members. The capture team.
  "members": [
    {
      "id": "9f1b3d5c-7e2a-4c6b-8d0f-1a3c5e7b9d2f",
      // The role on the capture team.
      "role": {
        "id": "4e6a8c0b-2d1f-4b3a-9c5e-7f9b1d3a5c6e",
        "name": "Capture manager",
      },
      // The team member in the role, or null.
      "user": {
        "id": "6c8e0a2b-4d3f-4f5a-a1c7-9b0d2e4f6a8c",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "[email protected]",
      },
      // The key person in the role, or null.
      "key_person_id": null,
    },
  ],
}

Without expand[], custom_fields and members aren't in the response at all. Check whether the field is present rather than treating a missing field as an empty list.

To read custom field values for many opportunities, list them, then retrieve each one with expand[]=custom_fields. See Read custom fields.