API Reference - Staff

Staff members are the system users that consist of both employee and vendor accounts.  Personal information about these individuals, such as there phone numbers and email address are stored in these objects.

Listing Staff Members

Returns a collection of staff records, optionally filtered by the available request parameters.

GET /api/v1/staff

Available Request Parameters:

Name Type Required Description
id integer no ID of the staff member.
last_name string no Last name of an employee, or name of vendor.
first_name string no First name of an employee.
email string no Email address of a staff member.
role integer no ID of the role this employee belongs to (How to Customize your User Roles)
is_vendor boolean no If true, return vendors.  If false, return employees.
created_from timestamp no Created on or after the date.
created_to timestamp no Created on or before the date.
updated_from timestamp no Updated on or after the date.
updated_to timestamp no Updated on or before the date.
expand_field_values boolean no Instructs the API to return values as JSON for applicable custom fields.

Note: All timestamp parameters are queried and returned in UTC. 

Getting a Staff Member

Returns a single staff record, based on the numeric ID.

GET /api/v1/staff/{staff_id}

Creating an Employee

Creates a new employee (i.e. staff user) based on the given criteria. Upon success, returns a staff object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.  

Note: Employees in Trackops are always assigned to company locations.

POST /api/v1/staff/employees

Available Parameters

Name Type Required Description
client_id integer yes The ID of the company location this employee belongs to (see Setting Up your Company Locations)
role_id integer yes The role ID that contains the permissions this employee will inherit. Only roles that are designated as available for Employees are valid.  Please visit Settings > User Roles from within the app for more information.
first_name string no First name
middle_name string no Middle name
last_name string yes Last name
title string no Job title or other title
email email no The primary email address
address_1 string no Primary street address
address_2 string no Unit, apartment number, etc...
address_3 string no Additional address info
city string no City
state string no 2-3 character State code (if in US, CA, AU), otherwise a string
zip string no Zip code or postal code
country string no 2 Character ISO country code
phone_home string no The home phone number
phone_mobile string no The mobile phone number
phone_office string no The office phone number
phone_fax string no The fax number
language string no 2-character ISO language code
birthday date no ISO formatted date of birth (YYYY-MM-DD)
 account_code string no Alternate reference ID or lookup code
 notes string no General notes (visible to the employee)
 admin_notes string no Private notes (not visible by the employee)

Allowing Duplicate Records

By default, the system will check for users with the same name and consider these records to be duplicates, which are rejected. If you wish to skip conflict checking and always create new records, you can pass the allow_duplicates parameter along with the request body.  When this value is true, the the system will always create the new employee.  See the example request body below.

Example New Employee Request

A new employee (i.e. staff user) is created by POSTing a JSON object to the specified end point using the above criteria.  The JSON object must contain the required fields (as shown above) and must be nested under a employee object.  See the following example request:

{
  "allow_duplicates": false,
  "employee": {
    "client_id": 2,
    "role_id": 3,
    "first_name": "Sam",
    "middle_name": "",
    "last_name": "Spade",
    "title": "Lead Investigator",
    "email": "example@trackops.com",
    "phone_home": "555-555-55555",
    "phone_mobile": "555-555-5555",
    "phone_office": "+1 404-555-5555 x501",
    "phone_fax": "999-999-9999",
    "birthday": "1979-01-01",
    "account_code": "12345",
    "notes": "These are some general notes!",
    "admin_notes": "Created by the API."
  } 
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

Updating an Employee

Updates an employee (i.e. staff user) based on the given criteria. Upon success, returns a staff object. See the example request at the bottom of this section for a better idea of how a fully formed request should look.  

Note: Employees in Trackops are always assigned to company locations via the client_id parameter.

POST /api/v1/staff/employees

Available Parameters

Name Type Required Description
client_id integer yes The ID of the company location this employee belongs to (see Setting Up your Company Locations)
role_id integer yes The role ID that contains the permissions this employee will inherit. Only roles that are designated as available for Employees are valid.  Please visit Settings > User Roles from within the app for more information.
first_name string no First name
middle_name string no Middle name
last_name string yes Last name
title string no Job title or other title
email email no The primary email address
address_1 string no Primary street address
address_2 string no Unit, apartment number, etc...
address_3 string no Additional address info
city string no City
state string no 2-3 character State code (if in US, CA, AU), otherwise a string
zip string no Zip code or postal code
country string no 2 Character ISO country code
phone_home string no The home phone number
phone_mobile string no The mobile phone number
phone_office string no The office phone number
phone_fax string no The fax number
language string no 2-character ISO language code
birthday date no ISO formatted date of birth (YYYY-MM-DD)
 account_code string no Alternate reference ID or lookup code
 notes string no General notes (visible to the employee)
 admin_notes string no Private notes (not visible by the employee)

Allowing Duplicate Records

By default, the system will check for users with the same name and consider these records to be duplicates, which are rejected. If you wish to skip conflict checking and always create new records, you can pass the allow_duplicates parameter along with the request body.  When this value is true, the the system will always create the new employee.  See the example request body below.

Example New Employee Request

A new employee (i.e. staff user) is created by sending a JSON object to the specified end point using the above criteria.  The JSON object must contain the required fields (as shown above) and must be nested under a employee object.  See the following example request:

{
  "allow_duplicates": false,
  "employee": {
    "client_id": 2,
    "role_id": 3,
    "first_name": "Sam",
    "middle_name": "",
    "last_name": "Spade",
    "title": "Lead Investigator",
    "email": "example@trackops.com",
    "phone_home": "555-555-55555",
    "phone_mobile": "555-555-5555",
    "phone_office": "+1 404-555-5555 x501",
    "phone_fax": "999-999-9999",
    "birthday": "1979-01-01",
    "account_code": "12345",
    "notes": "These are some general notes!",
    "admin_notes": "Created by the API."
  } 
}

Note: The above request is for demonstration purposes only, your implementation will require unique data provided by your account.

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request