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 employeesemployees:write: Create and update employeesleave:read: Read leaveorg: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": "deniz.kaya@example.com",
"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": "deniz.kaya@example.com",
"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": "deniz.kaya@example.com",
"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
- To get notified instead of polling: Webhooks.
- Every endpoint and field: API reference.
- Error responses and retries: Error model.