Guide: integrating the Orkelis public API

The Orkelis public API allows you to integrate your schedules, absences, users, and clockings with your existing tools: HRIS, ERP, payroll software, Business Intelligence tools, business applications, etc. The API follows REST principles and uses API key authentication. This guide covers key generation, authentication, all available endpoints, pagination, webhooks, and security best practices.

Prerequisites

• A Pro or Enterprise plan (the public API is not available on the Essential plan).
• An administrator account to generate API keys.
• Basic programming and HTTP/REST knowledge.
• A tool for testing requests: curl, Postman, Insomnia, or a programming language (Python, JavaScript, PHP, etc.).

1. Generate an API key

API keys are the authentication mechanism for the public API. Each key is associated with specific permissions (scopes) and can have an expiration date.

1. Log in as an administrator.
2. Go to API Keys (/dashboard/api-keys) from the sidebar.
3. Click Generate an API key.
4. Fill in the key information:

• Name: a descriptive name to identify the key's usage (e.g., "Sage Payroll Integration", "HRIS Sync", "BI Dashboard").
• Scopes: permissions granted to this key (see the Scopes section below).
• Expiration date: optional, but strongly recommended for temporary integrations.

1. Click Create.
2. The API key is displayed only once. Copy it immediately and store it securely.

Critical security: the API key is displayed once and only once upon creation. If you lose it, you will need to generate a new one. Store it in a secrets manager (Vault, AWS Secrets Manager, Infisical, etc.). Never commit it to a git repository and never transmit it via unencrypted email.

Available scopes

Scopes control each API key's permissions. Only assign the scopes needed for each integration (principle of least privilege):

• read:users — Read users: list, search, and view employee profiles.
• write:users — Write users: create, modify, and deactivate employees.
• read:plannings — Read schedules: view schedules, assignments, and slots.
• write:plannings — Write schedules: create and modify assignments.
• read:absences — Read absences: view absences and leave requests.
• write:absences — Write absences: create, modify, and cancel absences.
• read:time-entries — Read clockings: view time entries and timesheets.

2. Authentication

All requests to the public API must include the X-API-Key HTTP header with your key. The API returns a 401 Unauthorized error if the key is missing, invalid, or expired.

Authentication example

curl -H "X-API-Key: sk_live_your_api_key" \
  https://orkelis.app/api/v1/public/users

Request format

The API accepts and returns JSON. Include the Content-Type: application/json header for POST, PATCH, and PUT requests.

curl -X POST \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  https://orkelis.app/api/v1/public/endpoint

HTTP response codes

• 200 OK: request processed successfully.
• 201 Created: resource created successfully.
• 400 Bad Request: invalid data (check the request body).
• 401 Unauthorized: API key missing or invalid.
• 403 Forbidden: insufficient scope for this operation.
• 404 Not Found: resource does not exist.
• 422 Unprocessable Entity: valid but unprocessable data (e.g., date conflict).
• 429 Too Many Requests: rate limit reached (see the Rate Limiting section).
• 500 Internal Server Error: internal error (contact support).

3. Available endpoints

Users

User endpoints allow managing your employee profiles via the API.

• GET /api/v1/public/users — List users (paginated) — scope: read:users
• GET /api/v1/public/users/:id — User detail — scope: read:users
• POST /api/v1/public/users — Create a user — scope: write:users
• PATCH /api/v1/public/users/:id — Update a user — scope: write:users
• DELETE /api/v1/public/users/:id — Deactivate a user — scope: write:users

User structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "Marie",
  "lastName": "Dupont",
  "email": "[email protected]",
  "role": "AGENT",
  "contractHours": 35,
  "specialty": "RN",
  "status": "ACTIVE",
  "services": ["service-uuid-1"],
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-10T14:20:00Z"
}

Schedules

• GET /api/v1/public/plannings — List schedules (filter by dates, service) — scope: read:plannings
• GET /api/v1/public/plannings/:id — Assignment detail — scope: read:plannings
• POST /api/v1/public/plannings — Create an assignment — scope: write:plannings
• PATCH /api/v1/public/plannings/:id — Update an assignment — scope: write:plannings
• DELETE /api/v1/public/plannings/:id — Delete an assignment — scope: write:plannings

