Employee Management API

Manage mobile workforce accounts, role-based access permissions, and employee lifecycle states (Active, Disabled, Enabled).

---

Overview & Solution

Field sales, delivery fleets, and technical inspection forces need centralized identity management. The Employee Management API links employee records to assigned sales territories and security access levels.

---

Industry Use Cases

1. Territory Access Control

• Dynamic Role Management: Restrict field managers' visibility strictly to their assigned districts or branch territories.

2. Immediate Account Deactivation

• Instant Offboarding: Disable field accounts and revoke telemetry streaming immediately upon employee departure or device loss.

---

---

API reference

Field Force Mobility Execution APIs · Requires Intelomatic tenant

Field definitions: Employee

Endpoints

Method	Path	Purpose
POST	/employee/create	Create an employee
GET	/employee/detail/{id}	Get employee detail
POST	/employee/search	Search employees in a team
POST	/employee/disable/{employee_guid}	Disable an employee
POST	/employee/enable/{employee_guid}	Enable an employee
PUT	/api/app-base/employees/{employee_guid}	Replace an employee record
PATCH	/api/app-base/employees/{employee_guid}	Partially update an employee
POST	/employee/search	Search employees across the tenant

All requests require a bearer token and the api-key query parameter:

Authorization: Bearer <access_token>

?api-key=<apiKey>

Create an employee

POST /employee/create

Request Parameters

Parameter	In	Type	Required	Description	Example
employee_username	body	string	No
employee_full_name	body	string	No
employee_email	body	string	No
employee_phone	body	string	No
employee_dob	body	string	No
employee_role	body	string	No
employee_organization_id	body	string	No
employee_team_id	body	string	No
employee_reporting_manager	body	string	No
config	body	object	No
config.isValueDataType	body	boolean	No
config.createAccount	body	boolean	No

Request body

{
  "employee_username": "apidemo_newuser_9",
  "employee_full_name": "Demo User 9",
  "employee_email": "[email protected]",
  "employee_phone": "919800000009",
  "employee_dob": "1995-04-17",
  "employee_role": "Worker",
  "employee_organization_id": "1",
  "employee_team_id": "2",
  "employee_reporting_manager": "your_username",
  "config": {
    "isValueDataType": true,
    "createAccount": true
  }
}

Response Schema

200 OK

{
  "result": 0,
  "data": {
    "employee_guid": "6ab33224bba47a219f950da5",
    "Id": "a5a78d42-3c18-4c34-b80d-e3046fa8fc0e",
    "employee_full_name": "Demo User 9",
    "employee_email": "[email protected]",
    "employee_phone": "919800000009",
    "employee_team_id": "2",
    "employee_username": "apidemo_newuser_9",
    "employee_organization_id": "1",
    "employee_status": "3",
    "employee_dob": "1995-04-17",
    "employee_role": "Worker",
    "employee_reporting_manager": "apidemo_sovereignsolutions",
    "employee_created_from": 3,
    "employee_last_modified_from": 3,
    "Title": "Demo User 9",
    "Path": "/<internal storage path>"
  },
  "resultId": "LJ2j18NYmQ"
}

Field	Type	Description
result	integer	Status of the call. 0 means it succeeded.
data	object	The employee as created.
data.employee_guid	string	Business identifier of the employee - the value the enable and disable calls take in the path.
data.Id	string	Record ID in the EMPLOYEE layer - the value GET /employee/detail/{id} takes.
data.employee_full_name	string
data.employee_email	string
data.employee_phone	string
data.employee_team_id	string
data.employee_username	string
data.employee_organization_id	string
data.employee_status	string	Lifecycle state as a numeric code: 1 New, 2 Inactive, 3 Active, 4 Disable.
data.employee_dob	string
data.employee_role	string	Role code, as sent.
data.employee_reporting_manager	string
data.employee_created_from	integer	Channel that created the record, set by the platform: 1 Mobile, 2 Web, 3 Others.
data.employee_last_modified_from	integer	Channel of the last change, set by the platform: 1 Mobile, 2 Web, 3 Others.
data.Title	string	Display label of the record, kept in step with the full name.
data.Path	string	Internal storage location. Read-only.
resultId	string	Correlation ID for this call. Quote it when reporting a problem to support.

