Sarluma
  • Features
  • Security
  • API
  • Terms
  • Privacy
Sign in

API guide

Use the API to keep your employee list in sync with your HR system and to read evaluation results into your own reports. It is plain HTTPS and JSON, so it works from any language and from tools such as Zapier, Make or Power BI.

1. Create a key

A company administrator creates keys in Account → API keys. Choose Read only for reporting tools, or Read and update employees for an HR system. The key is shown once, so store it in your secret manager. Revoke a key there at any time; it stops working immediately.

2. Send it with every request

curl https://sarluma.com/api/v1/employees \
  -H "Authorization: Bearer evk_your_key"

A key belongs to one company and can only ever reach that company's data. Call the API from your server, never from a web page or a mobile app, because anyone who can see the key can use it.

3. Endpoints

Method and pathWhat it doesKey needed
GET /api/v1/companyCompany name, plan, employee limit, subscription endRead
GET /api/v1/departmentsDepartmentsRead
GET /api/v1/employees?limit=100&offset=0Employees, up to 500 per pageRead
PUT /api/v1/employees/{code}Create the employee with this code, or update it if it existsRead and update
GET /api/v1/cyclesEvaluation cycles and their statusRead
GET /api/v1/cycles/{id}/resultsScore, rating and rank of every employee in a cycleRead

Create or update an employee

curl -X PUT https://sarluma.com/api/v1/employees/E014 \
  -H "Authorization: Bearer evk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara Ahmed","job_title":"Nurse","department":"Nursing","form_code":"NURSE","active":true}'

Only name is required for a new employee. Fields you leave out keep their current value. department and form_code must already exist in your account. Send "active": false when someone leaves; their past evaluations are kept. Sending the same request twice is safe.

Read results

{
  "cycle": { "id": "…", "name": "2026 Review", "status": "open" },
  "evaluations_assigned": 5,
  "evaluations_completed": 5,
  "results": [
    {
      "employee_code": "E02", "name": "Khaled Yousef", "department": "Nursing",
      "evaluations_received": 2, "score": 3.8, "max_score": 4,
      "percent": 95.0, "rating": "exceeds_expectations",
      "rank": 1, "rank_in_form": 1,
      "areas": [ { "no": 1, "name": "Quality", "average": 4.75 } ]
    }
  ]
}

rating is one of unsatisfactory, needs_improvement, meets_expectations, exceeds_expectations, and is empty until the employee has at least one submitted evaluation. The API returns each employee's averages. It does not return which evaluator gave which score, or the written comments.

Errors

Errors come back as {"error": {"code": "…"}} with a matching HTTP status.

StatusCodeMeaning
401invalid_api_keyThe key is missing, mistyped or revoked
402subscription_expiredThe subscription has ended; reading still works, changes do not
403read_only_keyThis key cannot make changes
404not_foundNo such item in your company
409employee_limit_reachedYour plan's employee limit is full
422unknown_department, unknown_form, name_requiredFix the request and send it again
429too_many_attemptsToo many requests with a wrong key; wait for the time in Retry-After

Every change made through the API appears in your company's audit log, marked as coming from the API.