New Employee Provisioning

Updated March 13, 2026 14:34

Introduction

The provisioning of new employees requires a well defined business process. You'll want to conduct your own analysis, but the most common flow that we've observed are either a manual approach based on an API integration, or an SSO/SCIM assisted one that automates the creation and updating of employee records in the TrackTik platform. We'll examine both.

Overview - Manual API Approach

Details about the new employee are obtained from a source, like an HR system.
These source details used to CREATE a new employee record via the TrackTik API or manually within the Guarding Suite web application are generally the same and will involve a unique identifier of some kind, like a username and/or email address.

While creating the employee, you can add additional JSON objects to the payload like address and employmentProfile information (class of employee, pay rate, ideal total work hours per week to reach, overtime rule etc.)

Your data payload to send to TrackTik may contain a temporary password that you generate in your integration software as well. POST to /employees .
All TrackTik platform employees need to be assigned a Role. These Roles are typically defined via the Guarding Suite web application, although they can be created via API. Each Role has its own "id" unique identifier, and this needs to be known to assign an employee to that Role. The IDs of Roles will be obtained via a GET from the /roles endpoint. If you need to create a new Role, this can be done via a POST to /roles.
The employee is assigned their Role via the Guarding Suite app, or via API using the Employee's "id" value, and the Role's "id" value: POST to /user-roles.
If the Employee is assigned to an existing Role, that Role will already have permissions set for what it can and can't do in the TrackTik ecosystem (like viewing reports for the client site they are assigned to). If your integration is creating Roles, then it must also create Role Permissions for the role via the /role-permissions endpoint. This is not easy to do on your own because of how much configuration knowledge is required for the many functions of TrackTik's Software. You'll need to work with an Administrator of your target TrackTik web portal. For a deeper dive, a TrackTik Solution Engineer from Professional Services can help you complete a more in-depth Business Analysis and mapping exercise.
Circling back to temporary passwords: With a base record created, an ID number (the employees.id value, which differs from the employees.customId value) will be returned. If the Business Process's privacy policy requires that the Employee changes the password to a different one that only they know, then an action is executed via API that will force a prompt for the Employee to change their password after their first successful login on either the Guarding Suite web application, or Guard Tour mobile application: POST /employees/{id}/actions/force-password-change.

If employees, including new hires or terminated staff, encounter issues such as a lack of profile visibility or unauthorized access, ensure they are correctly added or removed from employee lists. Employee profiles missing from TrackTik after being inputted into Paycor may require syncing. For non-employee roles, the client portal access feature is recommended.

If a license was added but you have no login details, it likely means the employee profile hasn’t been created. Follow these steps:

Create the Employee profile and include the basics: name, email (for login), region and site assignments, and Role.
Assign a device or on-site license if the Employee will use the Guard Tour mobile application.
Generate credentials by either setting a temporary password yourself or sending an invite email if your portal supports it.
Provide onboarding instructions: how to log in (URL or app), username, temporary password, and any MFA requirements.
Confirm first login and enforce a password change.

Troubleshooting — Time Clock Visibility and Punching

If a new employee can’t punch in or isn’t visible on a biometric/time clock, review the following in order:

Employee profile and status
- Confirm the employee profile is created, Active, and has a correct Start Date.
- Ensure the employee has the correct role and is assigned to the correct branch/site.
Device assignment and sync
- Make sure the employee is included in the device’s allowed employee list or group for the site.
- Push/sync employees to the clock from your portal if required by your setup.
- Confirm the clock is online and has synced recently.
Enrollment and identifiers
- Enroll the employee’s biometric template (fingerprint/face) or badge/card per your device’s process.
- Verify the TrackTik Employee ID is set and communicated (this is the ID they’ll use for punching, not an external payroll ID).
Permissions and restrictions
- Confirm mobile app/time clock login is permitted by your Settings (Mobile App Login Restrictions, if applicable).
- Ensure the employee’s role allows punch actions.
Scheduling/assignment checks
- If your configuration requires a schedule for punching, ensure the employee is on the live schedule at the correct site.

Temporary workarounds while resolving provisioning:

A supervisor can enter a manual punch/time entry in the employee’s timesheet if permitted by policy.
If allowed at your company, the employee may clock via the mobile app using their TrackTik Employee ID and credentials.

If issues remain, share with your admin or Support:

Employee name and Employee ID
Clock serial/name and site
What has been synced/enrolled so far
Screenshots of the employee profile and device assignment

Ending Access for Departing Employees

When an employee leaves or must be blocked immediately, end access in both the licensing and account layers. Removing a device license alone will not end an active session.

