Developers

The Aequo API

Connect Aequo to your other systems – IT user provisioning, rostering, invoicing or BI. REST, JSON, OpenAPI 3. Available on the Business and Mittelstand plans.

Scoped API keys

Each key may only do what it needs – read or write per resource. Revocable at any time.

Privacy built in

No salary, health or whistleblowing data. Illness only appears as “absent”.

Fairly limited, fully logged

120 requests per minute per key. Every call is logged for your admin for 90 days.

Authentication

The company admin creates a key under Settings → API keys and chooses its scopes. The key is shown once. Send it with every call in the header “Authorization: Bearer aeq_…”.

Base URL: https://<workspace>.aequohr.com/api/public/v1

curl https://your-company.aequohr.com/api/public/v1/employees?per_page=100 \
  -H "Authorization: Bearer aeq_…" \
  -H "Accept: application/json"
{
  "data": [
    { "id": 12, "employee_number": "E-1042", "first_name": "Jonas", "last_name": "Weber",
      "work_email": "jonas.weber@example.de", "department": { "id": 3, "name": "Logistik" },
      "job_title": "Teamleitung Lager", "employment_status": "active", "hire_date": "2021-04-01" }
  ],
  "links": { "next": "…?page=2" },
  "meta": { "current_page": 1, "last_page": 3, "per_page": 100, "total": 248 }
}

Scopes

A call without the scope it needs is rejected with 403.

  • employees:readRead employees (work master data)
  • departments:readRead departments
  • absences:readRead absences
  • working_time:readRead working time
  • project_time:readRead projects and project time
  • project_time:writeBook project time
  • documents:readRead document metadata

Endpoints

EndpointScopeReturns
GET /employeesemployees:readEmployees with work master data – name, work email, department, job title, location, manager, status, start/end date. Filters: status, updated_since
GET /employees/{id}employees:readOne employee.
GET /departmentsdepartments:readDepartments with hierarchy and head.
GET /absencesabsences:readAbsences with period, days and status. Illness appears as type “absent” without details. Filters: employee_id, status, from, to
GET /working-timeworking_time:readRecorded working time per day: clock-in, clock-out, worked, break and overtime minutes. Filters: employee_id, from, to
GET /projectsproject_time:readProjects with client, status and hour budget – no rates or euro budgets. Filters: status
GET /time-entriesproject_time:readBooked project time. Filters: employee_id, project_id, status, from, to, updated_since
POST /time-entriesproject_time:writeBook project time for an employee – as a draft for the weekly approval; the employee must be on the project team.
GET /documentsdocuments:readMetadata of employee documents – never the file, never confidential documents. Filters: employee_id, updated_since

Paging and filters

Lists are paginated: ?page= and ?per_page= (at most 100, default 50). Responses contain “data”, “links” and “meta” with the total. Use updated_since to fetch only changes since your last sync.

Error codes

  • 401 – Key missing, invalid, revoked or expired
  • 403 – Scope missing, or the API is not in the plan
  • 404 – Not found
  • 422 – Invalid parameters – details in “errors”
  • 429 – Too many requests – wait the seconds in “Retry-After”

What the API deliberately never returns

Salaries and pay, health data (illness only appears as an absence), whistleblowing cases, tax, social-insurance and bank data, and private addresses and contact details. So you can connect systems without transferring special categories of personal data.