Документація HRlume API — довідник REST API

Початок роботи

Ваш екземпляр є вашим хостом API.

HRlume не використовує одне спільне джерело мультитенантного API. Замініть наведений нижче зразок хосту джерелом вашого власного розміщеного або виділеного екземпляра HRlume.

Базовий URLhttps://app.yourcompany.com

Швидкий запит

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

Автентифікація

Використовуйте спеціальний ключ API.

Створіть ключі Налаштування → Безпека → Ключі API у вашому екземплярі HRlume. Необроблений токен відображається один раз. Зберігайте його в секретному менеджері та ніколи не розміщуйте в коді браузера чи загальнодоступному сховищі.

Виберіть чітке призначення для кожного ключа — сторонній сервіс, аналітика/BI, автоматизація процесів, особисте використання або спеціальна українська/англійська мітка — щоб адміністратори могли ідентифікувати його пізніше. Ім’я, призначення, термін дії, білий список IP-адрес і області можна редагувати без обертання секретного маркера. Мета є описовою; доступ контролюється вибраними областями.

Рекомендований заголовокX-API-KEY: your_api_key

Альтернатива носіяAuthorization: Bearer your_api_key

Встановіть конкретну дату закінчення терміну дії для тимчасових інтеграцій або виберіть необмежений для тривалих підключень. Додаткові дозволені списки IP-адрес можуть ще більше обмежити ключ запитами, що надходять із відомих серверів інтеграції.

Права доступу

Надайте лише дані, необхідні для інтеграції.

Виберіть лише ті області, які потрібні інтеграції. Для зворотної сумісності застарілий ключ без збережених областей отримує всі області читання, але ніколи не отримує автоматично доступ до запису.

Доступ	Ресурс
`employees:read`	Співробітники
`departments:read`	Відділи
`teams:read`	Команди та члени команд
`leaves:read`	Запити на відпустку
`assets:read`	Активи компанії
`assets:write`	Створення та оновлення активів компанії
`recruiting:read`	Вакансії та кандидати
`recruiting:write`	Створюйте та оновлюйте вакансії та кандидатів
`documents:read`	Метадані документа
`documents:write`	Створення та оновлення метаданих документів
`surveys:read`	Метадані опитування та зведені підрахунки
`surveys:write`	Створюйте та оновлюйте проекти опитувань
`goals:read`	Цілі та OKR
`goals:write`	Створення й оновлення цілей і OKR
`knowledge:read`	Статті бази знань
`knowledge:write`	Створюйте та оновлюйте статті бази знань

Зміна даних

Доступ на запис надається явно й не відкриває небезпечних операцій.

використання POST для колекції, щоб створити запис, і PUT для /{id} щоб оновити лише передані поля. Успішна зміна повертає збережений запис у { "data": { ... } }; створення повертає HTTP 201.

Найменший привілей

Права на запис дають змогу змінювати персональні або критично важливі для бізнесу дані. HRlume позначає чутливі права в редакторі ключів. Використовуйте окремий короткостроковий ключ, обмежуйте його за IP-адресою та не надавайте доступ на запис інтеграціям, призначеним лише для звітності.

Ключі API не можуть видаляти записи, завантажувати файли, запускати опитування, надсилати відповіді на опитування чи схвалювати відпустку. Мутації співробітників, відділів, команд і запитів на відпустку залишаються недоступними, оскільки ці потоки потребують додаткових бізнес-правил HR.

Створіть актив

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..."}'

Пагінація

Версійовані спискові маршрути мають єдину структуру відповіді.

використання limit та offset. Стандартний ліміт — 50, максимальний — 200.

Конверт для відповідей

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

Приклади використання

Скопіюйте, адаптуйте та запускайте.

Зберігайте URL вашого екземпляра та API-ключ у змінних середовища. Приклади нижче використовують лише стандартні можливості платформ, тому почати можна без SDK.

СередовищеHRLUME_URL=https://app.yourcompany.com · HRLUME_API_KEY=your_api_key

JavaScript

Отримайте всі сторінки працівників

Продовжуйте запити, доки поточний offset не досягне загальної кількості, яку повернув 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