Terminate the device license: remove the device license assigned to the user to prevent new sessions.
Force a logout: if the Guarding Suite web application or Guard Tour mobile application is still running, the user may remain in an active session. You can:
- Change their password and notify them.
- Revoke tokens/sessions if your portal supports it.
- Ask them to log out manually; instruct them to fully close the app and reopen to trigger login.
Deactivate or terminate the employee profile: set the employee status to inactive/terminated so they cannot log in, even if a license is re-assigned.
Verify: attempt a login with the user's credentials (or ask them to confirm) to ensure access is denied.

Tip: Removing a device license alone doesn't immediately kill an active session. Always combine license termination with account deactivation or a forced logout.

Overview - SSO/SCIM Automated Approach

If your organization is using an Identity Provider (IDP) with Single Sign-One (SSO) capabilities and features System for Cross-Domain Identity Management (SCIM), then most of the engineering efforts from the above described process won't be necessary as the IDP with SCIM capabilities will be able to integrate itself into the TrackTik ecosystem and push/sync new Employee data, and sync its Grouping solution as Roles on its own, and will handle the authentication and authorizations.

The process of integration is therefore as follows:

For steps 2 and 3 below, the best practice is to configure both SSO and SCIM within the Identity Provider together as one application, with one Application identifier.
The SSO feature of TrackTik's software must be enabled and configured with an exchange of details about the TrackTik system for the IDP administrator (OpenID Path) and from the IDP which will need a dedicated Application creation (if one doesn't exist already) (Client ID, Client Secret and Discovery URL). A decision must also be made about what the employee's unique identifier will be, username or email address.
The SCIM feature of TrackTik's software must also be enabled, along with an Administrator Role assigned and SCIM dedicated Employee entity account. The Administrator SCIM dedicated Employee record's username and password will be provided, along with an OAuth 2 Client Record's Client ID and Client Secret. Lastly, TrackTik will provide an API endpoint address for you to request an expiring access token for yourself, which will have an expiry value as a count of days that you will define yourself.
The Identity Provider configures Groups (TrackTik roles) if necessary and assigns employees to them. A business process is defined to assign groups to new users created in the system.
Details about the new employee are obtained from a source, like an HR system.
These source details used to CREATE a new employee record via the SSO+SCIM IDP involve a unique identifier of some kind, like a username and/or email address.
The source details may or may not include a temporary password.
If a temporary password is not available, the integration will need to generate one within the SSO+SCIM IDP layer and communicate it to the new employee.

For more information on our SSO+SCIM solutions, see "Set up Azure single sign-on (SSO) for TrackTik" and "Set up and use provisioning for Azure".

Detailed - Manual API Approach

Create the Employee

Create a New Employee (with temporary password), and take note of the "id" value assigned in the response for next steps:

E.g. 1 - Basic + Address

POST /employees

{
    "region": 2,
    "customId": "C123-A - JS",
    "firstName": "John",
    "middleName": "string",
    "lastName": "Smith",
    "primaryPhone": "555-555-1234",
    "secondaryPhone": "555-555-4321",
    "username": "johnsmith23",
    "password": "YCpE#f9^8L8az",
    "email": "john.smith23@myemail.com",
    "jobTitle": "Assistant",
    "gender": "M",
    "birthday": "1980-08-24",
    "address": {
            "addressLine1": "111 Street Ave",
            "addressLine2": "",
            "city": "Dorval",
            "country": "CA",
            "state": "QC",
            "postalCode": "H9P 1G2",
            "latitude": 45.488805,
            "longitude": -73.5859921
        },
    "language": "EN_US",
    "fax": "000-000-0000",
    "tags": 
    [
        "string1","string2","string3"
    ]
}

E.g. 2 - Basic + Address + Employment Profile

POST /employees

  {
    "region": 2,
    "customId": "C123-A - JS",
    "firstName": "John",
    "middleName": "string",
    "lastName": "Smith",
    "primaryPhone": "555-555-1234",
    "secondaryPhone": "555-555-4321",
    "username": "johnsmith23",
    "password": "YCpE#f9^8L8az",
    "email": "john.smith23@myemail.com",
    "jobTitle": "Assistant",
    "gender": "M",
    "birthday": "1980-08-24",
    "address": {
            "addressLine1": "111 Street Ave",
            "addressLine2": "",
            "city": "Dorval",
            "country": "CA",
            "state": "QC",
            "postalCode": "H9P 1G2",
            "latitude": 45.488805,
            "longitude": -73.5859921
        },
    "language": "EN_US",
    "fax": "000-000-0000",
    "employmentProfile": {
            "employeeType": "EMPLOYEE",
            "employmentDate": "2025-08-14T00:00:00+00:00",
            "payRateType": "HOURLY",
            "hourlyRateType": "EMPLOYEE_SPECIFIC",
            "hourlyRate": 48,
            "overtimeExempt": false,
            "weeklyHoursTarget": 40,
            "weeklyHoursMaximum": 0,
            "weeklyHoursMinimum": 0
        },
    "tags": 
    [
        "string1","string2","string3"
    ]
}

