Overview

The Watheef API allows you to integrate your recruitment workflow with external systems. Push jobs from your ERP, pull applications into your HRIS, and receive real-time webhook notifications when events happen.

Authentication

All requests require an API key passed as a Bearer token. Generate keys from your organization's Settings → API Keys page.

curl -H "Authorization: Bearer wtf_your_api_key" \
  https://watheef.com/api/v1/jobs

Rate Limits

120 requests per minute per IP. Exceeding this returns 429 with a Retry-After header.

Error Handling

All errors return a JSON object with an error field.

List Jobs

{
  "data": [
    {
      "id": "clx1abc...",
      "title": "Senior Backend Engineer",
      "slug": "senior-backend-engineer",
      "status": "PUBLISHED",
      "employmentType": "CONTRACT",
      "employmentTypeLabel": "Contract",
      "workMode": "REMOTE",
      "workModeLabel": "Remote",
      "location": "Kuwait City",
      "department": "Engineering",
      "skills": ["Node.js", "PostgreSQL", "AWS"],
      "applicantCount": 12,
      "publishedAt": "2026-03-20T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

Create Job

{
  "title": "Product Manager",
  "description": "We are looking for a Product Manager to own our roadmap...",
  "requirements": "3+ years PM experience in fintech or SaaS",
  "benefits": "Competitive salary, health insurance, annual bonus",
  "employmentType": "FULL_TIME",
  "workMode": "HYBRID",
  "location": "Kuwait City",
  "department": "Product",
  "experienceLevel": "Mid-Senior",
  "skills": ["Agile", "Product Strategy", "Data Analysis"],
  "salaryMin": 800,
  "salaryMax": 1200,
  "showSalary": true,
  "publish": true,
  "expiresInDays": 30
}

Get Job

List Applications

List Webhooks

Create Webhook

{
  "url": "https://your-erp.com/webhooks/watheef",
  "events": [
    "application.created",
    "application.hired",
    "job.created"
  ]
}

{
  "data": {
    "id": "clx2def...",
    "url": "https://your-erp.com/webhooks/watheef",
    "events": ["application.created", "application.hired", "job.created"],
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6...",
    "active": true
  }
}

Delete Webhook

Event Types

Subscribe to any combination of these events when creating a webhook.

Payload Format

{
  "event": "application.created",
  "data": {
    "applicationId": "clx3ghi...",
    "candidateName": "Ahmad Ali",
    "jobTitle": "Senior Engineer",
    "status": "APPLIED"
  },
  "timestamp": "2026-03-21T16:00:00.000Z"
}

Verifying Signatures

Every webhook request includes an X-Watheef-Signature header. Verify it using HMAC-SHA256 with your webhook secret.

const crypto = require("crypto");

function verifyWebhook(rawBody, secret, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return expected === signature;
}

// Express.js example:
app.post("/webhooks/watheef", (req, res) => {
  const sig = req.headers["x-watheef-signature"];
  if (!verifyWebhook(JSON.stringify(req.body), SECRET, sig)) {
    return res.status(401).send("Invalid signature");
  }
  // Process the event...
  res.sendStatus(200);
});

ERP Integration

Connect Watheef with your ERP to automate the hiring workflow end-to-end.

ODOO Integration

ODOO is popular in Kuwait. Here's how to connect Watheef with your ODOO instance.

# In your ODOO custom module, call Watheef when
# a recruitment request is approved:

import requests

WATHEEF_API_KEY = "wtf_your_key_here"
BASE_URL = "https://watheef.com/api/v1"

def create_watheef_job(recruitment_request):
    response = requests.post(
        f"{BASE_URL}/jobs",
        headers={"Authorization": f"Bearer {WATHEEF_API_KEY}"},
        json={
            "title": recruitment_request.job_title,
            "description": recruitment_request.description,
            "department": recruitment_request.department_id.name,
            "location": "Kuwait City",
            "employmentType": "FULL_TIME",
            "publish": True,
        }
    )
    return response.json()

SAP Integration

For SAP SuccessFactors or SAP HCM integration, use the same REST endpoints. Create a middleware service that translates between SAP's data model and Watheef's API. Contact [email protected] for enterprise integration support.