What you get back

The record is returned inside a result / data / resultId envelope. Two identifiers in data you will need later:

Field	What it is	Where you use it
employee_guid	Account identifier	Enable and disable calls (/employee/enable/{employee_guid})
Id	Record identifier (UUID)	Reading detail (/employee/detail/{id})

Get employee detail

GET /employee/detail/{id}

Request Parameters

Parameter	In	Type	Required	Description	Example
id	path	string	Yes	Employee record Id (not employee_guid)	6c6009a2-3be2-498f-9f25-00a1ab142b25

Response Schema

200 OK

{
  "Id": "6c6009a2-3be2-498f-9f25-00a1ab142b25",
  "NodeId": "6c6009a2-3be2-498f-9f25-00a1ab142b25",
  "Name": "8267ec96-2ede-405b-954c-28c25ae53431",
  "Title": "Demo User 2",
  "Description": null,
  "employee_guid": "6a9bacffc5f4802e0abf1870",
  "employee_username": "apidemo_newuser_2",
  "employee_full_name": "Demo User 2",
  "employee_email": "[email protected]",
  "employee_phone": "919000000002",
  "employee_dob": "1995-04-17T00:00:00.000Z",
  "employee_role": "Worker",
  "employee_status": "4",
  "employee_team_id": "2",
  "employee_organization_id": "1",
  "employee_reporting_manager": "apidemo_sovereignsolutions",
  "employee_code": null,
  "employee_type_id": null,
  "employee_vehicle_id": null,
  "employee_image": null,
  "Path": "/<internal storage path>",
  "CreatedDate": "2026-09-05T05:47:43.296Z",
  "CreatedUser": "apidemo_sovereignsolutions",
  "CreatedUserId": 19536,
  "ModifiedDate": "2026-09-22T11:00:15.340Z",
  "ModifiedUser": "apidemo_sovereignsolutions",
  "ModifiedUserId": 19561,
  "DynamicProperties": null
}

Field	Type	Description
Id	string	Record ID of the employee in the EMPLOYEE layer.
NodeId	string	Same value as Id on this endpoint.
Name	string	Internal node name. Not an identifier any endpoint accepts.
Title	string	Display label, kept in step with the full name.
Description	string	Free-text description. null unless set.
employee_guid	string	Business identifier of the employee - the value the enable and disable calls take in the path.
employee_username	string	Login name. Other records reference the employee by this value.
employee_full_name	string	Full name.
employee_email	string	Email address.
employee_phone	string	Phone number.
employee_dob	string	Date of birth, returned as a full UTC timestamp.
employee_role	string	Role code - the same value accepted on input (e.g. Worker). See Employee.
employee_status	string	Lifecycle state as a numeric code: 1 New, 2 Inactive, 3 Active, 4 Disable.
employee_team_id	string	Numeric team ID - the value to send back on a write.
employee_organization_id	string	Numeric organization ID.
employee_reporting_manager	string	Username of the manager this employee reports to.
employee_code	string	Optional payroll or HR code. null unless your tenant uses it.
employee_type_id	string	Optional employee type. null unless your tenant uses it.
employee_vehicle_id	string	Vehicle assigned to the employee. null unless set.
employee_image	string	Profile photo. null unless set.
Path	string	Internal storage location. Read-only.
CreatedDate	string	When the employee was created, UTC.
CreatedUser	string	Account that created the employee.
CreatedUserId	integer	Numeric ID of the account that created the employee.
ModifiedDate	string	When the employee was last changed, UTC.
ModifiedUser	string	Account that last changed the employee.
ModifiedUserId	integer	Numeric ID of the account that last changed the employee.
DynamicProperties	string	Reserved. null in normal use.

Returns every employee_* field, including any left unset as null - use this call to read the full current state of an employee.

employee_status, employee_team_id and employee_organization_id are numeric codes here, the same form a write expects (see Employee for the code-to-label mapping). The search and partial update responses return these as labels/names instead.

Search employees in a team

POST /employee/search

Request Parameters

Parameter	In	Type	Required	Description	Example
hierarchyPath	query	string	No	Team hierarchy path, /<tenant>/<team>	/demo/sovereignsolutions
isInTree	body	boolean	No
skip	body	integer	No
take	body	integer	No