Schedule filtering parameters

• startDate (required): start date in YYYY-MM-DD format.
• endDate (required): end date in YYYY-MM-DD format.
• serviceId: filter by service identifier.
• userId: filter by employee identifier.
• shiftType: filter by shift type (MORNING, AFTERNOON, NIGHT, etc.).

Absences

• GET /api/v1/public/absences — List absences (filter by dates, employee, type) — scope: read:absences
• GET /api/v1/public/absences/:id — Absence detail — scope: read:absences
• POST /api/v1/public/absences — Create an absence — scope: write:absences
• PATCH /api/v1/public/absences/:id — Update an absence — scope: write:absences
• DELETE /api/v1/public/absences/:id — Cancel an absence — scope: write:absences

Absence types

The type field accepts the following values:

• CONGE_PAYE — Paid leave.
• CONGE_SANS_SOLDE — Unpaid leave.
• MALADIE — Sick leave.
• FORMATION — Training day.
• ECHANGE — Shift swap between employees.

Clockings

• GET /api/v1/public/time-entries — List clockings (filter by dates, employee, method) — scope: read:time-entries
• GET /api/v1/public/time-entries/:id — Clocking detail — scope: read:time-entries

Clocking filtering parameters

• startDate (required): start date in YYYY-MM-DD format.
• endDate (required): end date in YYYY-MM-DD format.
• userId: filter by employee identifier.
• method: filter by clocking method (KIOSK, MOBILE, MANUAL).

4. Pagination

All lists returned by the API are paginated. The API supports two pagination modes:

Page-based pagination (offset)

Classic page number pagination, suited for user interfaces:

GET /api/v1/public/users?page=2&limit=50

• page: page number, starting from 1 (default: 1).
• limit: items per page (default: 20, minimum: 1, maximum: 100).

Cursor-based pagination

Cursor pagination is recommended for sync operations and large data volumes. It is more performant and consistent when concurrent modifications occur:

GET /api/v1/public/users?cursor=eyJpZCI6IjEyMyJ9&limit=50

When the cursor parameter is provided, the page parameter is ignored. Use the nextCursor field in the response to traverse subsequent pages. When nextCursor is null, you have reached the last page.

Paginated response format

{
  "data": [
    { "id": "uuid-1", "firstName": "Marie", "lastName": "Dupont", "..." : "..." },
    { "id": "uuid-2", "firstName": "Paul", "lastName": "Martin", "..." : "..." }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "nextCursor": "eyJpZCI6InV1aWQtMiJ9",
    "hasMore": true
  }
}

5. Rate Limiting

The API enforces rate limits to ensure service stability:

• Pro plan: 100 requests per minute per API key.
• Enterprise plan: 1,000 requests per minute per API key.
• Response headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711234567

If you exceed the limit, the API returns a 429 Too Many Requests error. Wait the number of seconds indicated in the Retry-After header before retrying.

Best practice: implement an exponential backoff mechanism in your integrations. On a 429 error, wait 1 second, then 2, then 4, etc., before each new attempt.

6. Practical examples

Retrieve all active employees

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/users?limit=100&status=ACTIVE"

Retrieve the week's schedules

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/plannings?startDate=2026-03-16&endDate=2026-03-22"

Retrieve schedules for a specific service

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/plannings?startDate=2026-03-16&endDate=2026-03-22&serviceId=service-uuid"

Create a user

curl -X POST \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Sophie",
    "lastName": "Bernard",
    "email": "[email protected]",
    "role": "AGENT",
    "contractHours": 35,
    "specialty": "NA",
    "services": ["service-uuid-1"]
  }' \
  "https://orkelis.app/api/v1/public/users"

Create an absence

curl -X POST \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "startDate": "2026-03-20",
    "endDate": "2026-03-22",
    "type": "CONGE_PAYE",
    "reason": "Family vacation"
  }' \
  "https://orkelis.app/api/v1/public/absences"

Retrieve the month's clockings

curl -H "X-API-Key: sk_live_xxxxx" \
  "https://orkelis.app/api/v1/public/time-entries?startDate=2026-03-01&endDate=2026-03-31"

Cursor pagination (full loop)

