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

This page is the operating guide — creating keys, configuring webhooks and wiring payroll. The endpoint reference itself is deliberately not duplicated here: it lives next to the code and is updated with every release, covering the whole system — attendance, employees, tasks and projects, custom fields, recurring series, webhooks health and more.

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.

The API goes well beyond attendance. The same key also manages the task-management module: create and update tasks, post comments, set assignees by employee code, fill custom fields, read per-project status boards, and run bulk updates across up to 200 tasks in one request.

Recurring Tasks

A task can be made a recurring series through the API: send a recurrence rule (daily, specific weekdays, a day of the month, quarterly/yearly dates, or an every-N cadence) and the task becomes the series template. Completing the template starts the schedule — a fresh copy with the same content, assignees and estimate is created automatically on each matching day, in the organization's own timezone. Pause, resume, retune or stop a series with a single update call, and list every occurrence it has spawned.

MCP Server for AI Agents

Clokio ships an official MCP server — 50 tools covering tasks, attendance, employees and projects — so AI assistants like Claude, Cursor or any MCP-compatible client can work with your Clokio data directly, using your own API key and nothing more:

npx -y clokio-mcp

The server adds no permissions of its own: every call is governed by the key's scopes, exactly like a direct API request.

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.