Jobs - Humanly Developer Docs

Overview

Jobs represent open positions that candidates can be screened for. You can create jobs, attach interviews and screening questionnaires, assign ATS jobs, and manage job status. Job Families (read-only) provide a taxonomy layer that groups related jobs. Base URL: https://api.prod.qualifi.hr Authentication: All requests require an x-api-key header.

x-api-key: YOUR_API_KEY

All responses follow the envelope: { "data": { ... }, "meta": { "requestId": "uuid", "timestamp": "ISO-8601" } }.

Create Job

Create a new job posting. Endpoint: POST /qsi/gather/jobs

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/jobs \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Software Engineer",
    "type": "requisition",
    "department": "Engineering",
    "location": ["San Francisco, CA"],
    "workModel": "hybrid"
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/jobs', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Senior Software Engineer',
    type: 'requisition',
    department: 'Engineering',
    location: ['San Francisco, CA'],
    workModel: 'hybrid'
  })
});
const data = await response.json();

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/jobs',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Senior Software Engineer',
        'type': 'requisition',
        'department': 'Engineering',
        'location': ['San Francisco, CA'],
        'workModel': 'hybrid'
    }
)
data = response.json()

{
  "title": "Senior Software Engineer",
  "type": "requisition",
  "department": "Engineering",
  "location": ["San Francisco, CA"],
  "workModel": "hybrid",
  "status": "draft",
  "tags": ["backend", "python"]
}

