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,membersExpanding 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:
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"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()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.