Developers

Recruitizr Open API v1

A documented, versioned REST API and HMAC-signed webhooks. Build integrations with Zapier, Slack, your HRMS — or anything else that speaks HTTP.

Download Postman / Bruno collection Read the quick start

Quick start

Every request is authenticated with a tenant API key. Create one inside the app at Organization → API & Webhooks, then verify it with a single curl:

curl -H "Authorization: Bearer rk_live_..." \
     https://recruitizr.ai/api/v1/me

On success you'll get back the tenant context:

{
  "tenant_id":   "f8c669c6-...",
  "tenant_slug": "your-tenant",
  "api_key_name": "Production",
  "scopes": ["read", "write"]
}

Authentication

Authorization: Bearer rk_live_... — or X-API-Key header.

Versioning

URL-versioned at /api/v1/*. Breaking changes ship in v2.

Tenancy

API keys are tenant-scoped. You never see other tenants' data.

Endpoints

A focused, intentional surface for the most common integration jobs. More endpoints ship behind feature flags as customers ask for them.

Method	Path	Description
GET	/api/v1/me	Verify your API key and return tenant context.
GET	/api/v1/positions	List positions in your tenant. Filter by status, paginate with limit/skip.
POST	/api/v1/positions	Create a new position. Sets created_via:"api_v1".
GET	/api/v1/candidates	List candidates. Filter by position_id, email, or phone.
GET	/api/v1/candidates/{id}	Fetch a single candidate by id.
POST	/api/v1/candidates	Create a candidate. Fires the candidate.created webhook.
GET	/api/v1/interviews	List interviews. Filter by candidate_id and status.
GET	/api/v1/companies	List companies / clients.

Example — create a candidate

curl -X POST https://recruitizr.ai/api/v1/candidates \
  -H "Authorization: Bearer rk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_name": "Jane Doe",
    "position_id": "POSITION_UUID",
    "email": "jane@example.com",
    "phone": "+91-9000000000",
    "source": "linkedin"
  }'

Creating a candidate via the API fires the candidate.created webhook to every active subscription registered for your tenant.

Webhooks

Recruitizr POSTs signed JSON payloads to your endpoint when interesting things happen in your tenant. Every request carries an HMAC-SHA256 signature in X-Recruitizr-Signature so you can verify authenticity without trusting the network. Retries are spaced 2s / 10s / 60s.

Available events

candidate.created

A new candidate was added to a position.

candidate.updated

A candidate record was updated (status, contact, etc.).

interview.scheduled

An interview slot was scheduled.

interview.completed

An interview was marked complete with feedback.

closure.created

A candidate was successfully closed / placed.

resignation.approved

An employee resignation was approved in HRMS.

cv.uploaded

A CV file was attached to a candidate record.

Verify the signature (Node.js)

// Node.js — verify the HMAC signature on incoming webhooks
import crypto from "node:crypto";

export function verifyRecruitizrSignature(req, secret) {
  const header = req.headers["x-recruitizr-signature"] || "";
  const [, sig] = header.split("=");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)            // Buffer of the raw JSON body
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(sig, "hex"),
    Buffer.from(expected, "hex")
  );
}

Verify the signature (Python)

# Python — verify the HMAC signature on incoming webhooks
import hmac, hashlib

def verify_recruitizr_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    _, _, sig = header.partition("=")
    return hmac.compare_digest(sig, expected)

Treat the signing secret like a password. We only show it to you once, on subscription creation. Store it in your secrets manager, never commit it, and rotate it by deleting the webhook and creating a new one.

Ready to build?

Start a free trial, generate your first API key, and ship your first integration this afternoon.

Postman collection

We Value Your Privacy

We use cookies to enhance your browsing experience, serve personalized content, and analyze our traffic. By clicking "Accept All", you consent to our use of cookies. You can customize your preferences below.

Read our Privacy Policy and Cookie Policy