Експортуйте погоджені відпустки

Поєднайте фільтри з пагінацією, а потім запишіть вибрані поля у CSV.

Python 3 · стандартна бібліотека

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)

Обробка помилок

Перевіряйте структуровану помилку перед повторним запитом

Не повторюйте автоматично запити з помилками авторизації, прав доступу чи валідації. Записуйте статус і код помилки API, але ніколи не записуйте секретний ключ.

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

Дані працівників та організаційної структури

GET/api/employees

Список працівників

Повертає працівників компанії. Додайте paginate=1 щоб увімкнути пагінацію limit/offset.

Параметри запиту

search: Ім'я, прізвище або електронна пошта
dept: ID відділу
status: Статус працівника
paginate: Установити на 1
обмеження / зміщення: елементи керування сторінкою; максимальний ліміт старої версії становить 200

Доступ employees:read

GET/api/departments

Список відділів

Повертає всі відділи з інформацією про керівника, батьків і активну інформацію про кількість персоналу.

Доступ departments:read

GET/api/teams

Список команд

Повертає кожну команду, її керівника та короткі дані учасників. Використайте employeeId щоб повернути лише команди з указаним працівником.

GET/api/teams/{team_id}

Повертає одну команду в тій же формі.

Доступ teams:read

GET/api/integrations/v1/leave-requests

Список запитів на відпустку

Періоди повернення відпусток із підсумковими відомостями про співробітників, типи відпусток і затверджувачів. Приватні примітки та деталі відмови виключені.

Фільтри

status: pending, approved, rejected or cancelled
employeeId: ID працівника
leaveTypeId: ID типу відпустки
від/до: Перекриття діапазону РРРР-ММ-ДД

приклад

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

Доступ leaves:read

GET/api/integrations/v1/assets

Перелік активів компанії

Повертає метадані обладнання, призначення, категорії, вартості, розташування та гарантії.

Фільтри

search: Код, назва або серійний номер
status: Статус активу
assignedTo: ID працівника
categoryId: Ідентифікатор категорії активу

POST/api/integrations/v1/assets

Створює непризначений актив. Потрібні code та name.

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

Оновіть ідентифікатор активу та метадані інвентаризації. Дії присвоєння не виставляються.

Доступ assets:read

Право на запис assets:write

GET/api/integrations/v1/documents

Список метаданих документа

Повертає назви, типи, папки, область дії та термін дії. Вміст файлу, ключі об’єктів R2 і URL-адреси зберігання не розкриваються.

Фільтри

employeeId: ID працівника
type: Тип документа
folderId: ID папки
scope: personal or company
expiresBefore: РРРР-ММ-ДД

POST/api/integrations/v1/documents

Створює метадані для зовнішньої URL-адреси. Завантаження файлів і прямий доступ до об’єктів R2 через API недоступні.

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

Оновіть ім’я, тип, URL-адресу, співробітника, папку, обсяг або термін дії.

Створіть метадані зовнішнього документа

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

Доступ documents:read

Право на запис documents:write — чутливий доступ

GET/api/integrations/v1/knowledge

Список статей бази знань

Повертає двомовні заголовки, категорії та тексти статей із коротким описом автора.

Фільтри

search: Заголовок або текст будь-якою мовою
category: Українське значення категорії

POST/api/integrations/v1/knowledge

Створює двомовну статтю. title є обов’язковим.

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

Оновити заголовок, категорію чи тіло в українському/базовому та англійському варіантах.

Створіть двомовну статтю

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."
  }'

Доступ knowledge:read

Право на запис knowledge:write

Рекрутинг і залучення

Талант, опитування та продуктивність

GET/api/integrations/v1/jobs

Список робочих місць

Повертає вакансії з двомовним вмістом, відділом, діапазоном зарплат і кількістю кандидатів.

Фільтри

search: Українська або англійська назва
status: draft, open, closed or archived
departmentId: ID відділу
type: Значення типу зайнятості

POST/api/integrations/v1/jobs

Створює вакансію. title є обов’язковим.

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