Request body

{
  "isInTree": false,
  "skip": 0,
  "take": 20
}

skip and take are paging properties:

• skip - number of records to skip before the page starts. 0 is the first page.
• take - maximum number of records returned in this page. -1 returns every match, which is only safe on small datasets.

The response reports total, the number of records matching the query regardless of paging - keep requesting pages until skip + take reaches it.

Response Schema

200 OK

{
  "data": [
    {
      "Id": "a5a78d42-3c18-4c34-b80d-e3046fa8fc0e",
      "Layer": "EMPLOYEE",
      "Path": "/<internal storage path>",
      "ParentPath": "/<internal storage path>",
      "CreatedDate": "2026-09-23T01:57:56Z",
      "CreatedUser": "apidemo_sovereignsolutions",
      "ModifiedDate": "2026-09-23T01:58:12Z",
      "ModifiedUser": "apidemo_sovereignsolutions",
      "Title": "Demo User 9",
      "employee_full_name": "Demo User 9",
      "employee_email": "[email protected]",
      "employee_phone": "919800000009",
      "employee_dob": "1995-04-17T00:00:00Z",
      "employee_team_id__keyfield": "2",
      "employee_team_id": "SovereignSolutions",
      "employee_username": "apidemo_newuser_9",
      "employee_status": "Active",
      "employee_guid": "6ab33224bba47a219f950da5",
      "employee_role": "Team Member",
      "employee_organization_id": "demo",
      "employee_reporting_manager": "apidemo_sovereignsolutions"
    }
  ],
  "total": 15
}

Field	Type	Description
data	array	Matching employees, one page.
data[]	object
data[].Id	string	Record ID in the EMPLOYEE layer.
data[].Layer	string	Layer the record lives in, always EMPLOYEE.
data[].Path	string	Internal storage location. Read-only.
data[].ParentPath	string	Internal storage location of the parent node. Read-only.
data[].CreatedDate	string	When the employee was created, UTC.
data[].CreatedUser	string	Account that created the employee.
data[].ModifiedDate	string	When the employee was last changed, UTC.
data[].ModifiedUser	string	Account that last changed the employee.
data[].Title	string	Display label of the record, kept in step with the full name.
data[].employee_full_name	string
data[].employee_email	string
data[].employee_phone	string
data[].employee_dob	string	Date of birth, returned as a full UTC timestamp.
data[].employee_team_id__keyfield	string	The numeric team ID behind employee_team_id. This is the value to send back on a write.
data[].employee_team_id	string	Team name, not the numeric ID.
data[].employee_username	string	Login name.
data[].employee_status	string	Lifecycle state as a label: New, Inactive, Active or Disable.
data[].employee_guid	string	Business identifier of the employee.
data[].employee_role	string	Display label of the role, not the code accepted on input - Worker comes back as Team Member.
data[].employee_organization_id	string	Organization name, not the numeric ID.
data[].employee_reporting_manager	string	Username of the manager this employee reports to.
total	integer	Total number of matches, across all pages.

Disable an employee

POST /employee/disable/{employee_guid}

Request Parameters

Parameter	In	Type	Required	Description	Example
employee_guid	path	string	Yes	GUID of the employee to disable	6ab33224bba47a219f950da5

Response Schema

200 OK - streamed: 2 JSON objects sent one after another in the same body.

Message 1

{
  "result": 0,
  "data": true,
  "resultId": "H6733QoVCK"
}

Field	Type	Description
result	integer	Status of the call. 0 means it succeeded.
data	boolean	true when the employee was disabled.
resultId	string	Correlation ID for this call. Quote it when reporting a problem to support.

Message 2 - updated employee node

