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 path | What it does | Key needed |
|---|---|---|
GET /api/v1/company | Company name, plan, employee limit, subscription end | Read |
GET /api/v1/departments | Departments | Read |
GET /api/v1/employees?limit=100&offset=0 | Employees, up to 500 per page | Read |
PUT /api/v1/employees/{code} | Create the employee with this code, or update it if it exists | Read and update |
GET /api/v1/cycles | Evaluation cycles and their status | Read |
GET /api/v1/cycles/{id}/results | Score, rating and rank of every employee in a cycle | Read |
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.
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_api_key | The key is missing, mistyped or revoked |
| 402 | subscription_expired | The subscription has ended; reading still works, changes do not |
| 403 | read_only_key | This key cannot make changes |
| 404 | not_found | No such item in your company |
| 409 | employee_limit_reached | Your plan's employee limit is full |
| 422 | unknown_department, unknown_form, name_required | Fix the request and send it again |
| 429 | too_many_attempts | Too 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.