> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Job Families

> Browse the job family taxonomy that groups related jobs

## Overview

Job Families are read-only taxonomy records that group related jobs together. They are managed through the Qualifi dashboard and cannot be created or modified via the API. Use this endpoint to retrieve job family data and the job IDs associated with each family.

**Base URL:** `https://api.prod.qualifi.hr`

**Authentication:** All requests require an `x-api-key` header.

```
x-api-key: YOUR_API_KEY
```

<Callout type="info">
  Job Families are read-only via the API. Create or edit job families through the Qualifi dashboard.
</Callout>

## List Job Families

List all job families for the authenticated team.

**Endpoint:** `GET /qsi/gather/job-families`

<Callout type="info">
  The list endpoint returns all job family records for your team. Member `jobIds` are **not** included in the list response — fetch individual job families to retrieve their associated job IDs.
</Callout>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.prod.qualifi.hr/qsi/gather/job-families \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/job-families', {
      headers: {
        'x-api-key': apiKey
      }
    });
    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/job-families',
        headers={
            'x-api-key': api_key
        }
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "jobFamilies": [
        {
          "id": "family-uuid",
          "displayName": "Engineering",
          "description": "All engineering roles",
          "teamId": "team-uuid",
          "organizationId": "org-uuid",
          "createdById": "user-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        },
        {
          "id": "family-uuid-2",
          "displayName": "Sales",
          "description": "Customer-facing sales roles",
          "teamId": "team-uuid",
          "organizationId": "org-uuid",
          "createdById": "user-uuid",
          "createdAt": "2024-01-01T00:00:00Z",
          "updatedAt": "2024-01-01T00:00:00Z"
        }
      ]
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## Get Job Family

Retrieve a single job family by ID, including its associated job IDs.

**Endpoint:** `GET /qsi/gather/job-families/{id}`

<ParamField path="id" type="string" required>
  UUID of the job family
</ParamField>

<Callout type="info">
  `jobIds` — the list of job UUIDs belonging to this family — is only returned on the single-get response, not the list endpoint.
</Callout>

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid \
      -H "x-api-key: ${API_KEY}"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid', {
      headers: {
        'x-api-key': apiKey
      }
    });
    const data = await response.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.get(
        'https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid',
        headers={
            'x-api-key': api_key
        }
    )
    data = response.json()
    ```
  </Tab>
</Tabs>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "jobFamily": {
        "id": "family-uuid",
        "displayName": "Engineering",
        "description": "All engineering roles",
        "teamId": "team-uuid",
        "organizationId": "org-uuid",
        "createdById": "user-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z",
        "jobIds": ["job-uuid-1", "job-uuid-2", "job-uuid-3"]
      }
    },
    "meta": {
      "requestId": "uuid",
      "timestamp": "2024-01-01T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## JobFamilyResponse Field Reference

| Field            | Type       | Description                                                                           |
| ---------------- | ---------- | ------------------------------------------------------------------------------------- |
| `id`             | string     | UUID of the job family                                                                |
| `displayName`    | string     | Human-readable name of the job family                                                 |
| `description`    | string?    | Optional description of the job family                                                |
| `teamId`         | string     | UUID of the owning team                                                               |
| `organizationId` | string     | UUID of the owning organization                                                       |
| `createdById`    | string     | UUID of the user who created the job family                                           |
| `createdAt`      | string     | ISO-8601 creation timestamp                                                           |
| `updatedAt`      | string     | ISO-8601 last-updated timestamp                                                       |
| `jobIds`         | string\[]? | UUIDs of jobs in this family — **single-get only**, not returned in the list endpoint |

## Error Reference

| Status | Cause                         | Description                                                                                                             |
| ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing required team context | The request could not be scoped to a team — for an organization-level API key, supply `teamId` or use a team-scoped key |
| `401`  | Missing or invalid API key    | The `x-api-key` header is absent, expired, or does not match any team                                                   |
| `404`  | Not found                     | The job family UUID does not exist or does not belong to the authenticated team                                         |
| `500`  | Internal error                | An unexpected error occurred while processing the request                                                               |

## Related Resources

<CardGroup cols={2}>
  <Card title="Jobs" icon="briefcase" href="/api-reference/jobs">
    Create and manage job postings associated with job families
  </Card>

  <Card title="Interviews" icon="file-text" href="/api-reference/interviews">
    Attach interviews to jobs
  </Card>
</CardGroup>