Skip to content

Developers

The biik REST API and webhooks: what you can read, what you can write, where to start.

Developer documentation

The biik REST API lets external systems (payroll, accounting, access control, your own reporting tool) read the employee, organisation, leave and shift records in your account, and create and update employees. Webhooks notify your address about changes to the same records.

What is available

  • Read: employees, companies, locations, units, job titles, leave types, leave requests, leave balances, published shift assignments and the event stream.
  • Write: create an employee (POST /api/v1/employees) and update one (PATCH /api/v1/employees/{id}). Writing leave, payroll and timesheets is not part of the first API version; those are done in the product.
  • Webhooks: signed notifications of employee, unit, leave, shift and approval events.

Ground rules

  • The address is the application's own address; paths start with /api/v1. Requests come over HTTPS and authenticate only with the Authorization: Bearer header.
  • Bodies are JSON; field names are snake_case, IDs are uuid, days are YYYY-MM-DD and moments are UTC.
  • A key does not grant permissions, it narrows them: a key cannot see a record its role cannot see.
  • The error body is RFC 9457 (application/problem+json) and carries a machine-readable code. Human-readable texts in responses are in Turkish.
  • The machine-readable contract is at /api/v1/openapi.json (OpenAPI 3.1). The reference pages in this documentation are generated from the same file.

Where to start

  1. Quick start: create a key, add an employee, read their leave.
  2. Authentication and scopes: what each scope opens and how classified fields are returned.
  3. Webhooks: get notified instead of polling.
  4. API reference: every endpoint, field and example response.