Skip to content

Quick start

Create a key, add an employee through the API and read their leave.

Developer documentation

By the end of this guide you have an API key, you have added an employee through the API and you have read that employee's leave. The commands need curl and jq. Each command uses the variables and files left by the previous one: run them in order, in the same shell session, in an empty directory.

1. Turn on the API module

API access starts turned off in an account. The account owner turns on the API module on the Settings › Sector and Modules screen. The module depends on your plan.

2. Create a key

On the Settings › API screen press New key and fill in the form:

  • Key name: a name that tells which system uses the key.
  • Role: the key cannot see more than this role sees. For this guide choose a role that sees the whole account (for example Account Owner).
  • Scopes: select these four.
  • employees:read: Read employees
  • employees:write: Create and update employees
  • leave:read: Read leave
  • org:read: Read the organisation structure
  • Validity: 90 days by default, at most 365 days.
  • Allowed IP addresses: optional; leave it empty and the key works from any address.

Creating a key asks for extra verification: a fresh confirmation of your two-step verification or a code sent to your email. The full key starts with biik_sk_ and is shown only once; store it in a password manager right away.

3. Set the environment variables

export BIIK_API_URL="https://app.biik.io"
export BIIK_API_KEY="biik_sk_..."

The address of the application and the key you created. Do not put the key in source code or version control.

4. Test the key

curl -sS "$BIIK_API_URL/api/v1/key" \
  -H "Authorization: Bearer $BIIK_API_KEY"

Expected response: 200 Successful

Response fields: id, name, scopes, expires_at

5. Get the company ID

Every employee belongs to a company. Take the first company the key can see and store it in COMPANY_ID:

curl -sS "$BIIK_API_URL/api/v1/companies?limit=1" \
  -H "Authorization: Bearer $BIIK_API_KEY" | tee companies.json
COMPANY_ID=$(jq -r '.data[0].id' companies.json)

Expected response: 200 Successful

Example response (from the OpenAPI document)
{
  "data": [
    {
      "id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
      "name": "Marmara Lojistik Ltd.",
      "city": "Bursa",
      "is_demo": false,
      "created_at": "2026-01-05T08:00:00.000Z",
      "updated_at": "2026-03-02T09:15:00.000Z"
    }
  ],
  "next_cursor": null
}

6. Create an employee

POST requests need an Idempotency-Key header: if the connection drops you can safely repeat the same request with the same key (Idempotency). -i also prints the response headers; the body is on the last line.

IDEMPOTENCY_KEY="first-employee-$(date +%s)"
cat > employee.json <<JSON
{
  "company_id": "$COMPANY_ID",
  "first_name": "Deniz",
  "last_name": "Kaya",
  "hire_date": "2026-01-05"
}
JSON
curl -sS -i -X POST "$BIIK_API_URL/api/v1/employees" \
  -H "Authorization: Bearer $BIIK_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data @employee.json | tee created.txt
EMPLOYEE_ID=$(tail -n 1 created.txt | jq -r .id)

Expected response: 201 Created

Example response (from the OpenAPI document)
{
  "id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
  "job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
  "position_id": null,
  "manager_id": null,
  "first_name": "Deniz",
  "last_name": "Kaya",
  "work_email": "[email protected]",
  "status": "active",
  "employment_type": "full_time",
  "hire_date": "2026-03-02",
  "service_start_date": null,
  "sgk_entry_date": null,
  "probation_end": "2026-05-02",
  "is_demo": false,
  "created_at": "2026-02-24T09:30:00.000Z",
  "updated_at": "2026-03-02T07:00:00.000Z"
}

7. Repeat the same request

A request with the same key and the same body does not create a second employee: it returns the current state of the same record and the Idempotent-Replayed: true header.

curl -sS -i -X POST "$BIIK_API_URL/api/v1/employees" \
  -H "Authorization: Bearer $BIIK_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data @employee.json

Expected response: 201 Created · Header: Idempotent-Replayed: true

The id in the response equals the value in the EMPLOYEE_ID variable.

Example response (from the OpenAPI document)
{
  "id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
  "job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
  "position_id": null,
  "manager_id": null,
  "first_name": "Deniz",
  "last_name": "Kaya",
  "work_email": "[email protected]",
  "status": "active",
  "employment_type": "full_time",
  "hire_date": "2026-03-02",
  "service_start_date": null,
  "sgk_entry_date": null,
  "probation_end": "2026-05-02",
  "is_demo": false,
  "created_at": "2026-02-24T09:30:00.000Z",
  "updated_at": "2026-03-02T07:00:00.000Z"
}

8. Read the employee

curl -sS "$BIIK_API_URL/api/v1/employees/$EMPLOYEE_ID" \
  -H "Authorization: Bearer $BIIK_API_KEY"

Expected response: 200 Successful

The id in the response equals the value in the EMPLOYEE_ID variable.

Example response (from the OpenAPI document)
{
  "id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
  "org_unit_id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
  "job_title_id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
  "position_id": null,
  "manager_id": null,
  "first_name": "Deniz",
  "last_name": "Kaya",
  "work_email": "[email protected]",
  "status": "active",
  "employment_type": "full_time",
  "hire_date": "2026-03-02",
  "service_start_date": null,
  "sgk_entry_date": null,
  "probation_end": "2026-05-02",
  "is_demo": false,
  "created_at": "2026-02-24T09:30:00.000Z",
  "updated_at": "2026-03-02T07:00:00.000Z"
}

The national ID, IBAN, salary and personal details are returned only when the key carries the matching field: scope and the role carries the same field class; with this guide's key even the field names are absent from the response (Authentication and scopes).

9. Read their leave

The employee now appears in the Employees list in the product. The first API version does not write leave: a leave request is created and approved in the product (the Leave module must be turned on). For example HR opens a new request on the Leave screen, picks the person and sends the request on the employee's behalf; the request is approved in the approval flow. Once it is approved:

curl -sS "$BIIK_API_URL/api/v1/leave-requests?employee_id=$EMPLOYEE_ID" \
  -H "Authorization: Bearer $BIIK_API_KEY"

Expected response: 200 Successful

Example response (from the OpenAPI document)
{
  "data": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
      "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type_hidden": false,
      "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "status": "approved",
      "start_date": "2026-07-06",
      "end_date": "2026-07-10",
      "half_day": false,
      "amount": 5,
      "unit": "day",
      "paid": true,
      "is_demo": false,
      "created_at": "2026-06-15T11:20:00.000Z",
      "updated_at": "2026-06-16T08:05:00.000Z"
    }
  ],
  "next_cursor": null
}
curl -sS "$BIIK_API_URL/api/v1/leave-balances?employee_id=$EMPLOYEE_ID" \
  -H "Authorization: Bearer $BIIK_API_KEY"

Expected response: 200 Successful

Example response (from the OpenAPI document)
{
  "data": [
    {
      "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "unit": "day",
      "balance": 9,
      "reserved": 2,
      "available": 7
    }
  ],
  "next_cursor": null
}

Next