API Documentation

Build powerful integrations with the ZamanSync REST API. Type-safe, well-documented, and developer-friendly.

Getting Started

RESTful API

Clean, predictable REST endpoints with JSON responses

Secure by Default

JWT authentication with rate limiting and encryption

Versioned

Stable API versions with backwards compatibility

Authentication

All API requests require authentication using JWT tokens in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Get your API key from the dashboard under Settings → API Keys

Base URL

https://api.zamansync.io/v1

Core Endpoints

POST/auth/login

Authenticate and receive JWT token

POST/shift-events/clock-in

Clock in an employee with GPS verification

POST/shift-events/clock-out

Clock out an employee

GET/shift-events

List shift events with filtering

GET/timesheets

Get timesheets for date range

PATCH/timesheets/:id/approve

Approve a timesheet (Manager+ only)

POST/users

Create a new user (Admin only)

GET/users

List organization users

POST/locations

Create a work location (Admin only)

GET/reports/hours-by-employee

Generate employee hours report

POST/reports/export/timesheets

Export timesheets to CSV

Example Request

Clock in an employee with GPS verification:

POST /v1/shift-events/clock-in
Content-Type: application/json
Authorization: Bearer YOUR_JWT_TOKEN

{
  "locationId": "uuid-location-id",
  "timestamp": "2025-10-17T09:00:00Z",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "accuracy": 10,
  "deviceId": "device-fingerprint",
  "idempotencyKey": "unique-request-id"
}

Example Response

{
  "success": true,
  "data": {
    "shiftEventId": "uuid-event-id",
    "timestamp": "2025-10-17T09:00:00Z",
    "status": "CLOCKED_IN",
    "geofenceValid": true
  }
}

Error Handling

All errors follow a consistent format with HTTP status codes and error details:

{
  "success": false,
  "error": {
    "code": "GEOFENCE_VIOLATION",
    "message": "Clock-in location is outside the allowed geofence radius",
    "details": {
      "distance": 523,
      "allowedRadius": 100
    }
  }
}

400Bad Request - Validation error

401Unauthorized - Invalid or missing JWT

403Forbidden - Insufficient permissions

404Not Found - Resource doesn't exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error

Rate Limiting

API requests are rate-limited to ensure fair usage:

• Per IP: 100 requests per minute
• Per User: 1000 requests per hour
• Rate limit headers included in all responses
• Contact support for higher limits

SDKs & Libraries

Official client libraries for popular languages:

JavaScript/TypeScript

npm install @zamansync/sdk

Python

pip install zamansync

Ruby

gem install zamansync

Ready to integrate?

Get your API key and start building with ZamanSync today.