Time Tracking API Standards

Authentication Patterns

API Key Authentication

How it works:

• User generates API key in settings
• Include in header: X-Api-Key: YOUR_KEY
• Simple but less secure
• Common for personal/server-to-server use

Examples: Clockify, Harvest (legacy)

OAuth 2.0 (Standard for third-party apps)

Flow:

1. App redirects user to provider auth page
2. User grants permissions
3. App receives authorization code
4. App exchanges code for access token
5. App uses access token for API requests
6. Refresh token when expired

Benefits:

• User never shares password with third party
• Granular permission scopes
• Revocable access
• Industry standard

Examples: Toggl Track, Harvest (modern), TMetric

Bearer Token

Usage: Authorization: Bearer YOUR_TOKEN

• Often combined with OAuth
• Stateless authentication
• JWT tokens sometimes used

Common Integration Patterns

Project Management Sync

Scenario: Time tracking within PM tool (Asana, Jira, Trello)

Pattern:

1. PM tool project → Time tracking project (sync)
2. PM tool task → Time tracking task
3. User starts timer on PM task
4. Time data flows back to PM tool

Examples: Everhour, Harvest, Toggl integrations

Payroll Integration

Scenario: Approved timesheets → Payroll system

Pattern:

1. Time entries aggregated by employee
2. Manager approval in time tracking system
3. Export to payroll format (CSV, API)
4. Import into payroll (Gusto, ADP, Paychex)
5. Regular hours vs. overtime calculations

Invoicing Integration

Scenario: Billable hours → Client invoices

Pattern:

1. Mark time entries as billable
2. Apply hourly rates (by user, project, or client)
3. Generate line items for invoice
4. Export to invoicing tool (QuickBooks, FreshBooks, Xero)
5. Track invoiced vs. uninvoiced time

Data Format Standards

Time Representation

Duration formats:

• Seconds (integer): 3600 = 1 hour
• Decimal hours (float): 1.5 = 1 hour 30 minutes
• HH:MM format (string): "01:30"

Timestamp formats (ISO 8601 standard):

• 2026-03-20T14:30:00Z (UTC)
• 2026-03-20T14:30:00-05:00 (with timezone)

Date-only:

• 2026-03-20 (YYYY-MM-DD)

Filtering & Pagination

Common query parameters:

GET /time-entries?
  user_id=123&
  start_date=2026-03-01&
  end_date=2026-03-31&
  project_id=456&
  page=1&
  per_page=100

Pagination patterns:

• Offset-based: page=2&per_page=50
• Cursor-based: cursor=abc123&limit=50
• Link headers with next/prev URLs

Rate Limiting

Common limits:

• 1000-5000 requests per hour
• 10-100 requests per minute
• Different limits for different endpoints

Headers:

• X-RateLimit-Limit: Total allowed
• X-RateLimit-Remaining: Requests left
• X-RateLimit-Reset: When limit resets (Unix timestamp)

Best practices:

• Implement exponential backoff on 429 errors
• Cache responses when possible
• Use webhooks instead of frequent polling
• Batch operations when supported

Error Handling

Standard HTTP status codes:

• 200: Success
• 201: Created
• 400: Bad request (validation error)
• 401: Unauthorized (invalid/missing auth)
• 403: Forbidden (insufficient permissions)
• 404: Not found
• 429: Too many requests (rate limit)
• 500: Server error

Error response format:

{
  "error": "validation_error",
  "message": "Start time must be before end time",
  "details": {
    "field": "start_time",
    "value": "2026-03-20T15:00:00Z"
  }
}

Reporting APIs

Common report endpoints:

• Summary reports (total hours by project, user, date range)
• Detailed reports (individual time entries with filters)
• Utilization reports (billable vs. non-billable)
• Budget reports (actual vs. planned hours)

Export formats:

• JSON (for programmatic use)
• CSV (for Excel/Google Sheets)
• PDF (for client-facing reports)
• Excel (XLSX files)

Real-Time Features

WebSockets

Use cases:

• Live team dashboard (who's working on what)
• Real-time timer updates
• Instant notification of approvals

Server-Sent Events (SSE)

Alternative to WebSockets:

• One-way server-to-client push
• Simpler than WebSockets
• Good for notifications

Popular Time Tracking APIs

Toggl Track API

• Well-documented REST API
• v9 (latest) uses modern patterns
• Extensive filtering and reporting
• Active community

Clockify API

• Free tier generous
• Similar to Toggl structure
• Good documentation
• Supports webhooks

Harvest API v2

• OAuth 2.0 required
• Comprehensive endpoints
• Strong invoicing integration
• Detailed expense tracking

Everhour API

• Focused on project management integration
• Real-time sync capabilities
• Task-level granularity

Developer Resources

Essential documentation:

• Authentication guide
• API reference (all endpoints)
• Rate limits and quotas
• Webhook events reference
• Sample code (SDKs)
• Postman collections
• Changelog for API updates

SDKs and libraries:

• Official SDKs (Python, JavaScript, Ruby, PHP)
• Community libraries
• CLI tools
• Zapier/Make.com connectors

Future Trends

• GraphQL adoption increasing
• Real-time collaboration features
• AI-powered automatic categorization APIs
• Blockchain for immutable time records
• Standardization efforts across vendors