Build on WebHR

Getting access

1. The API is the API Access add-on. Ask your WebHR account manager, or support@webhr.in, to turn it on for your workspace.
2. A workspace admin opens Settings → Integrations & Security → API Keys and creates a key: a name, the scopes it needs, and optionally the IP addresses it may be used from and an expiry date.
3. WebHR shows the client_id and client_secret once. Keep the secret in your secrets manager; WebHR stores only a fingerprint and can't show it again. If it's lost, rotate the key.

Quick start

1. Get a token

curl -X POST https://api.webhr.in/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d "{\"client_id\": \"$WEBHR_CLIENT_ID\", \"client_secret\": \"$WEBHR_CLIENT_SECRET\"}"

import os, requests

token = requests.post("https://api.webhr.in/api/v1/auth/token", json={
    "client_id": os.environ["WEBHR_CLIENT_ID"],
    "client_secret": os.environ["WEBHR_CLIENT_SECRET"],
}, timeout=10).json()["access_token"]

const res = await fetch("https://api.webhr.in/api/v1/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: process.env.WEBHR_CLIENT_ID,
    client_secret: process.env.WEBHR_CLIENT_SECRET,
  }),
});
const { access_token: token } = await res.json();

{
  "access_token": "eyJhbGciOi…",
  "token_type": "bearer",
  "expires_in": 3600,
  "scopes": ["recruitment.jobs:read"]
}

2. Call the API

curl "https://api.webhr.in/api/v1/recruitment/jobs?status=published" \
  -H "Authorization: Bearer $WEBHR_TOKEN"

jobs = requests.get("https://api.webhr.in/api/v1/recruitment/jobs",
                    params={"status": "published"},
                    headers={"Authorization": f"Bearer {token}"}, timeout=10)
jobs.raise_for_status()
for job in jobs.json()["items"]:
    print(job["job_code"], job["title"])

const jobs = await fetch("https://api.webhr.in/api/v1/recruitment/jobs?status=published", {
  headers: { Authorization: `Bearer ${token}` },
});
const { items } = await jobs.json();

{
  "items": [{ "id": 42, "job_code": "JOB-0042", "title": "Welder", "status": "published", … }],
  "total": 1,
  "page": 1,
  "page_size": 25
}

Request builder

Pick an endpoint and fill in its fields to get a command you can run. It's built from the same OpenAPI file as the reference, so it always matches the API.

Authentication

• Swap the key for a token at POST /auth/token. A token lasts one hour; there are no refresh tokens, so ask for a new one when it expires or when a call answers 401.
• Send the token in the Authorization: Bearer … header on every call. It is refused anywhere else: in a query string, a cookie or the body.
• The API is for server-to-server use. It sends no CORS headers, so a browser page can't call it, and a client secret must never ship in a web page or a mobile app.
• Rotating or revoking a key in WebHR stops its tokens on their next call, not when they expire.
• Your workspace is identified by the key alone. Headers or fields naming another workspace are ignored.

Scopes

Give each key only what it needs. A call outside the key's scopes answers 403; narrowing a key's scopes in WebHR takes effect on its next call.

Paging and syncing

Lists take page (from 1) and page_size (default 25, at most 200), and answer {"items": […], "total": n, "page": 1, "page_size": 25}. Keep asking for the next page while page × page_size < total.

To keep a copy in sync, pass updated_since (an ISO 8601 time) to GET /recruitment/jobs: it returns only jobs changed since then, most recently changed first. Store the time each sync started and use it next time.

Errors

Every error has the same shape. Quote the request_id when you contact support; a 422 also lists each field's problem in errors.

{ "detail": "This key lacks the recruitment.jobs:create scope", "request_id": "5e7250c4-…" }

Rate limits

• 50 calls a minute per key. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; over the limit you get 429 with Retry-After.
• POST /auth/token: 30 calls per 10 minutes per IP address. After 10 failed attempts for a client_id within 15 minutes, that client is locked out for the rest of the 15 minutes, even with the right secret.
• Reuse a token for its hour; don't get a new one for every call.

Retrying safely

Send an Idempotency-Key header (any unique string up to 100 characters, such as a UUID) on every POST. If the network drops and you send the same request with the same key within 24 hours, WebHR answers with the first result instead of acting twice and adds Idempotent-Replayed: true. The same key with a different body answers 422.

Jobs

• POST /recruitment/jobs always creates a draft. Publish it with POST /recruitment/jobs/{job_id}/publish; take it off the careers page with /close. A job's status changes only through these two calls.
• Fields the API doesn't accept, such as a job's workspace, status, author or dates, are refused with 422 rather than ignored, so a mistake in your integration shows up straight away.
• Use the names from GET /department-masters and GET /designation-masters so jobs match your workspace's lists. hiring_manager_employee_id must be an employee of your workspace.

Careers page

Your public careers page needs no key. These two endpoints answer anyone, so they are limited per visitor address.

Security

• Keep the client secret on your server. Never put it in a web page, a mobile app, a URL or a log.
• Give each integration its own key with the fewest scopes, and an IP allowlist when its addresses are fixed.
• Rotate keys regularly, and at once if a secret may have leaked. Revoke keys you no longer use.
• WebHR records every call a key makes; admins see the last 30 days under API Keys → Calls.
• Found a vulnerability? Please tell security@webhr.in before anyone else.

Versioning

Version 1 lives at /api/v1. Within it we only add endpoints, fields and values, so write clients that ignore fields they don't know. A change that could break a client gets a new version, /api/v2, with at least 12 months' notice before v1 changes.

Support

Email support@webhr.in with the request_id of the call in question.