POSVelo
POSVeloDocs

HRM Quickstart Tutorial

From zero to your first payslip — one connected, copy-paste walkthrough

What you'll build in ~15 minutes

By the end you'll have a real department, a job title, an employee who can log in, a shift on the roster, a leave type, an approved leave request, a salary structure, and a finalized payslip the employee can download from their self-service portal — plus a live notification along the way. Every request below is taken from the shipped Postman collection.

Before You Start

You needDetails
A running backendDefault http://localhost:5000. See Running the Project.
The HR module enabledFor your tenant — see What's New in v2. Otherwise every /hr call returns MODULE_DISABLED.
An admin loginAn ADMIN (or HR_MANAGER) account to run the setup steps.
Postman or curlEither works. The Postman collection auto-saves IDs (department_id, employee_id, …) so requests chain themselves.

Step 0 — Log In & Get a Token

Everything except login needs a Bearer token. Log in once and reuse the accessToken.

bash
json
Set it once

In the shell, export it so the next commands stay short. In Postman, the Login request's test script already stores access_token for you.

bash

Step 1 — Create a Department

bash
json

Keep the returned id — call it department_id.

Step 2 — Create a Designation (Job Title)

bash

Save the returned id as designation_id.

Step 3 — Create an Employee (with a login)

This creates the person and a login account in one call, so they can use self-service later. Replace the {{...}} placeholders with the IDs from above.

bash
What just happened

An Employee row was created and linked to a new User with the EMPLOYEE role. John can now log in and reach the ESS portal at /me. Save the returned employee id as employee_id.

Step 4 — Put a Shift on the Roster

First create a reusable shift template:

bash

Save the template id as shift_template_id, then roster two days (a working day and an off-day):

bash
json

Step 5 — Set Up Leave & Approve a Request

Create a leave type, then have the employee apply, then approve it as the manager.

1

Create a leave type

bash

Save the id as leave_type_id.

2

Apply for leave (as the employee)

Logged in as John, the ESS form calls:

bash

The balance is reserved and every approver gets a live notification. Save the request id as leave_request_id.

3

Approve it (as admin/manager)

bash

The reserved days convert to used, John is notified, and the "New leave request" badge clears for the other approvers automatically.

Step 6 — Pay the Employee

Build a salary structure, assign John a salary, then run payroll.

1

Create a salary structure

bash

Save the id as salary_structure_id. Optionally POST .../salary-structures/{{salary_structure_id}}/apply-preset with { "countryCode": "BD" } to add standard components.

2

Assign a salary to John

bash
3

Create, process, approve, disburse the run

bash
Separation of duties

The person who approves a run must not be the one who processed it — in a real setup, use two accounts (e.g. an ACCOUNTANT processes, an ADMIN approves). For this tutorial on a fresh install you may need a second admin user.

Step 7 — See It From the Employee's Side

Log in as John and hit self-service — the same data, scoped to just him.

bash

In the browser, John sees all of this on the /me dashboard — payslips at /me/payslips, leave at /me/leave, roster at /me/shifts.

You're Done — The Whole Flow at a Glance

#You didEndpointDoc
1DepartmentPOST /api/v2/hr/departmentsEmployees
2DesignationPOST /api/v2/hr/designationsEmployees
3Employee + loginPOST /api/v2/hr/employeesEmployees
4Shift + rosterPOST /api/v2/hr/shifts/...Attendance & Shifts
5Leave + approvalPOST /api/v2/hr/leave/...Leave & Holidays
6Payroll run → payslipPOST /api/v2/hr/payroll/...Payroll
7Self-service viewGET /api/v2/me/...ESS
Where to go deeper

Each step has a full module guide linked above, and every endpoint (with permissions) is in the v2 API Reference. Curious who can call what? See Permissions & RBAC.