Оновіть вміст вакансії, статус, відділ, зарплату та публічні метадані.

Створіть двомовну вакансію

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
  }'

Доступ recruiting:read

Право на запис recruiting:write — чутливий доступ

GET/api/integrations/v1/candidates

Список кандидатів

Повертає контактні дані кандидата та поточний етап воронки. Файли резюме, внутрішні нотатки й детальні оцінки не включаються.

Фільтри

jobId: ID вакансії
stage: Етап воронки
source: Джерело кандидата
assignedTo: ID відповідального працівника

POST/api/integrations/v1/candidates

Створює кандидата для вакансії з jobId.

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

Оновлює контакти, джерело, відповідального, рейтинг або етап воронки.

Додайте кандидата до вакансії

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

Доступ recruiting:read

Право на запис recruiting:write — чутливий доступ

GET/api/integrations/v1/surveys

Список опитувань

Повертає метадані опитування, а також кількість питань і відповідей. Індивідуальні відповіді та особи респондентів ніколи не розкриваються.

Фільтри

status: draft, running or closed

POST/api/integrations/v1/surveys

Створює чернетку опитування. title є обов’язковим.

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

Оновлюйте двомовний вміст і анонімність, лише поки опитування є чернеткою.

Створіть чернетку анонімного опитування

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
  }'

Доступ surveys:read

Право на запис surveys:write — чутливий доступ

GET/api/integrations/v1/goals

Перелічіть цілі та OKR

Повертає цілі компанії, команди та співробітників із значеннями показників, вагами, періодами та вхідними даними прогресу.

Фільтри

ownerType: company, team or employee
ownerId: ID команди або співробітника
period: Налаштований цільовий період
status: Статус цілі

POST/api/integrations/v1/goals

Створює ціль компанії, команди або працівника. title та ownerType є обов’язковими.

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

Оновіть вміст, значення показників, статус, дату або період. Право власності не можна передати шляхом оновлення.

Оновіть прогрес цілі

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

Доступ goals:read

Право на запис goals:write

Помилки

Стандартні коди стану HTTP

Статус	Помилка	Значення
`401`	`unauthorized`	Відсутній, недійсний, прострочений, відкликаний або обмежений IP-ключ.
`403`	`forbidden`	Ключ не містить необхідної області.
`403`	`product_not_licensed`	Модуль продукту HRlume неактивний для цього екземпляра.
`404`	`not_found`	Невідома кінцева точка або ресурс.
`405`	`method_not_allowed`	Метод не підтримується. Кінцеві точки інтеграції приймають GET, POST і PUT лише там, де це задокументовано.
`409`	`conflict`	Запитана зміна суперечить поточному стану даних — наприклад, коли намагаються редагувати вже запущене опитування.

Потрібна інша кінцева точка?

Розкажіть нам, що ви хочете інтегрувати.

Ми розширюємо API на реальні робочі процеси, зберігаючи доступ до даних співробітників чітким і доступним для перевірки.

Запит кінцевої точки

Створюйте безпечні HR-інтеграції через HRlume REST API.

Усе необхідне для безпечного підключення HRlume.

Спеціалізовані endpoint’и

Обмежені за доступом API-ключі

Інтерактивна довідка

Налаштуйте доступ перед написанням будь-якого коду.

Знайдіть саме той маршрут, який вам потрібен.

Ваш екземпляр є вашим хостом API.

Використовуйте спеціальний ключ API.

Надайте лише дані, необхідні для інтеграції.

Доступ на запис надається явно й не відкриває небезпечних операцій.

Скопіюйте, адаптуйте та запускайте.

Отримайте всі сторінки працівників

Експортуйте погоджені відпустки

Перевіряйте структуровану помилку перед повторним запитом

Дані працівників та організаційної структури

Список працівників

Список відділів

Список команд

Список запитів на відпустку

Перелік активів компанії

Список метаданих документа

Список статей бази знань

Талант, опитування та продуктивність

Список робочих місць

Список кандидатів

Список опитувань

Перелічіть цілі та OKR

Стандартні коди стану HTTP

Розкажіть нам, що ви хочете інтегрувати.