Employees

Each employee has a profile in OnLocation. It contains their name, contact information, locations, department, user roles and role types, and tokens.

Use the employee API to return a list of all employees, add, update or delete employees, retrieve photos, and sign employees in or out.

We recommend that bulk employee changes are managed using our SyncPortal integration rather than the API. Check the OnLocation Help Center for more information.

List all employees

Retrieves a list of all employees.

A comma separated list of tag:value search parameters, a colon separator performs an exact match, a percent separator performs a starts-with search and greater/less than search number/date ranges.

A person can be matched to an external token which has been assigned to their profile such as RFID card number, a security turnstile controller may search for a staff account to update the onsite status, eg q=token:C1BB7F.

Request
query Parameters
q
string <string>

Filter by any employee value. It is not possible to filter by custom field elements at this point.

Example: q=location:sydney,name%john,last_login>2015-02-01
order
string <string>

Order by any element returned, prefix with a - to reverse order.

Example: order=id
limit
integer <int32>

Limits the amount of records to return.

Example: limit=10
header Parameters
If-Modified-Since
string <int32>

A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only entities created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00

Responses
200

List of employees

403

Access denied to this resource

404

Resource not found

500

Internal server error

get/staff
Request samples
curl -i -X GET \
  'https://api.whosonlocation.com/v1/staff?q=string&order=string&limit=0' \
  -H 'If-Modified-Since: string'
Response samples
application/json
application/json
application/xml
[
  • {
    }
]

Update multiple employees

Updates a list of multiple employees.

The request body contains a bulk staff list which will be processed by OnLocation for adds/updates/deletes. Set the Content-Type header to identify the the format of the bulk data.

Tokens can be imported by supplying at least tokenXtype and tokenXnumber columns where X is a arbitrary number, ie token1type. Token issued and expires will only be imported if set, multiple tokens are designated by using a different number for each set.

Request
query Parameters
group
string <string>

If uploading a subset of all employees then a group name is mandatory, this allows OnLocation to properly track removed items.

location
string <string>

Override location for all uploaded employees.

header Parameters
content type
integer <int32>

The format of the uploaded bulk, must be one of:

  • Text/csv - comma separated values (,)
  • Text/psv - pipe separated values (|)
  • Application/json - JSON array type containing one or more JSON objects
  • Application/xml - XML, a root node with one or more elements
Request Body schema: application/json

Information used to update an employee or list of employees:

Array
name
required
string <string>
title
string <string>
altname
string <string>
email
string <string>
phone
string <string>
mobile
string <string>
ice
string <string>
employee_id
integer <int32>
onsite_status
string <string>
location
required
string <string>
roletype
Array of any <string>
customfields
Array of any <string>
Deprecated

This field is deprecated and will be removed in the future. Please use the cf field instead.

object

This will return an object of custom fields set for employees. The key of the custom field corresponds to the ID of the custom fields when using the Customfield endpoint

globalroaming
integer <int32>

This determines whether the employee has global roaming permission.

Enum: 0 1
globalroaming_locations
Array of any <integer>

The IDs of the global roaming locations to which the employee has access. This field is effective when globalroaming is set to true or the globalroaming parameter is ommitted and the employee already has global roaming permission.

Responses
200

Updated employee record

403

Access denied to this resource

500

Internal server error

put/staff
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Create an employee

Creates a new employee profile

Request
header Parameters
Content-Type
required
integer <int32>

The format of the uploaded image data. It must be one of image/png or image/jpeg.

Request Body schema: application/json

Information used to create an employee:

name
required
string <string>
title
string <string>
altname
string <string>
email
string <string>
phone
string <string>
mobile
string <string>
ice
string <string>
employee_id
integer <int32>
onsite_status
string <string>
location
required
string <string>
roletype
Array of any <string>
customfields
Array of any <string>
Deprecated

This field is deprecated and will be removed in the future. Please use the cf field instead.

object

This will return an object of custom fields set for employees. The key of the custom field corresponds to the ID of the custom fields when using the Customfield endpoint

globalroaming
integer <int32>

This determines whether the employee has global roaming permission.

Enum: 0 1
globalroaming_locations
Array of any <integer>

The IDs of the global roaming locations to which the employee has access. This field is effective when globalroaming is set to true or the globalroaming parameter is ommitted and the employee already has global roaming permission.

Responses
201

Employee created

403

Access denied to this resource

500

Internal server error

post/staff
Request samples
application/json
{
  • "name": "Staff Name",
  • "title": "Mr",
  • "altname": "Daffy",
  • "email": "example.staff@whosonlocation.com",
  • "phone": "+1 206 555 0123",
  • "mobile": "+1 206 555 0123",
  • "ice": "+1 206 555 0123",
  • "employee_id": 301,
  • "onsite_status": "offsite",
  • "location": "Head Office",
  • "roletype": [
    ],
  • "customfields": [
    ],
  • "cf": {
    },
  • "globalroaming": 1,
  • "globalroaming_locations": [
    ]
}
Response samples
application/json
{
  • "id": 823562,
  • "created": "2021-10-06T15:35:50+13:00",
  • "modified": "2021-10-06T16:35:50+13:00",
  • "account_status": "new",
  • "last_login": "2021-11-15T16:35:50+13:00",
  • "onsite_status": "offsite",
  • "name": "Staff Name",
  • "title": "Mr",
  • "altname": "Daffy",
  • "email": "john.doe@example.org",
  • "phone": "+1 206 555 0123",
  • "mobile": "+1 206 555 0123",
  • "ice": "+1 206 555 0123",
  • "setup_method": "manual",
  • "employee_id": "1005",
  • "location": "Head Office",
  • "cur_location": "Head Office",
  • "department": "Administration",
  • "roles": [
    ],
  • "role_types": [
    ],
  • "tokens": [
    ],
  • "remote": 1,
  • "customfields": {
    },
  • "globalroaming": 1,
  • "globalroaming_locations": [
    ]
}

