API & Integrations

Every API request must include a valid API key for authentication. Keys are scoped to your organization, meaning a key can only access data belonging to your company.

Creating an API Key

1. 1

   Navigate to API Keys

   In the admin dashboard, go to Admin > API Keys.

2. 2

   Click "Create New Key"

   Give your key a descriptive name (e.g., "Payroll Integration" or "HR Dashboard").

3. 3

   Copy and Store the Key

   The key is displayed only once in the format clk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Copy it immediately and store it in a secure location (e.g., environment variables, a secrets manager).

Key Properties

Authentication Header

Include your API key in the X-API-Key header on every request:

curl -H "X-API-Key: clk_your_api_key_here" \
     -H "Content-Type: application/json" \
     https://app.clokio.io/api/v1/employees

The Clokio Public API v1 is a RESTful API. All endpoints are under /api/v1/ and return JSON. Every response follows the same format:

{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": { ... }
}

Read Endpoints (GET)

curl -H "X-API-Key: clk_your_key" \
     https://app.clokio.io/api/v1/employees

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/daily?date=2026-02-10"

{
  "status": "success",
  "message": "Daily attendance retrieved",
  "data": [
    {
      "employee_id": 42,
      "employee_name": "Sarah Johnson",
      "nip": "EMP-1042",
      "clock_in": "2026-02-10T08:55:00Z",
      "clock_out": "2026-02-10T17:32:00Z",
      "total_hours": 7.87,
      "break_minutes": 45,
      "status": "present"
    }
  ]
}

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/range?start=2026-02-01&end=2026-02-28"

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/employee/EMP-1042"

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/summary?month=02&year=2026"

Detailed Daily Activity

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/employee/00042/today?date=2026-03-26"

curl -H "X-API-Key: clk_your_key" \
     "https://app.clokio.io/api/v1/attendance/today/detailed?date=2026-03-26"

Write Endpoints (POST)

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042", "latitude": 32.0853, "longitude": 34.7818}' \
     https://app.clokio.io/api/v1/attendance/clock-in

{
  "status": "success",
  "message": "Employee clocked in successfully",
  "data": {
    "attendance_id": 8847,
    "employee_name": "Sarah Johnson",
    "clock_in": "2026-02-12T08:55:12Z",
    "location": "Main Office"
  }
}

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042", "latitude": 32.0853, "longitude": 34.7818}' \
     https://app.clokio.io/api/v1/attendance/clock-out

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042"}' \
     https://app.clokio.io/api/v1/attendance/break-start

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"nip": "EMP-1042"}' \
     https://app.clokio.io/api/v1/attendance/break-end

Employee Management

curl -X POST \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Jane Smith",
       "email": "jane@company.com",
       "phone": "+1234567890",
       "position": "Software Engineer",
       "department": "Engineering",
       "location": "Main Office"
     }' \
     https://app.clokio.io/api/v1/employees

curl -X PATCH \
     -H "X-API-Key: clk_your_key" \
     -H "Content-Type: application/json" \
     -d '{"status": "inactive"}' \
     https://app.clokio.io/api/v1/employees/00042/status

Error Handling

When a request fails, the API returns an appropriate HTTP status code along with an error message:

// 401 Unauthorized - Invalid or missing API key
{
  "status": "error",
  "message": "Invalid API key",
  "data": null
}

// 422 Unprocessable Entity - Validation error
{
  "status": "error",
  "message": "The date field is required",
  "data": null
}

// 429 Too Many Requests - Rate limit exceeded
{
  "status": "error",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "data": null
}

Webhooks let you receive real-time notifications when attendance events happen, without needing to poll the API. When an employee clocks in, clocks out, or takes a break, Clokio sends an HTTP POST request to your configured URL.

Supported Platforms

Supported Events

Filtering

You do not have to receive notifications for every event. Webhooks support granular filtering so you only get notified about what matters:

• By Location: Only receive events from specific work locations.
• By Employee: Monitor specific employees (e.g., new hires during probation).
• By Department: Limit notifications to certain departments.
• By Day of Week: Only send notifications on working days.
• By Time Range: Only trigger during specific hours (e.g., 6:00 AM - 10:00 AM for late-arrival monitoring).

Custom Message Templates

Customize the message that gets sent to your channel. Use placeholders like {employee_name}, {event_type}, {timestamp}, and {location_name} to build messages that fit your team's style.

Delivery Tracking & Retries

Clokio tracks the delivery status of every webhook notification. If a delivery fails (e.g., your endpoint is temporarily down), the system retries with exponential backoff. You can view delivery logs in the admin dashboard under Webhooks > Delivery Log to diagnose issues.

One of the most valuable uses of the Clokio API is feeding attendance data into your payroll system. Whether you use a manual process or automated software, Clokio provides the data you need.

Option 1: CSV Export (Manual)

The simplest approach is to export the monthly summary as a CSV file from the admin dashboard, then import it into your payroll software. The CSV includes all the fields payroll systems typically need: employee name/ID, total hours, overtime, leave days, and absence count. Most payroll software (including popular tools like ADP, Gusto, and QuickBooks) can import CSV files.

1. 1

   Go to Reports > Monthly Summary

   Select the month and year.

2. 2

   Click "Export CSV"

   The file downloads to your computer.

3. 3

   Import into Payroll Software

   Use your payroll tool's CSV import feature. Map the Clokio columns to your payroll fields.

Option 2: API Integration (Automated)

For organizations that want to eliminate manual steps entirely, use the API to sync attendance data automatically. A typical setup involves a nightly script that:

1. 1

   Fetches Yesterday's Attendance

   Calls GET /api/v1/attendance/daily?date=YYYY-MM-DD for yesterday's date.

2. 2

   Transforms the Data

   Maps Clokio fields to your payroll system's expected format.

3. 3

   Pushes to Payroll

   Sends the data to your payroll system's API or import endpoint.

Here is an example script (Node.js) that fetches yesterday's attendance:

// fetch-attendance.js
const API_KEY = process.env.CLOKIO_API_KEY;
const BASE_URL = 'https://app.clokio.io/api/v1';

// Get yesterday's date
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);
const dateStr = yesterday.toISOString().split('T')[0];

async function fetchAttendance() {
  const response = await fetch(
    `${BASE_URL}/attendance/daily?date=${dateStr}`,
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const result = await response.json();

  if (result.status === 'success') {
    console.log(`Found ${result.data.length} records for ${dateStr}`);
    // Transform and send to your payroll system here
    return result.data;
  } else {
    console.error('API Error:', result.message);
  }
}

fetchAttendance();

Monthly Summary for Payroll

At the end of each month, use the GET /api/v1/attendance/summary endpoint to retrieve a complete summary for every employee. This gives you total hours, overtime, leave days, and absence count -- everything your payroll department needs.