{
  "data": {
    "job": {
      "id": "job-uuid",
      "title": "Senior Software Engineer",
      "type": "requisition",
      "department": "Engineering",
      "location": ["San Francisco, CA"],
      "workModel": "hybrid",
      "status": "draft",
      "tags": ["backend", "python"],
      "organizationId": "org-uuid",
      "teamId": "team-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"
  }
}

List Jobs

List jobs with optional filtering and pagination. Endpoint: GET /qsi/gather/jobs

teamId

string

Filter by team UUID

page

number

Page number (default: 1)

pageSize

number

Items per page (default: 50, max: 100)

type

string

Filter by job type

status

string

Filter by job status

department

string

Filter by department

location

string

Filter by location string

string

Full-text search on job title and description

Pagination: Use page and pageSize query params. The response includes a pagination object with page, pageSize, total, and totalPages fields.

{
  "data": {
    "jobs": [
      {
        "id": "job-uuid",
        "title": "Senior Software Engineer",
        "type": "requisition",
        "department": "Engineering",
        "status": "active",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "total": 42,
      "totalPages": 1
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Get Job

Retrieve a single job by ID. Endpoint: GET /qsi/gather/jobs/{id}

string

required

UUID of the job

teamId

string

Team UUID (used for access scoping)

{
  "data": {
    "job": {
      "id": "job-uuid",
      "title": "Senior Software Engineer",
      "type": "requisition",
      "department": "Engineering",
      "location": ["San Francisco, CA"],
      "workModel": "hybrid",
      "description": "<p>We are looking for a senior engineer...</p>",
      "shortDescription": "Build great things",
      "status": "active",
      "tags": ["backend"],
      "interviewId": "interview-uuid",
      "screeningQuestionnaireId": "questionnaire-uuid",
      "assignedRecruiterId": "user-uuid",
      "jobFamilyIds": ["family-uuid"],
      "knowledgeBaseIds": ["kb-uuid"],
      "organizationId": "org-uuid",
      "teamId": "team-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"
  }
}

jobFamilyIds and knowledgeBaseIds are only returned on the single-get response, not the list endpoint.

Update Job

Update job fields (whole-body patch — any subset of optional fields). Endpoint: PATCH /qsi/gather/jobs/{id}

string

required

UUID of the job to update

Mutating an ATS-imported job via PATCH returns 409 Conflict. Use the ATS assign endpoint to manage ATS jobs.

{
  "title": "Staff Software Engineer",
  "status": "active"
}

{
  "data": {
    "job": {
      "id": "job-uuid",
      "title": "Staff Software Engineer",
      "status": "active",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Archive Job

Archive (soft-delete) a job. The job remains retrievable with archivedAt set. Endpoint: DELETE /qsi/gather/jobs/{id}

string

required

UUID of the job to archive

teamId

string

Team UUID (used for access scoping)

userId

string

UUID of the user performing the archive

{
  "data": {
    "job": {
      "id": "job-uuid",
      "archivedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Unarchive Job

Restore a previously archived job. Endpoint: POST /qsi/gather/jobs/{id}/unarchive

string

required

UUID of the job to restore

{
  "data": {
    "job": {
      "id": "job-uuid",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Attach Interview

Attach an interview to a job. Endpoint: PATCH /qsi/gather/jobs/{id}/interview

string

required

UUID of the job

{
  "interviewId": "interview-uuid"
}

{
  "data": {
    "job": {
      "id": "job-uuid",
      "interviewId": "interview-uuid",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Attach Screening Questionnaire

Attach a screening questionnaire to a job. Endpoint: PATCH /qsi/gather/jobs/{id}/screening-questionnaire

string

required

UUID of the job

{
  "screeningQuestionnaireId": "questionnaire-uuid"
}

{
  "data": {
    "job": {
      "id": "job-uuid",
      "screeningQuestionnaireId": "questionnaire-uuid",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Assign ATS Job

Assign an ATS job to the current team. Endpoint: POST /qsi/gather/jobs/assign-ats

{
  "integrationId": "integration-uuid",
  "externalJobId": "ats-job-123"
}

{
  "data": {
    "job": {
      "id": "job-uuid",
      "title": "Senior Software Engineer",
      "externalId": "ats-job-123",
      "importSource": "greenhouse",
      "teamId": "team-uuid",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Unassign Team from Job

Remove the team assignment from a job. Endpoint: DELETE /qsi/gather/jobs/{id}/team-assignment

string

required

UUID of the job

teamId

string

Team UUID to unassign

userId

string

UUID of the user performing the unassignment

{
  "data": {
    "success": true
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

JobResponse Field Reference

The following fields may be returned on a job object. Fields marked optional (?) may be absent when not set.

Field	Type	Description
`id`	string	UUID of the job
`title`	string	Job title
`type`	string	Job type. One of `requisition`, `pipeline`, `template`
`status`	string	Job status. One of `draft`, `pending_approval`, `approved`, `open`, `on_hold`, `closed`, `filled`, `cancelled`, `active`, `paused`, `archived`. Updates are subject to a transition state-machine (an invalid transition returns `400`)
`department`	string?	Department
`location`	string[]?	List of location strings
`workModel`	string?	Work model (`remote`, `hybrid`, `onsite`)
`description`	string?	Full job description (HTML or plain text)
`descriptionJson`	object?	Structured JSON description
`requirements`	string?	Requirements text
`requirementsJson`	object?	Structured JSON requirements
`shortDescription`	string?	Auto-generated brief summary (read-only — not settable via the API)
`tags`	string[]?	List of tags
`applyAction`	string?	Apply button behavior. One of `apply_first`, `interview_first`, `chat_to_apply`
`organizationId`	string	UUID of the owning organization
`teamId`	string	UUID of the owning team
`externalId`	string?	ID in the external ATS
`externalSlug`	string?	Slug in the external ATS
`importSource`	string?	Name of the ATS that imported this job
`interviewId`	string?	UUID of the attached interview
`meetingId`	string?	UUID of the attached meeting
`screeningQuestionnaireId`	string?	UUID of the attached screening questionnaire
`assignedRecruiterId`	string?	UUID of the assigned recruiter
`createdById`	string	UUID of the user who created the job
`createdAt`	string	ISO-8601 creation timestamp
`updatedAt`	string	ISO-8601 last-updated timestamp
`archivedAt`	string?	ISO-8601 archive timestamp; omitted from the response when the job is not archived
`ats`	object?	ATS metadata (read-only, see below)
`jobFamilyIds`	string[]?	Associated job family UUIDs — single-get only
`knowledgeBaseIds`	string[]?	Associated knowledge base UUIDs — single-get only

ATS Metadata (`ats` object)

The ats field is read-only and populated from the external ATS. It contains up to 8 sub-fields:

Field	Type	Description
`requisitionId`	string?	ATS requisition identifier
`hiringManager`	string?	Name or ID of the hiring manager in the ATS
`recruiter`	string?	Name or ID of the recruiter in the ATS
`headcount`	number?	Target headcount
`salaryRange`	object?	`{ min: number, max: number }`
`employmentType`	string?	Employment type as reported by the ATS
`openDate`	string?	ISO-8601 date the requisition was opened
`closeDate`	string?	ISO-8601 date the requisition was closed

Status Limitation

Status transitions are validated by a state-machine. Updating status is only permitted along allowed transitions; an invalid transition returns 400 Bad Request with a message of the form Invalid status transition from '...' to '...'. At creation, only draft, pending_approval, and active are accepted — advanced and terminal states (such as open, on_hold, closed, filled, cancelled, paused, archived) are reachable only via subsequent update transitions.API keys cannot approve jobs. On create, setting status: "approved" always returns 403 Forbidden. On update, transitioning a pending_approval job to approved returns 403 Forbidden. Job approvals must be performed through the Humanly dashboard.

Error Reference

Status	Code / Cause	Description
`400`	Validation error, disallowed field, or invalid status transition	Request body failed validation, a non-settable field (`customFields`, `crm`, `ats`) was included, or a disallowed status transition was attempted (`Invalid status transition from '...' to '...'`)
`401`	Missing or invalid API key	The `x-api-key` header is absent, expired, or does not match any team
`403`	Approval not allowed via API, or acting user not a team member	On create, setting `status: "approved"` always returns 403; on update, transitioning a `pending_approval` job to `approved` returns 403. Also returned when the acting `userId` is not a member of the target team
`404`	Not found / wrong team / unknown user	The job UUID does not exist or does not belong to the authenticated team, or the acting `userId` does not exist
`409`	ATS-imported job mutation	Attempted to PATCH an ATS-imported job directly; use the ATS assign endpoint instead
`500`	Internal error	An unexpected error occurred while processing the request

Job Families

Browse the job family taxonomy associated with your jobs

Interviews

Create and manage interviews to attach to jobs

​Overview

​Create Job

​List Jobs

​Get Job

​Update Job

​Archive Job

​Unarchive Job

​Attach Interview

​Attach Screening Questionnaire

​Assign ATS Job

​Unassign Team from Job

​JobResponse Field Reference

​ATS Metadata (ats object)

​Status Limitation

​Error Reference

​Related Resources

Job Families

Interviews

Overview

Create Job

List Jobs

Get Job

Update Job

Archive Job

Unarchive Job

Attach Interview

Attach Screening Questionnaire

Assign ATS Job

Unassign Team from Job

JobResponse Field Reference

ATS Metadata (`ats` object)

Status Limitation

Error Reference

Related Resources