Retrieve employee photo

Retrieves an employee's image, filtering with the provided ID. The request body contains the binary image data in the format specified by the Content-Type header.

Request
path Parameters
id
required
integer <int32>

ID of the employee

Responses
200

The employee's photo, if they have one

403

Access denied to resource

404

Resource not found

500

Internal server error

get/staff/{id}/photo
Request samples
curl -i -X GET \
  https://api.whosonlocation.com/v1/staff/:id/photo

Update an employee photo

Updates an employee profile image.

Request
path Parameters
id
required
integer <int32>

ID of the employee to update

header Parameters
Content-Type
required
string

The format of the uploaded image data, must be image/png or image/jpg

Responses
204

Updated photo

403

Access denied to this resource

404

Employee not found

500

Internal server error

put/staff/{id}/photo
Request samples
curl -i -X PUT \
  https://api.whosonlocation.com/v1/staff/:id/photo \
  -H 'Content-Type: string'

Retrieve employee photo metadata

Retrieves a single employee's profile image metadata.'

Request
path Parameters
id
required
integer <int32>

ID of the employee

Responses
200

Employee profile image data

403

Access denied to resource

404

Resource not found

500

Internal server error

head/staff/{id}/photo
Request samples
curl -i -X HEAD \
  https://api.whosonlocation.com/v1/staff/:id/photo

Retrieve an employee

Retrieves a single employee record, filtering with the provided ID.

A person can be matched to an external token which has been assigned to their profile such as RFID card number, a security turnstile controller may search for a staff account to update the onsite status, eg q=token:C1BB7F.

Request
path Parameters
id
required
integer <int32>

ID of the employee record to retrieve

Responses
200

Employee matching the provided ID

403

Access denied to resource

404

Resource not found

500

Internal server error

get/staff/{id}
Request samples
curl -i -X GET \
  https://api.whosonlocation.com/v1/staff/:id
Response samples
application/json
application/json
application/xml
{
  • "id": 823562,
  • "created": "2021-10-06T15:35:50+13:00",
  • "modified": "2021-10-06T16:35:50+13:00",
  • "account_status": "new",
  • "last_login": "2021-11-15T16:35:50+13:00",
  • "onsite_status": "offsite",
  • "name": "Staff Name",
  • "title": "Mr",
  • "altname": "Daffy",
  • "email": "john.doe@example.org",
  • "phone": "+1 206 555 0123",
  • "mobile": "+1 206 555 0123",
  • "ice": "+1 206 555 0123",
  • "setup_method": "manual",
  • "employee_id": "1005",
  • "location": "Head Office",
  • "cur_location": "Head Office",
  • "department": "Administration",
  • "roles": [
    ],
  • "role_types": [
    ],
  • "tokens": [
    ],
  • "remote": 1,
  • "customfields": {
    },
  • "globalroaming": 1,
  • "globalroaming_locations": [
    ]
}

Update an employee

Updates a one or more employee profiles.

Request
path Parameters
id
required
integer <int32>

ID of the employee or employees to update

Request Body schema: application/json

Information used to update an employee or list of employees:

name
required
string <string>
title
string <string>
altname
string <string>
email
string <string>
phone
string <string>
mobile
string <string>
ice
string <string>
employee_id
integer <int32>
onsite_status
string <string>
location
required
string <string>
roletype
Array of any <string>
customfields
Array of any <string>
Deprecated

This field is deprecated and will be removed in the future. Please use the cf field instead.

object

This will return an object of custom fields set for employees. The key of the custom field corresponds to the ID of the custom fields when using the Customfield endpoint

globalroaming
integer <int32>

This determines whether the employee has global roaming permission.

Enum: 0 1
globalroaming_locations
Array of any <integer>

The IDs of the global roaming locations to which the employee has access. This field is effective when globalroaming is set to true or the globalroaming parameter is ommitted and the employee already has global roaming permission.

Responses
204

Updated employee record

403

Access denied to this resource

500

Internal server error

put/staff/{id}
Request samples
application/json
{
  • "name": "Staff Name",
  • "title": "Mr",
  • "altname": "Daffy",
  • "email": "example.staff@whosonlocation.com",
  • "phone": "+1 206 555 0123",
  • "mobile": "+1 206 555 0123",
  • "ice": "+1 206 555 0123",
  • "employee_id": 301,
  • "onsite_status": "offsite",
  • "location": "Head Office",
  • "roletype": [
    ],
  • "customfields": [
    ],
  • "cf": {
    },
  • "globalroaming": 1,
  • "globalroaming_locations": [
    ]
}

Delete an employee

Removes the specified employee.

Request
path Parameters
id
required
integer <int32>

ID of the employee to delete

Responses
204

Employee deleted

403

Access denied to resource

404

Resource not found

500

Internal server error

delete/staff/{id}
Request samples
curl -i -X DELETE \
  https://api.whosonlocation.com/v1/staff/:id