# Findjobs HR Suite API

> The HR system for Georgian companies, built on findjobs.ge. This API lets a company's own agents read and (as endpoints go live) act on its HR Suite and its findjobs.ge account.

Base URL: https://hr.findjobs.ge/hr/api/v1
Auth: Authorization: Bearer fjhr_live_… (a company key) or fjhr_demo_… (a demo key, acts on the demo company only).
Keys are minted by the company owner at https://hr.findjobs.ge/hr/app/settings/api with explicit scopes. Treat a key as a password; it is shown once.
Limits: 60 calls a minute, 20 writes a minute, per key. 429 carries Retry-After.
Errors: JSON {error, message, docs}. Codes: missing_key, invalid_key, scope, rate_limited, not_yet (designed, not served), not_found, server_error.
Machine description: https://hr.findjobs.ge/hr/api/v1/openapi.json (add ?hl=ka|en|ru|tr for summaries in that language).
Human documentation: https://hr.findjobs.ge/hr/docs/api

## What a key can never do
- Read another company's data, or any job seeker's private data beyond what the company already sees on findjobs.ge.
- Move money, log in to a bank, or file with the Revenue Service. The suite prepares files; people send them.
- Mint or change keys. Keys are managed by the owner, behind the second lock.
- Learn whether an employee has a findjobs profile or is applying elsewhere.

## Endpoints
- GET /me [company:read] (live): Who you are: the company, this key's scopes and limits
- GET /home [company:read] (live): The Home queue: what needs a decision
- GET /market/pay-check [market:read] (live): What a family pays in a city: lower quarter, middle, upper quarter
- GET /market/difficulty [market:read] (live): Hiring difficulty in a city: ads per seeker, days ads stay up
- GET /market/radar [market:read] (live): Competitor radar: your open roles, rival ads, pay, who hires most
- GET /market/survey [market:read] (live): Salary survey groups in a city: companies, people, the middle of real pay
- POST /market/survey [money:write] (live): Your company's pay entry for a family: people, low, middle, high
- GET /jobs [jobs:read] (live): Your vacancies on findjobs.ge
- GET /jobs/{id} [jobs:read] (live): One vacancy in full
- GET /jobs/{id}/doctor [jobs:read] (live): The ad doctor: a 0–100 score, every check and what to fix
- POST /jobs [jobs:write] (planned): Post a vacancy (goes to moderation, as on the site)
- PATCH /jobs/{id} [jobs:write] (planned): Edit a vacancy
- POST /jobs/{id}/close [jobs:write] (planned): Close a vacancy
- POST /jobs/{id}/bump [jobs:write] (planned): Bump a vacancy (Pro)
- GET /applications [applications:read] (live): Applications to your vacancies
- GET /applications/{id} [applications:read] (live): One application: message, answers, scores
- GET /people [people:read] (live): Employee records (without private fields)
- POST /people [people:write] (live): Add a record
- GET /people/{id} [people:read] (live): One record with its history and leave balance
- PATCH /people/{id} [people:write] (live): Change a record; pay, role and department changes go to the history
- POST /people/{id}/leaving [people:write] (live): Set the last day
- GET /timeoff [people:read] (live): Time off: asked and approved
- POST /timeoff [people:write] (live): Add time off (asked, or approved at once)
- POST /timeoff/{id}/decide [people:write] (live): Decide: approved, declined, cancelled
- GET /payrun [money:read] (live): A month's pay run: lines and totals
- POST /payrun/{period}/approve [money:write] (live): Approve a month (a snapshot is taken first)
- GET /payrun/{period}/file [money:read] (live): A file of an approved month: oris, fina, 1c, excel, journal, tbc, bog, liberty, bank-excel, rsge
- GET /rules [money:read] (live): Rules and rates, with their confirmer
- POST /rules/{id}/confirm [money:write] (live): Confirm a rule in a name
- GET /snapshots [settings:write] (live): The snapshots
- POST /snapshots [settings:write] (live): Take a snapshot now
- POST /snapshots/{id}/restore [settings:write] (live): Restore a snapshot (a snapshot of now is taken first)
- GET /pipeline [applications:read] (live): One vacancy's board: stages, cards, the reply clock, scorecards
- POST /applications/{id}/status [applications:write] (live): Move a card to a stage: seen, shortlisted, hold, hired, rejected
- POST /applications/{id}/scorecard [applications:write] (live): Save a scorecard: four scores 1–5 and a note
- POST /applications/{id}/message [applications:write] (planned): Reply to the applicant in the same chat as on the site
- POST /applications/{id}/interview [applications:write] (planned): Schedule an interview
- GET /people [people:read] (planned): Employee records
- POST /people [people:write] (planned): Add an employee
- GET /people/{id} [people:read] (planned): One record (private details excluded)
- GET /leave/requests [people:read] (planned): Leave requests
- POST /leave/requests/{id}/decide [people:write] (planned): Approve or decline leave
- GET /pay-runs [money:read] (planned): Pay runs
- GET /pay-runs/{month} [money:read] (planned): One month's run with its lines
- POST /pay-runs/{month}/approve [money:write] (planned): Approve a run (files are prepared; no money moves)
- GET /rules [money:read] (planned): Rules and rates with their confirmation status
- GET /keys [settings:write] (planned): This company's keys (keys cannot be minted by a key)
- GET /webhooks [settings:write] (planned): Webhook subscriptions

## Try it
curl -H "Authorization: Bearer $KEY" "https://hr.findjobs.ge/hr/api/v1/market/pay-check?city=tbilisi&family=sales&offer=1200"