{
  "result": 0,
  "data": {
    "employee_guid": "6ab33224bba47a219f950da5",
    "Id": "a5a78d42-3c18-4c34-b80d-e3046fa8fc0e",
    "employee_status": "4",
    "employee_last_modified_from": 2,
    "LayerData": {
      "employee_guid": "6ab33224bba47a219f950da5",
      "employee_status": "4"
    },
    "Type": null,
    "NodeId": 100195153,
    "ParentId": 99689425,
    "Name": "26f14f46-696d-4537-a5b4-1237804feadf",
    "Title": null,
    "Description": null,
    "Created": "2026-09-23T01:57:56.97Z",
    "Creator": "apidemo_sovereignsolutions",
    "CreatorId": 19561,
    "Modified": "2026-09-23T01:58:12.296Z",
    "Modifier": "apidemo_sovereignsolutions",
    "ModifierId": 19561,
    "Path": "/<internal storage path>",
    "ParentIdPath": "/<internal node path>",
    "ParentPath": null,
    "Status": null,
    "Template": null,
    "MimeType": {
      "MimeType": "application/octet-stream",
      "Display": "unknown"
    },
    "Properties": [
      {
        "Name": "employee_guid",
        "DisplayName": null,
        "Value": "6ab33224bba47a219f950da5",
        "DataType": 3,
        "Format": null
      },
      {
        "Name": "employee_status",
        "DisplayName": null,
        "Value": "4",
        "DataType": 10,
        "Format": null
      }
    ],
    "Layer": "<TENANT>_EMPLOYEE",
    "Content": null,
    "IsInherited": false
  },
  "resultId": "VPE7S0E0hY"
}

Field	Type	Description
result	integer	Status of the call. 0 means it succeeded.
data	object	The employee node after the change.
data.employee_guid	string	The employee you disabled - the same GUID you sent in the path.
data.Id	string	Record ID in the EMPLOYEE layer.
data.employee_status	string	New lifecycle state as a numeric code - 4 (Disable) after a successful disable.
data.employee_last_modified_from	integer	Channel of this change, set by the platform: 1 Mobile, 2 Web, 3 Others.
data.LayerData	object	Only the fields this call changed, keyed by field name.
data.LayerData.employee_guid	string
data.LayerData.employee_status	string
data.Type	string
data.NodeId	integer	Internal numeric node ID. Not an identifier any endpoint accepts.
data.ParentId	integer	Internal numeric ID of the parent node.
data.Name	string	Internal node name.
data.Title	string
data.Description	string
data.Created	string	When the employee was created, UTC.
data.Creator	string	Account that created the employee.
data.CreatorId	integer	Numeric ID of the account that created the employee.
data.Modified	string	When this change was applied, UTC.
data.Modifier	string	Account whose token made this call.
data.ModifierId	integer	Numeric ID of the account whose token made this call.
data.Path	string	Internal storage location. Read-only.
data.ParentIdPath	string	Internal node path. Read-only.
data.ParentPath	string
data.Status	string
data.Template	string
data.MimeType	object
data.MimeType.MimeType	string
data.MimeType.Display	string
data.Properties	array	The changed fields again, one entry per field with its value and data type.
data.Properties[]	object
data.Properties[].Name	string	Field name.
data.Properties[].DisplayName	string
data.Properties[].Value	string	New value.
data.Properties[].DataType	integer	System data type code of the field. See Data types.
data.Properties[].Format	string
data.Layer	string	Internal layer name, prefixed with your tenant code.
data.Content	string
data.IsInherited	boolean
resultId	string	Correlation ID for this message.

The response is streamed as two JSON objects, sent one after the other in the same 200 OK body - not wrapped in an array. Message 1 confirms the account was disabled (data: true). Message 2 carries the employee node after the change, with data.employee_status now 4. Read the body until both objects have arrived; a client that parses the whole body as a single JSON document will fail.

The employee keeps their record and history - disabling only blocks the account. Re-enable with the /employee/enable endpoint.

Enable an employee

POST /employee/enable/{employee_guid}

Request Parameters

Parameter	In	Type	Required	Description	Example
employee_guid	path	string	Yes	GUID of the employee to enable	6a9b7d4bf212b7ed3916862a

Response Schema

200 OK

{
  "employee_guid": "6a9b7d4bf212b7ed3916862a",
  "Id": "2e0fec36-963c-4592-b8c9-a2c5096813f8",
  "employee_status": "3",
  "Title": "Demo User (updated)",
  "employee_last_modified_from": 2
}

Field	Type	Description
employee_guid	string	The employee you enabled - the same GUID you sent in the path.
Id	string	Record ID in the EMPLOYEE layer.
employee_status	string	New lifecycle state as a numeric code - 3 (Active) after a successful enable.
Title	string	Display label of the record.
employee_last_modified_from	integer	Channel of this change, set by the platform: 1 Mobile, 2 Web, 3 Others.

