Developer Overview

Hopshift exposes a REST API that lets you read and write HR data programmatically. Whether you're syncing employees from an existing HRIS, pushing payroll results into an accounting system, or building a custom dashboard for your organisation, the API gives you secure, structured access to your Hopshift data.

Quickstart

1. Create an API Key

API keys are scoped to a Group: they provide access to all companies within that group.

1. Log in to Hopshift as a Group Admin.
2. Navigate to Group Settings → API Keys.
3. Click Create API Key, give it a descriptive name (e.g. payroll-sync-prod), and copy the key immediately: it is only shown once.

Keep your API key secret. Do not commit it to source control.

2. Make Your First Request

All API requests require the Authorization header with your key:

curl https://hopshift.nottoosweetlabs.com/api/v1/employees \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response returns a paginated JSON array of employees across all companies in your group:

{
  "data": [
    {
      "id": "emp_01j...",
      "firstName": "Somchai",
      "lastName": "Jaidee",
      "email": "somchai@example.com",
      "companyId": "cmp_01j...",
      "status": "ACTIVE"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 120
  }
}

3. Explore the API Reference

The full list of endpoints, parameters, and response schemas is in the API Reference.

Integration Use Cases

HR System Sync

If your organisation manages employee records in a separate HRIS or ERP, use the Hopshift API to keep both systems in sync. Common patterns:

• Nightly employee sync: pull the Hopshift /employees endpoint and reconcile with your master HR database.
• Offboarding automation: when an employee is terminated in your HRIS, call the Hopshift API to update their status immediately.
• Org chart export: pull the reporting hierarchy from Hopshift to feed into org visualisation tools.

Payroll Software Integration

Hopshift finalises payroll and generates compliance documents, but some organisations want to push the final payroll data into a dedicated accounting or payroll ledger:

• Pull completed payroll runs via /payroll/runs after finalisation.
• Retrieve individual employee pay items (gross, tax withheld, SSO deductions, net pay) for each run.
• Map Hopshift payroll line items to your chart of accounts and POST journal entries to your accounting system.

Partner Applications

If you're building a workforce management or benefits tool that needs scheduling or leave data from Hopshift:

• Read employee shift assignments to power your own scheduling views.
• Sync leave balances so employees see consistent entitlements across both platforms.
• Post leave requests back to Hopshift on behalf of employees via the API.

Internal Dashboards & Reporting

Build custom reports that combine Hopshift data with other internal data sources:

• Headcount and turnover analytics
• Labour cost dashboards by company or department
• Attendance and punctuality metrics

Authentication Summary

• All API requests use Bearer token authentication via the Authorization header.
• Tokens are group-scoped: one key grants access to all companies in the group.
• Keys do not expire automatically but can be revoked at any time from Group Settings.
• See Architecture for the full auth model.

Rate Limits

The API enforces a default rate limit of 200 requests per minute per API key. If you exceed this, you'll receive a 429 Too Many Requests response with a Retry-After header. For higher limits, contact support.