Job Families

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

Job Families are read-only via the API. Create or edit job families through the Qualifi dashboard.

List Job Families

List all job families for the authenticated team. Endpoint: GET /qsi/gather/job-families

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.

cURL
JavaScript
Python

curl -X GET https://api.prod.qualifi.hr/qsi/gather/job-families \
  -H "x-api-key: ${API_KEY}"

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/job-families', {
  headers: {
    'x-api-key': apiKey
  }
});
const data = await response.json();

response = requests.get(
    'https://api.prod.qualifi.hr/qsi/gather/job-families',
    headers={
        'x-api-key': api_key
    }
)
data = response.json()

{
  "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"
  }
}

Get Job Family

Retrieve a single job family by ID, including its associated job IDs. Endpoint: GET /qsi/gather/job-families/{id}

string

required

UUID of the job family

jobIds — the list of job UUIDs belonging to this family — is only returned on the single-get response, not the list endpoint.

cURL
JavaScript
Python

curl -X GET https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid \
  -H "x-api-key: ${API_KEY}"

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();

response = requests.get(
    'https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid',
    headers={
        'x-api-key': api_key
    }
)
data = response.json()

{
  "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"
  }
}

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

Jobs

Create and manage job postings associated with job families

Interviews

Attach interviews to jobs

Get Started

API Reference

Guides

Code Examples

Resources

Overview

List Job Families

Get Job Family

JobFamilyResponse Field Reference

Error Reference

Jobs

Interviews

​Overview

​List Job Families

​Get Job Family

​JobFamilyResponse Field Reference

​Error Reference

​Related Resources

Jobs

Interviews

Overview

List Job Families

Get Job Family

JobFamilyResponse Field Reference

Error Reference

Related Resources