Replace an employee record

PUT /api/app-base/employees/{employee_guid}

Request Parameters

Parameter	In	Type	Required	Description	Example
employee_guid	path	string	Yes	GUID of the employee to update	6a9b7d4bf212b7ed3916862a
employee_username	body	string	No
employee_full_name	body	string	No
employee_email	body	string	No
employee_phone	body	string	No
employee_dob	body	string	No
employee_role	body	string	No
employee_team_id	body	string	No
employee_reporting_manager	body	string	No

Request body

{
  "employee_username": "field_user_01",
  "employee_full_name": "Field User Test",
  "employee_email": "[email protected]",
  "employee_phone": "919000000003",
  "employee_dob": "1995-09-14",
  "employee_role": "Worker",
  "employee_team_id": "2",
  "employee_reporting_manager": "your_username"
}

Response Schema

200 OK

{
  "employee_guid": "6a9b7d4bf212b7ed3916862a",
  "employee_username": "field_user_01",
  "employee_full_name": "Field User Test",
  "employee_email": "[email protected]",
  "employee_phone": "919000000003",
  "employee_dob": "1995-09-14T17:00:00Z",
  "employee_role": "Team Member",
  "employee_status": "New",
  "employee_team_id": "2",
  "employee_team_id__keyfield": "2",
  "employee_reporting_manager": "apidemo_sovereignsolutions",
  "employee_last_modified_from": 2,
  "Title": "Field User Test"
}

Field	Type	Description
employee_guid	string	The employee you updated - the same GUID you sent in the path.
employee_username	string	Login name. Other records reference the employee by this value.
employee_full_name	string	The value now stored.
employee_email	string	The value now stored.
employee_phone	string	The value now stored.
employee_dob	string	Date of birth, returned as a full UTC timestamp even though it is sent as a date.
employee_role	string	Returned as the display label of the role, not the code you sent - Worker comes back as Team Member. See Employee.
employee_status	string	Account lifecycle state: New, Inactive, Active or Disable. This call does not change it.
employee_team_id	string	Team the employee belongs to.
employee_team_id__keyfield	string	Internal duplicate of employee_team_id. Ignore it.
employee_reporting_manager	string	Username of the manager this employee reports to.
employee_last_modified_from	integer	Channel of this change, set by the platform: 1 Mobile, 2 Web, 3 Others.
Title	string	Display label of the record, kept in step with the full name.

This is a replace. Send the full set of fields you want the employee to end up with - a field you leave out is not preserved from the previous state.

Role and status come back as display labels, not the codes accepted on input. Map them back through Employee before comparing to what you sent.

Partially update an employee

PATCH /api/app-base/employees/{employee_guid}

Request Parameters

Parameter	In	Type	Required	Description	Example
employee_guid	path	string	Yes	GUID of the employee to update	6a9b7d4bf212b7ed3916862a
employee_full_name	body	string	No

Request body

{
  "employee_full_name": "Demo User (updated)"
}

Response Schema

200 OK

{
  "employee_guid": "6a9b7d4bf212b7ed3916862a",
  "Id": "2e0fec36-963c-4592-b8c9-a2c5096813f8",
  "employee_username": "field_user_01",
  "employee_full_name": "Demo User (updated)",
  "employee_email": "[email protected]",
  "employee_phone": "919000000003",
  "employee_dob": "1995-09-14T17:00:00Z",
  "employee_role": "Team Member",
  "employee_status": "New",
  "employee_team_id": "SovereignSolutions",
  "employee_team_id__keyfield": "2",
  "employee_organization_id": "demo",
  "employee_reporting_manager": "apidemo_sovereignsolutions",
  "employee_last_modified_from": 2,
  "Layer": "EMPLOYEE",
  "Title": "Demo User (updated)",
  "Path": "/<internal storage path>",
  "ParentPath": "/<internal storage path>",
  "CreatedDate": "2026-09-05T02:24:11Z",
  "CreatedUser": "apidemo_sovereignsolutions",
  "ModifiedDate": "2026-09-08T06:53:25Z",
  "ModifiedUser": "apidemo_sovereignsolutions"
}