#!/bin/bash
# Sync all users with cursor pagination
BASE_URL="https://orkelis.app/api/v1/public/users"
API_KEY="sk_live_xxxxx"
CURSOR=""

while true; do
  if [ -z "$CURSOR" ]; then
    RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" "$BASE_URL?limit=100")
  else
    RESPONSE=$(curl -s -H "X-API-Key: $API_KEY" "$BASE_URL?limit=100&cursor=$CURSOR")
  fi

  # Process data
  echo "$RESPONSE" | jq '.data[] | .firstName + " " + .lastName'

  # Get next cursor
  CURSOR=$(echo "$RESPONSE" | jq -r '.meta.nextCursor')
  HAS_MORE=$(echo "$RESPONSE" | jq -r '.meta.hasMore')

  if [ "$HAS_MORE" != "true" ]; then
    break
  fi
done

7. Webhooks

To receive real-time notifications when events occur in Orkelis, configure webhooks. Webhooks send HTTP POST requests to the URL of your choice.

Configure a webhook

1. Go to Webhooks (/dashboard/webhooks) in the sidebar.
2. Click Add a webhook.
3. Enter the target URL (e.g., https://your-server.com/webhooks/orkelis).
4. Select the events to listen for:

• planning.published — A schedule has been published.
• planning.updated — A schedule has been updated.
• absence.created — An absence has been created.
• absence.approved — An absence has been approved.
• absence.rejected — An absence has been rejected.
• user.created — A user has been created.
• user.updated — A user has been updated.
• time-entry.created — A clocking has been recorded.

1. Optional: add a secret to verify webhook signatures.
2. Click Save.

Webhook payload format

{
  "event": "absence.approved",
  "timestamp": "2026-03-17T10:30:00Z",
  "data": {
    "id": "absence-uuid",
    "userId": "user-uuid",
    "type": "CONGE_PAYE",
    "startDate": "2026-03-20",
    "endDate": "2026-03-22",
    "status": "APPROVED"
  }
}

Signature verification

If you configured a secret, each webhook request includes an X-Webhook-Signature header containing an HMAC SHA-256 of the request body. Verify this signature in your server to ensure the webhook comes from Orkelis.

# Python verification
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

8. API key management

Rigorous management of your API keys is essential for data security.

• Rotation: regenerate a key without deleting it via the Rotate button on the API Keys page. The old key is immediately invalidated and replaced with a new one. Update your integration immediately.
• Revocation: delete a compromised key via the Delete button. All requests using this key will receive a 401 error.
• Usage logs: view each key's usage history in the Logs tab: number of requests, dates, endpoints called, response codes, source IP addresses.
• Expiration: set an expiration date for temporary keys. Orkelis sends a reminder email 7 days before expiration.

Principle of least privilege: create one API key per integration with only the necessary scopes. For example, a payroll integration only needs read:time-entries and read:users. This limits the impact in case of compromise.

9. Integration best practices

• Use cursor pagination for bulk sync operations: it is more performant and consistent than page-based pagination.
• Implement exponential backoff on 429 or 5xx errors.
• Store API keys in a secrets manager (never hardcoded).
• Verify webhook signatures to prevent injection attacks.
• Log all API errors on your side to facilitate troubleshooting.
• Test your integrations in a staging environment before production.
• Monitor your key consumption via the Logs tab on the API Keys page.

10. Troubleshooting

• 401 Unauthorized error: the API key is missing, invalid, or expired. Check the X-API-Key header and your key's validity.
• 403 Forbidden error: the key doesn't have the required scope for this operation. Check the scopes assigned to your key on the API Keys page.
• 404 Not Found error: the requested resource doesn't exist. Check the UUID used in the URL.
• 422 Unprocessable Entity error: data is valid but inconsistent (e.g., end date before start date, nonexistent employee). Check the errors field in the response for details.
• 429 Too Many Requests error: you have exceeded the rate limit. Wait the time indicated in the Retry-After header.
• Webhook not received: verify your URL is publicly accessible (not localhost). Check delivery logs in Webhooks > Logs to see attempts and your server's response codes.
• Missing data in response: some fields are only returned if you have the corresponding scope. Check your permissions.

API technical support: for any questions about the public API, contact our technical team at [email protected] or consult the interactive documentation (Swagger) at orkelis.app/api/docs.