HRlume API Documentation — REST API Reference

Getting started

Your instance is your API host.

HRlume does not use one shared multi-tenant API origin. Replace the sample host below with the origin of your own hosted or dedicated HRlume instance.

Base URLhttps://app.yourcompany.com

Quick request

curl "https://app.yourcompany.com/api/employees?paginate=1&limit=20" \
  -H "X-API-KEY: your_api_key"

Authentication

Use a dedicated API key.

Create keys in Settings → Security → API keys inside your HRlume instance. The raw token is shown once. Store it in a secret manager and never place it in browser code or a public repository.

Choose a clear purpose for each key — third-party service, analytics/BI, process automation, personal use or a custom Ukrainian/English label — so administrators can identify it later. The name, purpose, lifetime, IP allowlist and scopes can be edited without rotating the secret token. Purpose is descriptive; access is controlled by the selected scopes.

Recommended headerX-API-KEY: your_api_key

Bearer alternativeAuthorization: Bearer your_api_key

Set a specific expiry date for temporary integrations, or choose unlimited for long-running connections. Optional IP allowlists can further restrict a key to requests coming from known integration servers.

Scopes

Grant only the data an integration needs.

Select only the scopes an integration needs. For backward compatibility, a legacy key with no stored scopes gets all read scopes, but it never receives write access automatically.

Scope	Resource
`employees:read`	Employees
`departments:read`	Departments
`teams:read`	Teams and team members
`leaves:read`	Leave requests
`assets:read`	Company assets
`assets:write`	Create and update company assets
`recruiting:read`	Jobs and candidates
`recruiting:write`	Create and update jobs and candidates
`documents:read`	Document metadata
`documents:write`	Create and update document metadata
`surveys:read`	Survey metadata and aggregate counts
`surveys:write`	Create and update draft surveys
`goals:read`	Goals and OKRs
`goals:write`	Create and update goals and OKRs
`knowledge:read`	Knowledge-base articles
`knowledge:write`	Create and update knowledge-base articles

Writing data

Write access is explicit and non-destructive.

Use POST on a collection to create a record and PUT on /{id} to update only the fields you send. Successful mutations return the saved record in { "data": { ... } }; creation returns HTTP 201.

Least privilege

Write scopes can change personal or business-critical data. HRlume highlights sensitive scopes in the key editor. Use a dedicated short-lived key, restrict it by IP and never grant write access to reporting-only integrations.

API keys cannot delete records, upload files, launch surveys, submit survey responses or approve leave. Employee, department, team and leave-request mutations stay unavailable because those flows require additional HR business rules.

Create an asset

curl -X POST "https://app.yourcompany.com/api/integrations/v1/assets" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"code":"LT-1042","name":"MacBook Pro","serialNumber":"C02..."}'

Pagination

Versioned list endpoints share one envelope.

Use limit and offset. The default limit is 50 and the maximum is 200.

Response envelope

{
  "data": [{ "id": "resource-id" }],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 128
  }
}

Usage examples

Copy, adapt and run.

Keep the instance URL and API key in environment variables. The following examples use only standard platform features, so you can start without an SDK.

EnvironmentHRLUME_URL=https://app.yourcompany.com · HRLUME_API_KEY=your_api_key

JavaScript

Read every employee page

Continue until the current offset reaches the total returned by the API.

Node.js 18+

const baseUrl = process.env.HRLUME_URL;
const apiKey = process.env.HRLUME_API_KEY;
const employees = [];
let offset = 0;

while (true) {
  const url = new URL("/api/employees", baseUrl);
  url.search = new URLSearchParams({ paginate: "1", limit: "100", offset });

  const response = await fetch(url, {
    headers: { "X-API-KEY": apiKey }
  });
  if (!response.ok) throw new Error(`HRlume API ${response.status}`);

  const page = await response.json();
  employees.push(...page.data);
  offset += page.data.length;
  if (offset >= page.pagination.total || page.data.length === 0) break;
}

console.log(`Loaded ${employees.length} employees`);

Python

Export approved leave requests

Use filters and pagination together, then write the selected fields to CSV.

Python 3 · standard library

import csv, json, os, urllib.parse, urllib.request

base = os.environ["HRLUME_URL"].rstrip("/")
key = os.environ["HRLUME_API_KEY"]
rows, offset = [], 0

