Автентифікація
Один API-ключ на компанію. Ми зберігаємо лише його хеш і показуємо ключ один раз, тож скопіюйте його відразу. Після перевипуску або відкликання запити зі старим ключем одразу відхиляються.
Ключ діє від імені адміністратора, який його видав. Усе, що ваша інтеграція робить із цим ключем, наприклад змінює статус відгуку чи реєструє webhook, фіксується як дія цього адміністратора і зобов'язує вашу компанію так само, як дія в кабінеті.
https://jobico.io/api/v1curl "https://jobico.io/api/v1/applications?since=2026-10-01T00:00:00Z&limit=50" \
-H "Authorization: Bearer jk_live_..."Ліміти запитів
З одним ключем можна робити до 60 запитів на хвилину. Кожна відповідь на запит із чинним ключем показує, скільки у вас лишилося: RateLimit-Limit - це бюджет, RateLimit-Remaining - скільки з нього ще не витрачено, RateLimit-Reset - за скільки секунд він поновиться. Коли бюджет вичерпано, ви отримаєте 429 із заголовком Retry-After: зачекайте стільки секунд і продовжуйте. Окремо з однієї IP-адреси можна робити до 300 запитів на хвилину з усіх ключів разом; понад це адреса отримає такий самий 429 з RateLimit-Limit: 300. Нехай основну роботу робить webhook: він доставляє кожен новий відгук за лічені секунди. Опитуйте API лише як підстраховку: відгуки не частіше ніж раз на 10 хвилин на компанію, вакансії не частіше ніж раз на годину.
RateLimit-Limit: 60
RateLimit-Remaining: 41
RateLimit-Reset: 23Ендпоінти
| Метод | Шлях | Що робить |
|---|---|---|
| GET | /api/v1/jobs | усі вакансії вашої компанії, разом із чернетками, спочатку найстаріші, кожна в повній формі (ті самі поля, що приймає запис, плюс id, slug, status, archived, url і дати). Фільтр: status (draft, pending_review, active або inactive), наприклад status=active, щоб дзеркалити лише відкриті вакансії. Посторінково через limit і cursor, як і кожен список |
| POST | /api/v1/jobs | створити вакансію з полями нижче: чернетку за замовчуванням або одразу опубліковану зі status active. Відповідь 201 із вакансією |
| GET | /api/v1/jobs/:id | одна вакансія за її id |
| PATCH | /api/v1/jobs/:id | змінити будь-яку частину полів вакансії (кожне повністю замінює збережене значення) і через status закрити (inactive) або знову відкрити (active) її; відповідь - вакансія, як її повертає GET |
| GET | /api/v1/applications | відгуки на ваші вакансії, спочатку найстаріші. Фільтри: job (id вакансії) і since (дата й час у форматі ISO із Z або зсувом, включно; сама дата без часу не приймається). Посторінково через limit і cursor, як і кожен список |
| GET | /api/v1/applications/:id | один відгук за його id |
| GET | /api/v1/applications/:id/cv | Файл резюме з відгуку |
| PATCH | /api/v1/applications/:id | змінити статус відгуку на viewed або rejected чи зафіксувати найм через hired; у відповіді - той самий відгук у вигляді, який повертає GET |
| GET | /api/v1/webhook | ваш поточний webhook: url, чи він активний і остання доставка; 404, якщо webhook ще не налаштовано |
| PUT | /api/v1/webhook | зареєструвати або замінити webhook із вказаним url і ввімкнути доставки; у відповіді - новий секрет для підпису, показується один раз |
| DELETE | /api/v1/webhook | видалити webhook і скасувати всі доставки, що ще чекають у його черзі; відповідає 204, навіть якщо видаляти не було чого |
| POST | /api/v1/webhook/test | надіслати на ваш webhook тестову подію просто зараз |
| GET | /api/v1/reference | довідники значень для полів вакансії (спеціалізації, навички, рівні, країни та інші) з версією, щоб помічати зміни; забирайте не частіше ніж раз на годину |
Дані відгуку
Ви отримуєте лише ті відгуки, які кандидати подали самі. Контакти та резюме є у відповіді, якщо кандидат відкрив вашій компанії контакти, а при відгуку на Jobico це відбувається завжди. Поле cv містить url, fileName, contentType і size (розмір у байтах, може бути null). cv.url - це підписане посилання, яке 7 днів відкривається без ключа, з браузера чи із сервера (клієнт має переходити за редіректом або додати ?download=1, щоб отримати байти одразу); кожен запит відгуку повертає свіже посилання, а та сама адреса відповідає і на ваш API-ключ. Надіслане резюме лишається доступним, поки кандидат ділиться з вами контактами, навіть якщо згодом замінить файл у профілі; посилання перестає відповідати, щойно кандидат закриє контакти або ви перевипустите API-ключ.
{
"data": [
{
"id": "6abc0000000000000000ab12",
"status": "applied",
"appliedAt": "2026-10-01T09:12:33.000Z",
"job": { "id": "6ab1...", "slug": "senior-product-designer", "title": "Senior Product Designer", "url": "https://jobico.io/jobs/senior-product-designer" },
"candidate": { "name": "Olena Shevchenko", "email": "olena@example.com", "phone": "+380..." },
"cv": { "url": "https://jobico.io/api/v1/applications/6abc0000000000000000ab12/cv?t=1764158400000.q3Xv9mJ2kLp8sT1uWz4yB6cD0eF7gH5iK9lM2nO4pR8", "fileName": "resume.pdf", "contentType": "application/pdf", "size": 184322 },
"coverLetter": "...",
"screeningAnswers": [{ "question": "...", "answer": "..." }],
"matchScore": 87,
"url": "https://jobico.io/employer/applications/6abc0000000000000000ab12"
}
],
"nextCursor": "MTc5MTAyMTYwMDAwMDo2YWJjMDAwMDAwMDAwMDAwMDAwMGFiMTI",
"total": 73
}Посторінковий обхід і синхронізація
Кожен список (вакансії й відгуки) ділиться на частини однаково: передайте limit (від 1 до 100, за замовчуванням 50) і отримайте data, nextCursor і total. Щоб прочитати наступну частину, надішліть цей nextCursor як cursor; коли він повернеться як null, ви отримали все (якщо сторінка закінчилася рівно на останньому рядку, за нею буде ще одна порожня). total рахує всі рядки за вашими фільтрами незалежно від курсора, тож він однаковий на кожній сторінці. У межах одного читання курсор памʼятає, де саме ви зупинилися, тому нічого не пропускається й не повторюється, навіть коли кілька рядків мають однаковий час або один із них тим часом видалено. Для регулярної синхронізації відгуків запамʼятовуйте appliedAt найновішого збереженого відгуку й наступного разу надсилайте його як since; since включний, тож пропускайте id, які у вас уже є. Номерів сторінок немає: параметр page ігнорується, і ви отримуєте першу сторінку; курсор, який ми не видавали, отримає 400. Фільтри на кшталт since поєднуються з курсором.
curl "https://jobico.io/api/v1/applications?cursor=MTc5MTAyMTYwMDAwMDo2YWJjMDAwMDAwMDAwMDAwMDAwMGFiMTI&limit=100" \
-H "Authorization: Bearer jk_live_..."Як повідомити про рішення
Коли ваша ATS позначає відгук як переглянутий (viewed) або відхилений (rejected), надішліть нам PATCH, і кандидат побачить зміну на Jobico. Відхилити відгук можна з будь-якого стану. Скасувати відмову через API не можна, це робить лише людина в кабінеті, тож viewed для відхиленого відгуку отримає 409. Якщо надіслати статус, який уже стоїть, нічого не зміниться, і це не помилка.
curl -X PATCH "https://jobico.io/api/v1/applications/6abc0000000000000000ab12" \
-H "Authorization: Bearer jk_live_..." \
-H "content-type: application/json" \
-d '{ "status": "viewed" }'Найм
Статус hired повідомляє нам про найм кандидата за цим відгуком - так само, як кнопка «Додати найм» у кабінеті. Вакансію, кандидата й компанію ми визначаємо самі, тож інших полів у тілі немає (решта ігнорується). Статус самого відгуку не змінюється, у відповіді - той самий відгук. Подальші кроки щодо найму відбуваються між Jobico і компанією в кабінеті й через API не передаються. Повторний hired для того самого кандидата нічого не змінює й відповідає 200. Скасувати найм через API не можна - це робить людина в кабінеті.
curl -X PATCH "https://jobico.io/api/v1/applications/6abc0000000000000000ab12" \
-H "Authorization: Bearer jk_live_..." \
-H "content-type: application/json" \
-d '{ "status": "hired" }'Публікація вакансій з вашої ATS
POST /api/v1/jobs створює вакансію з тими самими полями й за тими самими правилами, що й форма в кабінеті. Обов'язкові: title, specialty, description, industries, salary (min і max; currency за замовчуванням USD), employmentType і locationType; решта необов'язкова. Тіло суворе на кожному рівні: невідоме поле отримує 400, зокрема всередині salary, location, interviewProcess і requiredLanguages, тож одруківка ніколи мовчки не губить дані. Навички в techStack зіставляються з нашим списком, разом із синонімами й регістром, і зберігаються в нашому написанні; невідома нам навичка зберігається як надіслана. У відповіді видно, що саме збережено. Команда найму не входить до API: вакансія створюється від імені адміністратора, який видав ключ (або чинного адміністратора, якщо та людина вже покинула вашу компанію), а командою керують у кабінеті. PATCH /api/v1/jobs/:id приймає будь-яку частину тих самих полів, і кожне надіслане поле повністю замінює збережене значення: список замінює весь список, а salary потребує і min, і max. Salary без currency зберігає поточну валюту вакансії. Щоб прибрати location, надішліть null; необовʼязкові текстові поля очищуються порожнім рядком, а списки - порожнім списком.
curl -X POST "https://jobico.io/api/v1/jobs" \
-H "Authorization: Bearer jk_live_..." \
-H "content-type: application/json" \
-d '{
"title": "Senior Product Designer",
"specialty": "product-designer",
"description": "<p>You will own the design of our hiring flows end to end.</p>",
"requirements": "<ul><li>5+ years in product design</li></ul>",
"industries": ["SaaS"],
"techStack": ["Figma", "reactjs"],
"grades": ["senior"],
"salary": { "min": 4000, "max": 6000, "currency": "USD" },
"employmentType": "full-time",
"locationType": "remote",
"candidateLocation": "eu-or-ukraine",
"requiredLanguages": [{ "language": "English", "minLevel": "Upper-Intermediate" }],
"screeningQuestions": ["Link to your portfolio?"],
"status": "active"
}'
{
"data": {
"id": "6ab1000000000000000000c3",
"slug": "senior-product-designer-acme-k2f9",
"title": "Senior Product Designer",
"status": "active",
"archived": false,
"url": "https://jobico.io/jobs/senior-product-designer-acme-k2f9",
"techStack": ["Figma", "React"],
"salary": { "min": 4000, "max": 6000, "currency": "USD" },
"postedAt": "2026-10-18T09:00:00.000Z",
"createdAt": "2026-10-18T09:00:00.000Z",
...
}
}Локація і право на відгук
Право на відгук визначають два поля. candidateLocation - регіон кандидата: worldwide, ukraine, outside-ukraine, eu або eu-or-ukraine. location - обʼєкт із полями country і city: country приймає value зі списку countries у GET /api/v1/reference (англійська назва, наприклад "Albania"); city - необовʼязковий довільний текст до 200 символів. Щоб приймати відгуки лише з однієї країни, вкажіть цю країну в location, а candidateLocation передайте як worldwide або не передавайте зовсім; це відповідає опції «Країна кандидата» в кабінеті. Для офісних і гібридних вакансій location також задає країну й місто офісу. Якщо передано і регіон, відмінний від worldwide, і країну, діє регіон, а країна відгуки не обмежує, тому передавайте лише одне з двох. Щоб зняти обмеження за країною, передайте "location": null у PATCH.
Статуси, перевірка і квота
status - це draft, active або inactive. Вакансія створюється як чернетка, якщо в тілі не вказано active (нова вакансія не може бути inactive). Компанія може мати щонайбільше 20 чернеток; понад це відповідь - 409. Надішліть inactive, щоб закрити вакансію, і active, щоб відкрити її знову; той самий PATCH може містити й інші поля. Вакансію, на яку вже є відгуки, не можна видалити: закрийте її, а закриту вакансію можна архівувати в кабінеті. Публікація проходить ті самі перевірки, що й у кабінеті: поки вашу компанію ще не допущено до публікації, вакансія стає в чергу, а відповідь містить status pending_review (вона вийде, щойно людина схвалить компанію); кожна перша публікація витрачає один зі слотів компанії на публікацію (за замовчуванням 15 на 30 днів), а понад це відповідь - 429 із nextSlotAt; компанія з обмеженням отримує 403. Повторне відкриття вакансії, яка вже була опублікована, слота не витрачає. Видалення, архівування та підняття лишаються в кабінеті.
curl -X PATCH "https://jobico.io/api/v1/jobs/6ab1000000000000000000c3" \
-H "Authorization: Bearer jk_live_..." \
-H "content-type: application/json" \
-d '{ "status": "inactive" }'Помилки валідації
Тіло, що порушує правило, отримує 400 з error, одним реченням для логу, та issues, по запису на кожну проблему зі шляхом поля через крапку (salary.min, requiredLanguages.0.language) і тим, що з ним не так. Межі: title від 3 до 400 символів; description щонайменше 10 символів тексту й не більше 10 000; до 20 навичок, 10 галузей, 20 переваг, 10 етапів співбесіди, 10 обов'язкових мов, 50 заблокованих країн і 5 відсівних питань по 300 символів; зарплата від 0 до 10 000 000, min не більше за max; experienceYears від 0 до 50.
HTTP/1.1 400 Bad Request
{
"error": "Minimum salary must be at least 0; Industries has too many items (max 10); Titel is not a known field",
"issues": [
{ "path": "salary.min", "message": "Minimum salary must be at least 0" },
{ "path": "industries", "message": "Industries has too many items (max 10)" },
{ "path": "titel", "message": "Titel is not a known field" }
]
}Довідники
GET /api/v1/reference повертає списки значень, з яких складається вакансія (кожне поле, крім techStack, приймає лише ці значення): specialties (value і label), skills, grades, employmentTypes, locationTypes, candidateLocations, countries (value плюс англійська та українська назви), currencies, industries, englishLevels (value і label) і languages. Надсилайте значення точно так, як у списку. Поле version - відбиток списків: збережіть його, забирайте списки не частіше ніж раз на годину (відповідь можна кешувати на цей час) і оновлюйте своє зіставлення, коли воно зміниться.
curl "https://jobico.io/api/v1/reference" \
-H "Authorization: Bearer jk_live_..."
{
"data": {
"version": "3f9c2a1b7d4e",
"specialties": [{ "value": "frontend", "label": "Front-End Developer" }, ...],
"skills": ["React", "Node.js", "PostgreSQL", ...],
"grades": ["trainee", "junior", "middle", "senior", "lead", "architect"],
"employmentTypes": ["full-time", "part-time", "contract", "freelance"],
"locationTypes": ["remote", "hybrid", "office"],
"candidateLocations": ["worldwide", "ukraine", "outside-ukraine", "eu", "eu-or-ukraine"],
"countries": [{ "value": "Ukraine", "en": "Ukraine", "uk": "Україна" }, ...],
"currencies": ["USD", "EUR", "UAH", "GBP", "PLN", "AED"],
"industries": ["FinTech", "E-commerce", ...],
"englishLevels": [{ "value": "Upper-Intermediate", "label": "Upper-Intermediate (B2)" }, ...],
"languages": ["English", "German", ...]
}
}Webhook: application.created
Вкажіть нам HTTPS-ендпоінт, на сторінці API та ATS або через API нижче, і ми надсилатимемо на нього POST із кожним новим відгуком. У тілі запиту - тип події, мітка часу та описані вище дані відгуку в полі data.
POST https://ats.example.com/hooks/jobico
content-type: application/json
user-agent: Jobico-Webhooks/1.0
webhook-id: 6abd1111111111111111cd34
webhook-timestamp: 1791021600
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
{ "type": "application.created", "timestamp": "2026-10-03T10:00:00.000Z", "data": { ...application } }Реєстрація webhook через API
Інтеграція може налаштувати webhook сама, і тоді рекрутеру лишається скопіювати лише API-ключ. Надішліть PUT з url, і у відповіді буде секрет для підпису. Виклик замінює webhook, який компанія мала раніше, і вмикає доставки; доставки, що ще чекали в черзі для попередньої адреси, скасовуються, тож доберіть пропущене через API. Кожен виклик створює новий секрет і показує його один раз, тож викликайте PUT один раз на підключення і зберігайте отримане.
curl -X PUT "https://jobico.io/api/v1/webhook" \
-H "Authorization: Bearer jk_live_..." \
-H "content-type: application/json" \
-d '{ "url": "https://ats.example.com/hooks/jobico" }'
{
"data": {
"url": "https://ats.example.com/hooks/jobico",
"enabled": true,
"createdAt": "2026-10-17T09:00:00.000Z",
"secret": "whsec_..."
}
}Тестова подія
Тестова подія - це справжня підписана доставка з вигаданим кандидатом. Поле data має точно таку форму, як в application.created: найновіша вакансія вашої компанії (або null) і зразок резюме, який можна завантажити. Тип події - webhook.test, тож подбайте, щоб ваш ендпоінт ніколи не створював з неї кандидата. Надіслати її можна зі сторінки API та ATS або через POST /api/v1/webhook/test, що відповідає полями ok і statusCode. Вона йде навіть тоді, коли webhook на паузі, ніколи не повторюється і щоразу має новий webhook-id.
{
"type": "webhook.test",
"timestamp": "2026-10-17T09:00:00.000Z",
"data": {
"id": "6abe2222222222222222ef56",
"status": "applied",
"appliedAt": "2026-10-17T09:00:00.000Z",
"job": { "id": "6ab1...", "slug": "senior-product-designer", "title": "Senior Product Designer", "url": "https://jobico.io/jobs/senior-product-designer" },
"candidate": { "name": "Test Candidate", "email": "test.candidate@example.com", "phone": "+380000000000" },
"cv": { "url": "https://jobico.io/samples/test-candidate-cv.pdf", "fileName": "test-candidate-cv.pdf", "contentType": "application/pdf", "size": 733 },
...
}
}Перевірка підпису
Доставки відповідають специфікації Standard Webhooks і мають три заголовки: webhook-id, webhook-timestamp і webhook-signature. Щоб перевірити доставку, з'єднайте id, мітку часу та необроблене тіло запиту (raw body) крапками й підпишіть цей рядок алгоритмом HMAC-SHA256, використавши як ключ секрет без префікса whsec_, декодований із base64. Будь-яка бібліотека Standard Webhooks зробить це за вас.
import { createHmac, timingSafeEqual } from 'node:crypto';
const verifyJobicoWebhook = ({ secret, headers, rawBody }) => {
const key = Buffer.from(secret.replace('whsec_', ''), 'base64');
const signed = `${headers['webhook-id']}.${headers['webhook-timestamp']}.${rawBody}`;
const expected = `v1,${createHmac('sha256', key).update(signed).digest('base64')}`;
return headers['webhook-signature']
.split(' ')
.some((sig) => sig.length === expected.length && timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));
};Повтори та гарантії доставки
Відповідайте будь-яким 2xx протягом 10 секунд (5 секунд на повторних спробах) - і доставку зараховано. Переадресації ми не виконуємо, тож 3xx вважається невдачею. Інакше ми пробуємо знову не раніше ніж через 1 хвилину, 5 хвилин, 30 хвилин, 2 години та 8 годин (обробник повторів запускається кожні 10 хвилин), а потім припиняємо. Кожен повтор несе відгук у його поточному стані. Доставка гарантується щонайменше один раз (at-least-once), тож дедуплікуйте за webhook-id.
Поки webhook на паузі, ми нічого не надсилаємо й не ставимо в чергу: відгуки, що надійшли за цей час, можна забрати через API з фільтром since. Доставки, які на момент паузи вже повторювалися, зачекають і підуть після ввімкнення, якщо ввімкнути протягом 30 днів від відгуку. Видалення webhook скасовує все, що ще чекало.
Інтеграції з ATS
Підключіть ATS, з якою вже працюєте. Якщо вашої системи тут ще немає, те саме роблять API та webhook, описані вище. Потрібна насамперед певна система? Напишіть нам на support@jobico.io.
Доступно
Незабаром
- PeopleForce
- Greenhouse
- Lever
- Teamtailor
- Workable
Правила використання
- API-ключ і секрет webhook конфіденційні. Ваша компанія відповідає за кожен запит, зроблений з їх використанням, і має негайно перевипустити їх у разі витоку.
- Дії через API вважаються діями вашої компанії: вакансію, яку опублікувала інтеграція, кандидати бачать від імені вашої компанії, статус, який вона виставила, бачить кандидат, а зареєстрований нею webhook замінює попередній.
- Дані кандидатів, отримані через API або webhook, можна використовувати лише для обробки відгуків на власні вакансії, а на вимогу кандидата їх потрібно видалити.
- Використання регулюється нашими Умовами використання