Employees API: Creating and Querying Employee Records

The /employees endpoint manages employee records - the central identity for tip recipients on the Aplauso platform.

Create an Employee

POST /v2/employees
Content-Type: application/json
Authorization: Bearer <idToken>

Request

{
  "propertyId": "prop456",
  "organizationId": "org789",
  "firstName": "Maria",
  "lastName": "Garcia",
  "email": "maria@hotel.com",
  "phone": "+13125551234",
  "position": "Housekeeper",
  "departmentId": "dept111",
  "outletId": "out222",
  "firebaseUid": "firebase-uid-string",
  "environment": "live"
}

Auto-Generated Fields

Field	Description
`shortCode`	6-character alphanumeric code derived from the employeeId; used in QR code URLs
`employmentInviteCode`	8-character invite code for onboarding (see Invite Codes)

Response

{
  "success": true,
  "employeeId": "emp_xxxxxxxxxxx",
  "shortCode": "MARIA1",
  "employee": { ... }
}

Look Up an Employee by Short Code

Short codes are embedded in QR code URLs (k.aplauso.io/{shortCode}). To resolve a short code to a full employee record:

GET /v2/employees?shortCode=MARIA1&environment=live

Response

{
  "employee": {
    "employeeId": "emp_xxxxxxxxxxx",
    "firstName": "Maria",
    "lastName": "Garcia",
    "shortCode": "MARIA1",
    "position": "Housekeeper",
    "propertyId": "prop456",
    "status": 10
  }
}

Get the Current User's Employee Record

GET /v2/employees?me=true&environment=live
Authorization: Bearer <idToken>

Returns the employee record linked to the authenticated user's Firebase UID. If the user has multiple employee records across properties, this returns the active one based on users.activeEmployeeId. Also sets activeEmployeeId on the user document on first call.

Query Employees

GET /v2/employees?propertyId=prop456&environment=live
Authorization: Bearer <idToken>

Query Parameters

Parameter	Description
`me=true`	Return current authenticated user's employee record
`propertyId`	All employees at a property
`departmentId`	Employees in a specific department
`employeeId`	Single employee by ID
`shortCode`	Single employee by QR short code
`environment`	`live` / `sandbox` / `demo`

Employee Status Codes

Status	Value	Meaning
Active	10	Employee is active and receiving tips
Inactive	20	Temporarily disabled
Deleted	30	Permanently removed

Linking Firebase Users to Employees

Pass firebaseUid when creating an employee to link it to an existing Firebase Auth user. If the employee was created before the user signed up, the link is created automatically when the user signs in for the first time and enters their invite code.

An employee without a firebaseUid is a placeholder invite record - it will appear in the Aplauso management dashboard but cannot log in or receive push notifications until a user accepts the invite.