while True:
    query = urllib.parse.urlencode({
        "status": "approved", "from": "2026-01-01",
        "limit": 200, "offset": offset,
    })
    request = urllib.request.Request(
        f"{base}/api/integrations/v1/leave-requests?{query}",
        headers={"X-API-KEY": key},
    )
    with urllib.request.urlopen(request) as response:
        page = json.load(response)
    rows.extend(page["data"])
    offset += len(page["data"])
    if offset >= page["pagination"]["total"] or not page["data"]:
        break

with open("approved-leave.csv", "w", newline="") as output:
    fields = ["employeeEmail", "startDate", "endDate", "totalDays"]
    writer = csv.DictWriter(output, fieldnames=fields, extrasaction="ignore")
    writer.writeheader()
    writer.writerows(rows)

Error handling

Read the structured error before retrying

Do not retry authorization, scope or validation errors automatically. Log the status and API error code without logging the secret key.

JavaScript

const response = await fetch(`${process.env.HRLUME_URL}/api/integrations/v1/assets`, {
  headers: { "X-API-KEY": process.env.HRLUME_API_KEY }
});
const payload = await response.json();

if (!response.ok) {
  console.error("HRlume request failed", {
    status: response.status,
    error: payload.error
  });
  process.exitCode = 1;
} else {
  console.log(payload.data);
}

Core HR

People and organisational data

GET/api/employees

List employees

Returns company employees. Add paginate=1 to enable limit/offset pagination.

Query parameters

search: First name, last name or email
dept: Department ID
status: Employee status
paginate: Set to 1
limit / offset: Page controls; legacy max limit is 200

Scope employees:read

GET/api/departments

List departments

Returns all departments with manager, parent and live active headcount information.

Scope departments:read

GET/api/teams

List teams

Returns each team with its manager and embedded member summaries. Use employeeId to return only teams containing one employee.

GET/api/teams/{team_id}

Returns one team in the same shape.

Scope teams:read

GET/api/integrations/v1/leave-requests

List leave requests

Returns leave periods with employee, leave-type and approver summaries. Private notes and rejection details are excluded.

Filters

status: pending, approved, rejected or cancelled
employeeId: Employee ID
leaveTypeId: Leave type ID
from / to: Overlapping YYYY-MM-DD range

Example

curl "https://app.yourcompany.com/api/integrations/v1/leave-requests?status=approved&from=2026-01-01" \
  -H "X-API-KEY: your_api_key"

Scope leaves:read

GET/api/integrations/v1/assets

List company assets

Returns equipment, assignment, category, value, location and warranty metadata.

Filters

search: Code, name or serial number
status: Asset status
assignedTo: Employee ID
categoryId: Asset category ID

POST/api/integrations/v1/assets

Create an unassigned asset. Requires code and name.

PUT/api/integrations/v1/assets/{id}

Update asset identity and inventory metadata. Assignment actions are not exposed.

Scope assets:read

Write scope assets:write

GET/api/integrations/v1/documents

List document metadata

Returns names, types, folders, scope and expiry dates. File contents, R2 object keys and storage URLs are not exposed.

Filters

employeeId: Employee ID
type: Document type
folderId: Folder ID
scope: personal or company
expiresBefore: YYYY-MM-DD

POST/api/integrations/v1/documents

Create metadata for an external URL. File upload and R2 object access are not exposed.

PUT/api/integrations/v1/documents/{id}

Update name, type, URL, employee, folder, scope or expiry date.

Create external document metadata

curl -X POST "$HRLUME_URL/api/integrations/v1/documents" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Remote work policy",
    "type": "policy",
    "url": "https://company.example/policies/remote-work.pdf",
    "scope": "company",
    "expiryDate": "2027-12-31"
  }'

Scope documents:read

Write scope documents:write — sensitive

GET/api/integrations/v1/knowledge

List knowledge-base articles

Returns bilingual titles, categories and article bodies with author summaries.

Filters

search: Title or body in either language
category: Ukrainian category value

POST/api/integrations/v1/knowledge

Create a bilingual article. title is required.

PUT/api/integrations/v1/knowledge/{id}

Update title, category or body in Ukrainian/base and English variants.

Create a bilingual article

curl -X POST "$HRLUME_URL/api/integrations/v1/knowledge" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Віддалена робота",
    "titleEn": "Remote work",
    "category": "Політики",
    "categoryEn": "Policies",
    "body": "Правила та рекомендації для команди.",
    "bodyEn": "Rules and guidance for the team."
  }'

Scope knowledge:read

Write scope knowledge:write

Recruiting and engagement

Talent, surveys and performance

GET/api/integrations/v1/jobs