Field	Type	Description
employee_guid	string	The employee you updated - the same GUID you sent in the path.
Id	string	Record ID in the EMPLOYEE layer. Different from employee_guid; the employee endpoints address the employee by the GUID.
employee_username	string	Login name. Other records reference the employee by this value.
employee_full_name	string	The value now stored.
employee_email	string	The value now stored.
employee_phone	string	The value now stored.
employee_dob	string	Date of birth, returned as a full UTC timestamp even though it is sent as a date.
employee_role	string	Display label of the role, not the code accepted on input - Worker comes back as Team Member. See Employee.
employee_status	string	Account lifecycle state: New, Inactive, Active or Disable. Unchanged by this call.
employee_team_id	string	Team name, not the numeric ID you send on create.
employee_team_id__keyfield	string	The numeric team ID behind employee_team_id. This is the value to send back on a write.
employee_organization_id	string	Organization name, not the numeric ID you send on create.
employee_reporting_manager	string	Username of the manager this employee reports to.
employee_last_modified_from	integer	Channel of this change, set by the platform: 1 Mobile, 2 Web, 3 Others.
Layer	string	Layer the record lives in, always EMPLOYEE.
Title	string	Display label of the record, kept in step with the full name.
Path	string	Internal storage location. Read-only.
ParentPath	string	Internal storage location of the parent node. Read-only.
CreatedDate	string	When the employee was created, UTC.
CreatedUser	string	Account that created the employee.
ModifiedDate	string	When this update was applied, UTC.
ModifiedUser	string	Account whose token made this call.

Send only what you want to change. Unlike PUT, fields you leave out keep their current value; the response returns the full record as it now stands.

Names come back where IDs went in. employee_team_id and employee_organization_id are returned as names (SovereignSolutions, demo) although a create or replace sends numeric IDs. The numeric team ID is still available as employee_team_id__keyfield - use that value when writing the employee back.

Search employees across the tenant

POST /employee/search

Request Parameters

Parameter	In	Type	Required	Description	Example
skip	body	integer	No
take	body	integer	No
searchKey	body	string	No

Request body

{
  "skip": 0,
  "take": 20,
  "searchKey": "field_user_01"
}

skip and take are paging properties:

• skip - number of records to skip before the page starts. 0 is the first page.
• take - maximum number of records returned in this page. -1 returns every match, which is only safe on small datasets.

The response reports total, the number of records matching the query regardless of paging - keep requesting pages until skip + take reaches it.

More request examples

List all

{
  "skip": 0,
  "take": 20
}

Search by username

{
  "skip": 0,
  "take": 20,
  "searchKey": "field_user_01"
}

Response Schema

200 OK

{
  "data": [
    {
      "Id": "f62b56f8-72e2-4691-bfae-24923cb1825d",
      "Layer": "EMPLOYEE",
      "CreatedDate": "2026-06-05T03:59:53Z",
      "Title": "Test 1",
      "employee_username": "field_user_01",
      "employee_full_name": "Test 1",
      "employee_status": "3"
    }
  ],
  "total": 1
}

Field	Type	Description
data	array
data[]	object
data[].Id	string
data[].Layer	string
data[].CreatedDate	string
data[].Title	string
data[].employee_username	string
data[].employee_full_name	string
data[].employee_status	string
total	integer

Example

curl -X POST '$BASE_URL/employee/create?api-key=$API_KEY' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"employee_username": "apidemo_newuser_9", "employee_full_name": "Demo User 9", "employee_email": "[email protected]", "employee_phone": "919800000009", "employee_dob": "1995-04-17", "employee_role": "Worker", "employee_organization_id": "1", "employee_team_id": "2", "employee_reporting_manager": "your_username", "config": {"isValueDataType": true, "createAccount": true}}'

Notes

employee_organization_id, employee_team_id and employee_reporting_manager are all specific to your workspace - you receive them when your demo or tenant account is provisioned. The values below are placeholders.

POST /employee/search without a query parameter searches every employee your key can see; add hierarchyPath to scope the same search to one team's hierarchy path.

employee_status is set by the platform: 1 new, 2 inactive, 3 active, 4 disabled. The enable and disable calls move a record between 3 and 4.