There are more fields available for the employmentProfile object, so consult with our /rest/v1 documentation to learn more about those.

On Passwords

While the password complexity validation can be configured in the web application by an administrator (not accessible via API), there are basic minimums and you'll be reminded of them if you don't meed the requirements:

Multi-Factor Authentication (MFA)

MFA is typically administered by your IT team. General process:

IT enables MFA on the account.
You receive setup instructions (email or in-portal prompt).
On first login after activation, register an authenticator (e.g., Authenticator app or SMS).
Save backup codes in a secure place.
Verify MFA by logging in once more and completing the second factor.

For issues (new device, lost codes), contact IT to reset MFA.

Assign a Role (existing)

If you don't already know the id value of the role you'd like to assign to the employee, you can peruse the current roles with GET /roles . Once you find the id, you need to create a join record between the employee.id value and the role.id value via /user-roles:

POST /user-roles

{
  "user" : 1525,
  "role" : 12
}

Create a New Role

You can alternatively create a NEW role. The TrackTik suite of applications manages permissions through 3 different tiers of Admin, Staff and Client. You can also define the sort order for how the roles list will appear in the Guarding Suite web application.

Regional Scope or Global

Roles participate in the Regional scope for data access like other objects you may be familiar with like Employees and Report Templates. If you intend to make a non-global role (data access will be limited to a region) you'll need to know the ID of the region (can be looked up with a GET /regions call) to include in the payload.

Or, Roles can be set to Global instead and have data access throughout the portal.

In the example below we'll create a global Admin portal role (so that it meets a scenario of a broad integration with a higher level of access, which means a Region ID isn't necessary). We also won't worry about the sort order:

POST /roles

{
    "name": "API Service Account",
    "description": "For an HR system integration",
    "portal": "ADMIN",
    "order": 0,
    "account": null,
    "region": null,
    "isGlobal": true,
    "status": "ACTIVE"
}

The response of this POSTed payload includes an ID number assigned to the Role. Take note of this for the next section explaining how to create Role Permissions:

{
        "name": "API Service Account",
        "description": "For an HR system integration",
        "portal": "ADMIN",
        "order": 0,
        "account": null,
        "region": null,
        "isGlobal": true,
        "status": "ACTIVE",
  ==>   "id": 53
}

If you'd prefer a TrackTik web application administrator create the role for you, it can be done following instructions provided here: https://support.tracktik.com/hc/en-us/articles/1500001735462--Roles-and-Permissions

Create Role Permissions

There are two Role Permission record formats in the TrackTik ecosystem. The first is legacy and tied to the web application's UI, and we won't be using it. It has a format like, "path/to/function". An actual example would be, "patrol/customer/reports".

The old format can be accessed and worked with via API, but they don't follow enough of a pattern to be easily taught, so if you need to take that approach, define the role permissions via the web application as explained here: https://support.tracktik.com/hc/en-us/articles/1500001735462--Roles-and-Permissions

The new format is based on the Admin|Client|Staff portal paradigm and directly references API endpoints, like, "admin:employees:view" (for read access of the employees endpoint) or, "admin:employees:create" (for new employee create access) or a wildcard pattern which means "all view/create and /method/execute" (execute is for API actions) permissions like:

admin:employees:*

This is the format we will use in the example below of creating a Role Permission. If you want your custom role for an API based integration to grant all access to Employees data, you would remember the Role ID and the format for created a Role Permission like this:

POST /role-permissions

{
   "role" : 53,
   "permission" : "admin:employees:*"
}

But if you wanted a read-only permission, you would:

POST /role-permissions

{
   "role" : 53,
   "permission" : "admin:employees:view"
}

You can lock things down much more even down to the individual properties of a data object like Employees, and that information will be documented at a later date and referenced here then.

Force a Password Change

When you need a new or existing Employee to define a new password for themselves, you can force a password change mechanism so that the next time they log into a TrackTik application using their existing credentials, they'll be prompted to define a new password. This account status and process is triggered using a dedicated API action and all you need is the Employee's ID (which you can lookup via /employees):

POST /employees/{id}/actions/force-password-change

(no body payload required)

Verifying Password Change Pending Status

If you need to generate a list of Employees that have had been flagged to reset their passwords, you can make a call to the /employees endpoint with the following filter:

GET /employees?forcePasswordChange=true

Employee Region Changes

If you make a mistake and your Employee was created in the wrong region, you can use their id value and the id value of the region they should be in instead, to move them to it:

POST /employees/{employees.id}/actions/move-to-region

{
   "region" : 123
}