Getting Started - HRMS Public API

Introduction

Welcome to the HRMS Public API! This gateway enables external systems to securely integrate with your organization's HR data and workflows.

The HRMS Public API serves as a secure data mapping center that exposes your organization's employee data, departmental information, leave records, and other HR-related information through standardized REST endpoints. It supports multiple integration methods including direct API calls, SCIM (System for Cross-domain Identity Management), and Webhooks.

This guide will help you set up application tokens and make your first API request in just a few minutes. Whether you're building a custom integration or connecting third-party HR tools, we've got you covered.

Prerequisites

Before you begin, ensure you have the following:

Active HRMS Account: Access to your organization's HRMS instance
Administrator or Integration Permission: Ability to manage application tokens and integrations
Basic REST API Knowledge: Familiarity with HTTP methods (GET, POST, PATCH, DELETE)
API Client Tools: Any of the following to test API endpoints:
- curl (command line)
- Postman or Insomnia (GUI clients)
- Your preferred programming language's HTTP library

Step 1 - Create an Application Token

Application tokens are used to authenticate your API requests securely. Each token can be scoped to specific permissions.

Creating Your Token

Log in to HRMS with your administrator account
Navigate to Company Settings → Integrations
Click the + Create Token button
Fill in the token details:
- Token Name: A descriptive name (e.g., "Payroll System Integration")
- Description: Purpose of the token (optional but recommended)
Select Required Scopes: Choose which API resources this token can access:
- users:read - Read user/employee data
- departments:read - Read department information
- positions:read - Read position/job titles
Click Generate and copy your token immediately

⚠️ Important: Your token is displayed only once. Store it securely in your environment variables or secret management system. If you lose it, you'll need to generate a new token.

Example Token Usage

Using the token in a request header:

curl -H "Authorization: Bearer YOUR_APPLICATION_TOKEN" \
  -H "X-Environment: staging" \
  https://dev.workbeats.app/api/v1/users

In JavaScript/Node.js:

const headers = {
  'Authorization': 'Bearer YOUR_APPLICATION_TOKEN',
  'Content-Type': 'application/json',
  'X-Environment': 'staging'
};

fetch('https://dev.workbeats.app/api/v1/users', { headers })
  .then(res => res.json())
  .then(data => console.log(data));

In Python:

import requests

headers = {
    'Authorization': 'Bearer YOUR_APPLICATION_TOKEN',
    'Content-Type': 'application/json',
    'X-Environment': 'staging'
}

response = requests.get(
    'https://dev.workbeats.app/api/v1/users',
    headers=headers
)
print(response.json())

Step 2 - Make Your First API Request

Let's make a simple request to fetch a list of all users in your organization.

Using curl

curl -X GET https://dev.workbeats.app/api/v1/users \
  -H "Authorization: Bearer YOUR_APPLICATION_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Environment: staging"

Using Postman

Create a new GET request
Enter URL: https://dev.workbeats.app/api/v1/users
Go to the Headers tab
Add header: Authorization: Bearer YOUR_APPLICATION_TOKEN
Add header: X-Environment: staging (or uat)
Click Send

Example Response

200 OK - Successful Response:

{
  "data": [
    {
      "id": "user_001",
      "type": "user",
      "attributes": {
        "staffId": "S0001",
        "email": "john.doe@company.com",
        "name": "John Doe",
        "preferred_name": "John",
        "phone": "+60123456789",
        "status": "active"
      }
    }
  ]
}

Fetching a Specific User

You can also fetch details of a specific user by ID:

curl -X GET https://dev.workbeats.app/api/v1/users/user_001 \
  -H "Authorization: Bearer YOUR_APPLICATION_TOKEN" \
  -H "X-Environment: staging"

Step 3 - Understand the API Structure

Base URL

All API endpoints are relative to the base URL:

https://dev.workbeats.app/api

Current API Version

We're currently on API version v1. All endpoints are prefixed with /v1.

Available Endpoints

Method	Endpoint	Description
`GET`	/v1/users	List all users
`GET`	/v1/users/{userId}	Get user details (includes department, position, work locations)
`GET`	/v1/departments	List all departments
`GET`	/v1/positions	List all positions/job titles

Request/Response Format

The API uses JSON for all request and response bodies.

Content-Type Header Required:

Content-Type: application/json

Required Headers

Every API request requires the following headers:

Authorization: Bearer YOUR_APPLICATION_TOKEN
X-Environment: staging

Header Details:

Authorization - Your application token for authentication
X-Environment - Target environment based on where your token was generated:
- staging - Use this if your application token was generated from emspaced.hd.mybrandname.co
- uat - Use this if your application token was generated from hrms.emspaced.com (Production)

Example with JavaScript:

const headers = {
  'Authorization': 'Bearer YOUR_APPLICATION_TOKEN',
  'Content-Type': 'application/json',
  'X-Environment': 'staging'  // or 'uat' if token from production
};

Step 4 - Handle Errors

The API returns standard HTTP status codes and detailed error messages. Here are the most common scenarios:

400 Bad Request

Cause: Malformed request or missing required parameters

Example Response:

{
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."]
  }
}

401 Unauthorized

Cause: Missing or invalid authentication token

Example Response:

{
  "message": "Unauthenticated"
}

Solution: Verify your token is correct and included in the Authorization header.

403 Forbidden

Cause: Token lacks required scopes for this endpoint

Example Response:

{
  "message": "Insufficient permissions for this resource"
}

Solution: Add the required scope to your application token in the Integrations settings.

404 Not Found

Cause: The requested resource doesn't exist

Example Response:

{
  "message": "Resource not found"
}

500 Internal Server Error

Cause: Server-side error (rare, but can happen)

Solution: Please contact support if errors persist.

Error Handling Best Practices

Always check the HTTP status code of responses
Parse error messages to understand what went wrong
Implement retry logic with exponential backoff for 5xx errors
Log errors for debugging and monitoring
Set request timeouts to prevent hanging connections

Next Steps

You've successfully made your first API request! Here's what you can explore next:

Full API Documentation

Explore the complete API documentation with interactive examples and detailed endpoint specifications.

📖 Full API Documentation

Getting Started with HRMS Public API

Introduction

Prerequisites

Step 1 - Create an Application Token

Creating Your Token

Example Token Usage

Step 2 - Make Your First API Request

Using curl

Using Postman

Example Response

Fetching a Specific User

Step 3 - Understand the API Structure

Base URL

Current API Version

Available Endpoints

Request/Response Format

Required Headers

Step 4 - Handle Errors

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Error Handling Best Practices

Next Steps

Full API Documentation