Custom API Integrations

Learn how to integrate your own systems with the Shifts platform using our comprehensive REST API, authenticate securely with API tokens, and create custom integrations for your organization’s unique needs.

Overview

The Shifts platform provides a powerful REST API that enables you to build custom integrations with your existing systems. This article explains how to access the API, authenticate your requests, understand the available endpoints, and build reliable integrations that automate workflows between Shifts and your other business systems.

API Capabilities

The Shifts API allows you to programmatically:

• Retrieve and manage shift information
• Access employee data and schedules
• Track attendance records
• Process leave requests
• Generate forecasts and analyze demand signals
• Create and manage bulk operations
• Export and import data
• Receive real-time event notifications via webhooks

Getting Started with API Access

Creating API Tokens

To use the API, you need to create an authentication token:

1. Navigate to Admin Settings > API Tokens
2. Click Create New Token
3. Enter a descriptive name for the token (e.g., “Payroll Integration”)
4. Select the permissions needed for your integration
5. Optionally set an expiration date for enhanced security
6. Click Generate Token
7. Important: Copy and securely store the generated token immediately; it will only be displayed once

API Rate Limits

The Shifts API employs rate limiting to ensure system stability:

• Standard limit: 1,000 requests per hour per token
• Burst limit: 100 requests per minute per token
• Rate limit headers are included in all responses
• Exceeding limits results in 429 (Too Many Requests) responses

API Authentication

All API requests require authentication using your API token:

Authorization: Bearer YOUR_API_TOKEN

Example using curl:

curl -X GET "https://yoursubdomain.shifts.com/api/v1/shifts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Key API Endpoints

The Shifts API includes the following primary endpoints:

Shifts Management

• GET /api/v1/shifts - List shifts
• POST /api/v1/shifts - Create a new shift
• GET /api/v1/shifts/{id} - Get shift details
• PUT /api/v1/shifts/{id} - Update a shift
• DELETE /api/v1/shifts/{id} - Delete a shift

Employee Data

• GET /api/v1/employees - List employees
• GET /api/v1/employees/{id} - Get employee details
• GET /api/v1/employees/{id}/schedule - Get employee schedule

Attendance Management

• GET /api/v1/attendance_records - List attendance records
• POST /api/v1/attendance_records - Create an attendance record
• GET /api/v1/attendance_records/{id} - Get attendance details
• PUT /api/v1/attendance_records/{id} - Update an attendance record

Leave Management

• GET /api/v1/leave_requests - List leave requests
• POST /api/v1/leave_requests - Submit a leave request
• GET /api/v1/leave_requests/{id} - Get leave request details
• PUT /api/v1/leave_requests/{id} - Update a leave request status

Bulk Operations

• POST /api/v1/bulk_operations - Create a bulk operation
• GET /api/v1/bulk_operations/{id} - Check operation status

Forecasting

• GET /api/v1/forecasts - List forecasts
• POST /api/v1/forecasts - Create a forecast
• GET /api/v1/demand_signals - Get demand signals

Exports

• POST /api/v1/export_files - Request a data export
• GET /api/v1/export_files/{id} - Get export file status
• GET /api/v1/export_files/{id}/download - Download an export file

Webhook Integration

For real-time event notifications, you can set up webhooks:

1. Go to Admin Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter the URL where you want to receive webhook events
4. Select the events you’re interested in:
   • shift.created, shift.updated, shift.cancelled
   • shift_assignment.created, shift_assignment.updated
   • attendance.check_in, attendance.check_out, attendance.missed
   • leave_request.created, leave_request.approved, leave_request.rejected
5. The system generates a secret key for secure verification
6. Use this key to validate incoming webhook payloads

Webhook Payload Verification

For security, always verify webhook payloads:

1. Each webhook request includes an X-Webhook-Signature header
2. Calculate HMAC-SHA256 of the payload using your secret key
3. Compare your calculation with the signature header
4. Only process the webhook if signatures match

// Example code for verifying webhook signatures (Node.js)
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = 'sha256=' + hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(calculatedSignature)
  );
}

Common API Integration Scenarios

HRIS Integration

Synchronize employee data between your HRIS system and Shifts:

1. Create a scheduled job that pulls employee data from your HRIS
2. Map HRIS fields to Shifts API fields
3. Use the Shifts API to create or update employee records
4. Set up webhooks to receive notifications of employee updates in Shifts

Payroll Integration

Automatically send timesheet data to your payroll system:

1. Create a scheduled job that runs before each pay period
2. Use the Shifts API to retrieve attendance records for the period
3. Calculate hours worked, including regular and overtime
4. Format and send the data to your payroll system’s API

Business Intelligence Integration

Feed workforce data into your BI tools:

1. Use the Shifts API to export shift, attendance, and cost data
2. Transform the data to match your data warehouse schema
3. Import the data into your BI platform
4. Create dashboards that combine Shifts data with other business metrics

Best Practices

For reliable API integration:

1. Use Webhooks for Real-Time Updates: Instead of frequent polling
2. Implement Proper Error Handling: Account for API rate limits and server errors
3. Cache Data When Appropriate: Reduce API calls for frequently accessed data
4. Use Bulk Endpoints: For operations involving multiple records
5. Handle Pagination: Many endpoints return paginated results
6. Keep Tokens Secure: Store API tokens in secure environment variables, not in code
7. Monitor API Usage: Track rate limits and integration performance
8. Test in Sandbox First: Verify integrations in a test environment before production

Troubleshooting

Common API issues and solutions:

• 401 Unauthorized: Check API token validity and permissions
• 403 Forbidden: Verify the token has appropriate permissions
• 429 Too Many Requests: Implement exponential backoff and respect rate limits
• 500 Server Error: Contact support with the request details and response error
• Webhook delivery failures: Ensure your endpoint is consistently available and responds quickly

API Documentation

For complete API documentation:

1. Visit https://yoursubdomain.shifts.com/api/documentation
2. Browse interactive documentation with all endpoints and parameters
3. Test API calls directly from the documentation interface
4. View example requests and responses for each endpoint

Related Resources

• HRIS Integration
• Webhook Notifications
• API Authentication

This article should be updated when:

1. New API endpoints are added
2. Authentication methods change
3. Rate limits are adjusted
4. Webhook event types are modified
5. New integration capabilities are introduced