List jobs

Returns vacancies with bilingual content, department, salary range and candidate counts.

Filters

search: Ukrainian or English title
status: draft, open, closed or archived
departmentId: Department ID
type: Employment type value

POST/api/integrations/v1/jobs

Create a vacancy. title is required.

PUT/api/integrations/v1/jobs/{id}

Update vacancy content, status, department, salary and public metadata.

Create a bilingual vacancy

curl -X POST "$HRLUME_URL/api/integrations/v1/jobs" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backend-розробник",
    "titleEn": "Backend Engineer",
    "location": "Remote · Ukraine",
    "type": "full-time",
    "status": "open",
    "salaryMin": 3500,
    "salaryMax": 5000,
    "currency": "USD",
    "hot": true
  }'

Scope recruiting:read

Write scope recruiting:write — sensitive

GET/api/integrations/v1/candidates

List candidates

Returns candidate contact details and current pipeline state. CV files, internal notes and scorecard details are excluded.

Filters

jobId: Job ID
stage: Pipeline stage
source: Candidate source
assignedTo: Responsible employee ID

POST/api/integrations/v1/candidates

Create a candidate for an existing jobId.

PUT/api/integrations/v1/candidates/{id}

Update contact, source, assignee, rating or pipeline stage.

Add a candidate to a vacancy

curl -X POST "$HRLUME_URL/api/integrations/v1/candidates" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job_uuid",
    "firstName": "Olena",
    "lastName": "Koval",
    "email": "olena@example.com",
    "source": "Referral",
    "stage": "applied"
  }'

Scope recruiting:read

Write scope recruiting:write — sensitive

GET/api/integrations/v1/surveys

List surveys

Returns survey metadata plus question and response counts. Individual answers and respondent identities are never exposed.

Filters

status: draft, running or closed

POST/api/integrations/v1/surveys

Create a draft survey. title is required.

PUT/api/integrations/v1/surveys/{id}

Update bilingual content and anonymity only while the survey is a draft.

Create an anonymous survey draft

curl -X POST "$HRLUME_URL/api/integrations/v1/surveys" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Настрій команди",
    "titleEn": "Team mood",
    "introText": "Поділіться, як минув ваш тиждень.",
    "introTextEn": "Tell us how your week went.",
    "anonymous": true
  }'

Scope surveys:read

Write scope surveys:write — sensitive

GET/api/integrations/v1/goals

List goals and OKRs

Returns company, team and employee goals with metric values, weights, periods and progress inputs.

Filters

ownerType: company, team or employee
ownerId: Team or employee ID
period: Configured goal period
status: Goal status

POST/api/integrations/v1/goals

Create a company, team or employee goal. title and ownerType are required.

PUT/api/integrations/v1/goals/{id}

Update content, metric values, status, due date or period. Ownership cannot be moved by update.

Update goal progress

curl -X PUT "$HRLUME_URL/api/integrations/v1/goals/goal_uuid" \
  -H "X-API-KEY: $HRLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currentValue": 72,
    "status": "active",
    "dueDate": "2026-09-30"
  }'

Scope goals:read

Write scope goals:write

Errors

Standard HTTP status codes

Status	Error	Meaning
`401`	`unauthorized`	Missing, invalid, expired, revoked or IP-restricted key.
`403`	`forbidden`	The key does not include the required scope.
`403`	`product_not_licensed`	The HRlume product module is not active for this instance.
`404`	`not_found`	Unknown endpoint or resource.
`405`	`method_not_allowed`	The method is unsupported. Integration endpoints accept GET, POST and PUT only where documented.
`409`	`conflict`	The requested mutation conflicts with current data or state, such as editing a running survey.

Need another endpoint?

Tell us what you want to integrate.

We expand the API around real workflows while keeping employee data access explicit and auditable.

Request an endpoint

Build secure HR integrations with the HRlume REST API.

Everything you need to connect HRlume safely.

Purpose-built endpoints

Scoped API keys

Interactive reference

Configure access before writing any code.

Your instance is your API host.

Use a dedicated API key.

Grant only the data an integration needs.

Write access is explicit and non-destructive.

Copy, adapt and run.

Read every employee page

Export approved leave requests

Read the structured error before retrying

People and organisational data

List employees

List departments

List teams

List leave requests

List company assets

List document metadata

List knowledge-base articles

Talent, surveys and performance

List jobs

List candidates

List surveys

List goals and OKRs

Standard HTTP status codes

Tell us what you want to integrate.