Skip to main content

​
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 -X GET https://api.prod.qualifi.hr/qsi/gather/job-families \
  -H "x-api-key: ${API_KEY}"

{
  "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}
​
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 -X GET https://api.prod.qualifi.hr/qsi/gather/job-families/family-uuid \
  -H "x-api-key: ${API_KEY}"

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

FieldTypeDescription
idstringUUID of the job family
displayNamestringHuman-readable name of the job family
descriptionstring?Optional description of the job family
teamIdstringUUID of the owning team
organizationIdstringUUID of the owning organization
createdByIdstringUUID of the user who created the job family
createdAtstringISO-8601 creation timestamp
updatedAtstringISO-8601 last-updated timestamp
jobIdsstring[]?UUIDs of jobs in this family — single-get only, not returned in the list endpoint

​
Error Reference

StatusCauseDescription
400Missing required team contextThe request could not be scoped to a team — for an organization-level API key, supply teamId or use a team-scoped key
401Missing or invalid API keyThe x-api-key header is absent, expired, or does not match any team
404Not foundThe job family UUID does not exist or does not belong to the authenticated team
500Internal errorAn unexpected error occurred while processing the request

Jobs

Create and manage job postings associated with job families

Interviews

Attach interviews to jobs