API Reference

The Hopshift employee REST API gives partner systems read access to employee records in your Hopshift group. For AI-assisted scheduling, approvals and payroll, use the MCP setup guide.

REST integrations use keys from Group Settings → API Keys. Personal AI connections use MCP connections and inherit the creator's current permissions. The authentication, rate limits and JSON response format below describe the REST API; MCP has its own connection settings and limits.

Group Settings → API Keys creates two types of key. Employee list keys (scope employees:read) read the employee endpoints described here. Data sync keys (scope sync:read) copy the group's employees, structure, attendance, leave, payroll and history into your own database through /api/v1/sync/; they must expire within a year and can be renewed. See the Data sync guide.

Base URL

All API endpoints are served from:

https://hopshift.app

Versioned endpoints live under the /api/v1/ prefix. Always use the versioned path: unversioned paths are internal and may change without notice.

https://hopshift.app/api/v1/employees

Authentication

The Hopshift API uses API keys for authentication. Keys are created in your Hopshift dashboard under Group Settings → API Keys and must be sent as a Bearer token on every request.

curl https://hopshift.app/api/v1/employees \
  -H "Authorization: Bearer hops_your_api_key_here"

Keys belong to a Group, with company access recorded at creation. Owner and whole-group Admin keys cover the whole group; company-scoped Admin keys remain limited to their creation-time company snapshot. See Authentication for details.

Versioning

The API is versioned with a /v1/ path prefix. Breaking changes will be introduced under a new version prefix (/v2/) and the old version will remain available with advance notice of deprecation.

Non-breaking additions (new optional fields, new endpoints) may be added to the current version at any time.

Rate Limiting

Employee list keys are subject to a rate limit of 200 requests per minute. When this limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. See Rate Limiting for implementation guidance. Data sync keys have their own limits.

Available Endpoints

Response Format

All responses are JSON. Successful responses follow this envelope:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "total_pages": 3
  }
}

Error responses always include an "error" string field:

{
  "error": "Unauthorized"
}

HTTP Status Codes