Many API endpoints support optionally "expanding" related resources in the response through the expand parameter. This allows you to fetch related data in a single request rather than making multiple API calls.

Using Expansions

Expansions are specified using the expand query parameter, which accepts an array of expansion types. Multiple expansions can be requested in a single call.

Example

For example, to expand the openings resource for a job, you can use the following request:

curl --request POST \
     --url https://api.ashbyhq.com/job.info \
     --header 'Content-Type: application/json' \
     --data '
{
  "id": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  "includeUnpublishedJobPostingsIds": true,
  "expand": [
    "openings"
  ]
}
'

Which returns something like this:

{
  "success": true,
  "results": {
    "id": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
    ...
    "openings": [
      {
        "id": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
        "openedAt": "2022-08-12T20:29:56.964Z",
        "closedAt": "2022-08-12T20:29:56.964Z",
        "isArchived": false,
        "archivedAt": "2022-08-12T20:29:56.964Z",
        "closeReasonId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
        "openingState": "Approved",
        "latestVersion": {
          "id": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
          "identifier": "string",
          "description": "string",
          "authorId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
          "createdAt": "2022-08-12T20:29:56.964Z",
          "teamId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
          "jobIds": [
            "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
          ],
          "targetHireDate": "string",
          "targetStartDate": "string",
          "isBackfill": true,
          "employmentType": "FullTime",
          "locationIds": [
            "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
          ],
          "hiringTeam": [
            {
              "email": "test@ashbyhq.com",
              "firstName": "Joey",
              "lastName": "Joe",
              "role": "Hiring Manager",
              "userId": "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
            }
          ],
          "customFields": [
            {
              "id": "650e5f74-32db-4a0a-b61b-b9afece05023",
              "title": "Expected start date",
              "value": "2022-11-10T19:47:56.795Z"
            }
          ]
        }
      }
    ]
  }
}

Possible Expansions

applicationFormSubmissions
compensation
interview
job
location
openings
referrals

Not all expansions are available for all endpoints. The documentation for each endpoint will list which expansions are supported.