Docs API Reference Overview
v2.4.0

API Overview

The IRA FORCE REST API provides programmatic access to all workforce management features including employees, scheduling, attendance, incidents, and real-time communications.

Base URL

All API requests are made to the following base URL:

Environment Base URL
Production https://api.iraforce.cloud/v1
Staging https://api.staging.iraforce.cloud/v1
Development http://localhost:3000/v1

Authentication

The API supports multiple authentication methods depending on your use case:

🔑 API Keys

Best for server-to-server integrations. Include in the X-API-Key header.

curl -H "X-API-Key: ifk_live_xxxxxxxxxxxx" \
  https://api.iraforce.cloud/v1/employees

🎫 JWT Tokens

Best for user-facing applications. Include in the Authorization header.

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://api.iraforce.cloud/v1/me

🔐 OAuth 2.0

Best for third-party integrations. Standard OAuth 2.0 authorization code flow.

See Authentication for complete details.

Request Format

All requests must include the following headers:

Content-Type: application/json
Accept: application/json
X-API-Key: ifk_live_xxxxxxxxxxxx

Request Body

For POST, PUT, and PATCH requests, send data as JSON:

// Create a new employee
const response = await fetch('https://api.iraforce.cloud/v1/employees', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'ifk_live_xxxxxxxxxxxx'
  },
  body: JSON.stringify({
    first_name: 'John',
    last_name: 'Smith',
    email: 'john.smith@example.com',
    role: 'guard',
    site_id: 'site_abc123'
  })
});

Response Format

All responses are returned in JSON format with consistent structure:

Success Response

{
  "success": true,
  "data": {
    "id": "emp_xyz789",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "role": "guard",
    "site_id": "site_abc123",
    "created_at": "2026-01-04T10:30:00Z",
    "updated_at": "2026-01-04T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123xyz"
  }
}

List Response (Paginated)

{
  "success": true,
  "data": [
    { "id": "emp_001", "first_name": "John", ... },
    { "id": "emp_002", "first_name": "Jane", ... }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_prev": false
  },
  "meta": {
    "request_id": "req_def456uvw"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  },
  "meta": {
    "request_id": "req_ghi789rst"
  }
}

HTTP Methods

Method Description Idempotent
GET Retrieve a resource or list of resources ✅ Yes
POST Create a new resource ❌ No
PUT Replace an entire resource ✅ Yes
PATCH Partially update a resource ❌ No
DELETE Remove a resource ✅ Yes

API Endpoints

The API is organized around the following resource groups:

👥 Employees

GET /employees List all employees
POST /employees Create an employee
GET /employees/{id} Get an employee
PATCH /employees/{id} Update an employee
View full documentation →

📅 Scheduling

GET /shifts List shifts
POST /shifts Create a shift
POST /shifts/{id}/assign Assign employee to shift
POST /shifts/{id}/swap Request shift swap
View full documentation →

⏱️ Attendance

POST /attendance/clock-in Clock in
POST /attendance/clock-out Clock out
GET /timesheets List timesheets
POST /timesheets/{id}/approve Approve timesheet
View full documentation →

🚨 Incidents

GET /incidents List incidents
POST /incidents Create an incident
POST /incidents/{id}/escalate Escalate incident
View full documentation →

Pagination

List endpoints support cursor-based pagination for consistent results:

# First page
GET /v1/employees?per_page=25

# Next page
GET /v1/employees?per_page=25&cursor=eyJpZCI6ImVtcF8wMjUifQ==

Query Parameters

Parameter Type Default Description
per_page integer 25 Number of records per page (max: 100)
cursor string - Cursor for next page (from previous response)
sort string created_at Field to sort by
order string desc Sort order (asc or desc)

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

Plan Requests/Minute Requests/Day
Basic 60 10,000
Advanced 300 100,000
Enterprise 1,000 Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1704371460

Error Codes

The API uses standard HTTP status codes and custom error codes:

HTTP Status Error Code Description
400 VALIDATION_ERROR Invalid request parameters
401 UNAUTHORIZED Missing or invalid authentication
403 FORBIDDEN Insufficient permissions
404 NOT_FOUND Resource not found
429 RATE_LIMITED Too many requests
500 INTERNAL_ERROR Server error (contact support)

SDKs & Libraries

Official client libraries for popular languages:

📦 Node.js npm install @iraforce/sdk 🐍 Python pip install iraforce 🐹 Go go get github.com/iraforce/go 💎 Ruby gem install iraforce

Next Steps

Next Authentication → Interactive Swagger UI →
ESC