Introduction

The APIʼs documented within this technical specification (GetUsers, AddUpdateUsers) can be used to access existing data or create new data within the SafetyChain Software application. Users are the objects created within SafetyChain to allow users to access the software.

Getting Started

All API requests require an authorization token – reference our Authentication page for more information

Get Users

Required User Fields and the Equivalent UI Setup

What is required to configure a user in the UI?

There is a set of attributes that are required for configuring a User. The User Name must be unique. A first and last name is required for each user as well as an email address. If a user will not be receiving emails, or does not have an email address, some sort of email address must be entered. Here is a screenshot of the User fields:

The Timezone is used to display timestamps within the web application. Data is stored in UTC and then converted to the user based on their configured Timezone.

Locations are a layer of all user security filtering within the SafetyChain Software application. A User is assigned to a Location(s) and any related Forms/Tasks/Etc will be filtered for the specific Locations for which the user is assigned.

Roles are used to grant a User Permissions within the system.

Workgroups are used for Task Assignments and Notifications. This is not a required field when configuring a user.

GetUsers

This API will be used to list users in the system.

API Structure

POST api/integration/GetUsers

Required Request Parameters

Name	Location	Description
Authorization token	Header	See Login Authentication API documentation
Take	Body	Paging the data (recommended default 100)
Skip	Body	Paging the data (recommended default 0)
PageSize	Body	Paging the data (recommended default 100)
Filters: Firstname Lastname Username Role Location EmployeeId FullName dptlocation dptroles	Body	Used to filter the Users returned in the response. The "Logic" attribute can be: Or, And The "Operator" on the filter can be: Contains, Equal

Request JSON firstname and lastname parameters:

{
    "Take": 100,
    "Skip": 0,
    "PageSize": 100,
    "Filter": {
        "Logic": "and",
        "Filters": [
            {
                "Field": "firstname",
                "Value": "Test",
                "Operator": "contains"
            },
            {
                "Field": "lastname",
                "Value": "User1",
                "Operator": "contains"
            }
        ]
    }
}

Request JSON employeeid parameter:

{
    "Take": 100,
    "Skip": 0,
    "PageSize": 100,
    "Filter": {
        "Logic": "and",
        "Filters": [       
            {
                "Field": "employeeid",
                "Value": "123456",
                "Operator": "contains"
            }
        ]
    }
}

Request JSON location parameter:

{
  "Take": 100,
  "Skip": "",
  "Filter": {
    "filters": [{
        "field": "dptlocation",
        "operator": "contains",
        "value": "QA Tech"
      } ],
    "logic": "and"
  }
}

Request JSON roles parameter:

{
  "Take": 100,
  "Skip": "",
  "Filter": {
    "filters": [{
        "field": "dptroles",
        "operator": "contains",
        "value": "QA Tech"
      } ],
    "logic": "and"
  }
}

Response Parameters

Name	Description
ID	GUID of the User Object. – not required
Title	Only used for Suppliers
FirstName	User's first name
LastName	User's last name
Username	Username
Email	Configured email address
ClearPassword	Please note this is part of the data schema but clear passwords are never stored
PasswordHash	This will not be returned by the UI but is part of the data schema
PasswordExpired	Status for the user's password expiration
PasswordResetDate	The last time the user's password was reset
IsActive	User account status. Setting this to false will disable the user
IsLocked	A user may be locked if they exceed the limit for failed login attempts
UnsuccessfulAttemptsCount	Running total of login failures since the last successful login
RemainingAttemptsCount	How many tries the user has remaining before being locked
TimeZone	Timezone information for the user
Roles	The defined permissions the user has been granted
Permissions	Value is null – at this time
UserRefs	Value is null – at this time
IsEnable	true or false
AddedUser	Value is null – at this time
RemovedUser	Value is null – at this time
ID	Role GUID
Name	Role Name
AddedRoles	Value is null – at this time
RemovedRoles	Value is null – at this time
Locations	The Locations the user belongs to
IsEnabled	true or false
Id	Location ID GUID
Name	Location Name
AddedLocation	Value is null – at this time
RemovedLocation	Value is null – at this time
Workgroups
WorkGroupUsers	Value is null – at this time
IsEnable	true or false
GetEnabledWorkgroup	Value is null – at this time
AddedWorkGroupUsers	Value is null – at this time
IntegerId	0
Id	Workgroup GUID
Name	Workgroup Name
AddedWorkGroups	Value is null – at this time
RemovedWorkGroups	Value is null – at this time
IsAdmin	true or false
UserType	This will always be 0
Partner	Value is null – at this time
FullName	User's Full Name, first name space last name
Name	Display name
Status	Active or InActive
HasAllLocations	Flag used if a user has been granted access to All Locations, true or false
HasAllSuppliers	Used for Supplier Users, true or false
PasswordPolicy	Value is null – at this time
PartnerRefs
AddedPartnerRefs	Value is null – at this time
RemovedPartnerRefs	Value is null – at this time
Pin	User's Secret Pin, only used in Direct Observation, set to null if no "Pin" has been set.
EmployeeId	Employee Identification Number
Phone	Employee Phone Number
DefaultLocation
IsEnabled	true or false
Id	Default Location GUID
Name	Default Location Name
SecurityLevel	Define the user's security level. This is used to manage level of settings the user can modify.

Sample Response JSON

{
  "Data": [
      {
        "Id": "665cef8d-88f3-42ac-b9d5-b63bc44954e0",
        "Title": "",
        "FirstName": "Test",
        "LastName": "User1",
        "Username": "TestUser1",
        "Email": "[email protected]",
        "ClearPassword": null,
        "PasswordHash": null,
        "PasswordExpired": false,
        "PasswordResetDate": "0001-01-01T00:00:00.0000000Z",
        "IsActive": true,
        "IsLocked": false,
        "UnsuccessfulAttemptsCount": 0,
        "RemainingAttemptsCount": null,
        "UserCultureInfo": null,
        "TimeZone": {
          "Id": "US/Pacific",
          "DisplayName": "U.S. Pacific"
        },
        "Roles": [
          {
            "Permissions": null,
            "UserRefs": null,
            "IsEnable": false,
            "AddedUser": null,
            "RemovedUser": null,
            "Id": "cec00be4-65a4-4998-91ea-ea12485a4b46",
            "Name": "Operator 1"
          }
        ],
        "AddedRoles": null,
        "RemovedRoles": null,
        "Locations": [
          {
            "IsEnabled": false,
            "Id": "00000000-0000-0000-0000-000000000000",
            "Name": "ALL"
          }
        ],
        "AddedLocation": null,
        "RemovedLocation": null,
        "WorkGroups": [
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "3b30a38e-6ddb-4b73-b580-36436c8bd31c",
            "Name": "Operator 1"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "d8f6a130-2c4f-4337-93d7-a46f2b034b2d",
            "Name": "FSQA"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "27515ef8-5ac5-499d-bb1d-ab2d90a8a7d1",
            "Name": "R&D"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "40d5b4a3-cbca-43d6-a078-b2e2f947d885",
            "Name": "Category Manager"
          }
        ],
        "AddedWorkGroups": null,
        "RemovedWorkGroups": null,
        "IsAdmin": false,
        "UserType": 0,
        "Partner": null,
        "FullName": "Test User1",
        "Upn": "TestUser1",
        "Name": "Test User1",
        "Status": "Active",
        "HasAllLocations": true,
        "HasAllSuppliers": false,
        "PasswordPolicy": null,
        "PartnerRefs": [
        
        ],
        "AddedPartnerRefs": null,
        "RemovedPartnerRefs": null,
        "Pin": null,
        "EmployeeId": "79996",
        "Phone": "",
        "DefaultLocation": {
          "IsEnabled": false,
          "Id": "3ce94133-d81d-4986-a18f-2a4e0ad75012",
          "Name": "Los Angeles - 90024"
        },
        "SecurityLevel": "0"
      }
    ]
  },
  "RequestError": null,
  "DetailedError": null,
  "Status": true,
  "Errors": null,
  "RefreshToken": false
}

AddUpdateUsers

This API will be used to add new, or modify existing, Users in the system. Implementation best practice to call GetUsers to review fields required in your request for AddUpdateUsers. API Structure

POST api/integration/AddUpdateUsers

Required Request Parameters

Name	Location	Options	Description
Authorization token	Header		See Login Authentication API documentation
ID	Body		GUID for the user. If creating a user, a 0 GUID can be provided and the system will generate a new one or it can be left blank
FirstName	Body		User's first name
LastName	Body		User's last name
Username	Body		Username
Email	Body		User's email address for notifications
Timezone	Body	ID DisplayName America/Phoenix US/Eastern US/Mountain Etc/GMT US/Pacific US/Central US/Hawaii U.S. Arizona (except Navajo) U.S. Eastern U.S. Mountain Greenwich Mean Time U.S. Pacific U.S. Central U.S. Hawaii	User's working timezone. This is used to convert timestamp data in the web application. All timestamps are stored in UTC and converted to display to the user. The timezone options are abbreviated here. We follow the IANA standard.
Roles	Body	Roles must be pre-configured to assign to a user	Permissions granted to the user
Locations	Body	Locations must be pre-configured to assign to a user	The Locations the user belongs to
Workgroups	Body	Workgroups must be pre-configured to assign to a user	The workgroups that the user belongs to
Status	Body	0 or 1	0 = active, 1 = inactive
Operation	Body	"Insert","Update"	Flag used to indicate if you are adding resources or updating resources.
PartialSuccess	Body	"True","False"	Flag to allow a partial commit of the changes.

Request JSON: Creating or Editing a User

{
  "Operation": "Update",
  "PartialSuccess": false,
  "RequestNo": "AddUpdateUsers",
  "Data": {
    "Users": [
      {
        "Id": "665cef8d-88f3-42ac-b9d5-b63bc44954e0",
        "Title": "",
        "FirstName": "Test",
        "LastName": "User1",
        "Username": "TestUser1",
        "Email": "[email protected]",
        "ClearPassword": null,
        "PasswordHash": null,
        "PasswordExpired": false,
        "PasswordResetDate": "0001-01-01T00:00:00.0000000Z",
        "IsActive": true,
        "IsLocked": false,
        "UnsuccessfulAttemptsCount": 0,
        "RemainingAttemptsCount": null,
        "UserCultureInfo": null,
        "TimeZone": {
          "Id": "US/Pacific",
          "DisplayName": "U.S. Pacific"
        },
        "Roles": [
          {
            "Permissions": null,
            "UserRefs": null,
            "IsEnable": false,
            "AddedUser": null,
            "RemovedUser": null,
            "Id": "cec00be4-65a4-4998-91ea-ea12485a4b46",
            "Name": "Operator 1"
          }
        ],
        "AddedRoles": null,
        "RemovedRoles": null,
        "Locations": [
          {
            "IsEnabled": false,
            "Id": "00000000-0000-0000-0000-000000000000",
            "Name": "ALL"
          }
        ],
        "AddedLocation": null,
        "RemovedLocation": null,
        "WorkGroups": [
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "3b30a38e-6ddb-4b73-b580-36436c8bd31c",
            "Name": "Operator 1"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "d8f6a130-2c4f-4337-93d7-a46f2b034b2d",
            "Name": "FSQA"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "27515ef8-5ac5-499d-bb1d-ab2d90a8a7d1",
            "Name": "R&D"
          },
          {
            "WorkGroupUsers": null,
            "IsEnable": false,
            "GetEnabledWorkgroup": false,
            "AddedWorkGroupUsers": null,
            "RemovedWorkGroupUsers": null,
            "IntegerId": 0,
            "Id": "40d5b4a3-cbca-43d6-a078-b2e2f947d885",
            "Name": "Category Manager"
          }
        ],
        "AddedWorkGroups": null,
        "RemovedWorkGroups": null,
        "IsAdmin": false,
        "UserType": 0,
        "Partner": null,
        "FullName": "Test User1",
        "Upn": "TestUser1",
        "Name": "Test User1",
        "Status": "Active",
        "HasAllLocations": true,
        "HasAllSuppliers": false,
        "PasswordPolicy": null,
        "PartnerRefs": [
          
        ],
        "AddedPartnerRefs": null,
        "RemovedPartnerRefs": null,
        "Pin": null,
        "EmployeeId": "79996",
        "Phone": "",
        "DefaultLocation": {
          "IsEnabled": false,
          "Id": "3ce94133-d81d-4986-a18f-2a4e0ad75012",
          "Name": "Los Angeles - 90024"
        },
        "SecurityLevel": "0"
      }
    ]
  },
  "RequestError": null,
  "DetailedError": null,
  "Status": true,
  "Errors": null,
  "RefreshToken": false
}

Response Parameters

Name	Description
RequestID	Use this GUID within our GetBatchStatus API to request updates on when the request will be processed outside of the UI. See Request Status API documentation.
RequestStatus	If no syntax errors are present the default response is Pending until the request can be processed.
RequestError	Error object providing information if an error occurs
Status	Indicating the success of the API request

Response JSON

{
    "RequestId": "91d9ad28-8759-4ccd-b401-a4ea0c32ed19",
    "RequestStatus": "Pending",
    "RequestError": null,
    "Status": true,
    "Errors": null,
    "RefreshToken": false
}

Additional Request JSON Examples

Minimum Required Parameters

{
    "Data": {
        "Users": [{    
            "Title": "",
            "FirstName": "Jane",
            "LastName": "Doe",
            "Username": "jdoe",
            "Email": "[email protected]",
            "TimeZone": {
                "Id": "US/Pacific",
                "DisplayName": "U.S. Pacific"
            },
            "Roles": [{
                "Name": "Analytics"
            }],
            "Locations": [{
                "Name": "ALL"           
            }],
            "WorkGroups": [{
                "Name": "Test"
            }],
            "UserType": 0,
            "Status": 1
        }]
    },
    "Operation": "Insert",
    "Status": true,
    "Errors": null,
    "RefreshToken": false,
    "PartialSuccess": false
}

Request with Multiple Roles

{
    "Data": {
        "Users": [{
            "Title": "",
            "FirstName": "Jane",
            "LastName": "Doe",
            "Username": "jdoe",
            "Email": "[email protected]",
            "TimeZone": {
                "Id": "US/Pacific",
                "DisplayName": "U.S. Pacific"
            },
            "Roles": [{
                "Name": "Analytics"
            }],
              "Roles": [{
                "Name": "Op Checks"
            }],
            "Locations": [{
                "Name": "ALL"            
            }],
            "WorkGroups": [{
                "Name": "Test"
            }],
            "UserType": 0,
            "Status": 1
        }]
    },
    "Operation": "Update",
    "Status": true,
    "Errors": null,
    "RefreshToken": false,
    "PartialSuccess": false
}

Request with Employee ID

{
    "Data": {
        "Users": [{
            "Title": "",
            "FirstName": "Jane",
            "LastName": "Doe",
            "Username": "jdoe",
            "Email": "[email protected]",
            "EmployeeId": "45465888",
            "TimeZone": {
                "Id": "US/Pacific",
                "DisplayName": "U.S. Pacific"
            },
            "Roles": [{
                "Name": "Analytics"
            }],
              "Roles": [{
                "Name": "Op Checks"
            }],
            "Locations": [{
                "Name": "ALL"          
            }],
            "WorkGroups": [{
                "Name": "Test"
            }],
            "UserType": 0,
            "Status": 0
        }]
    },
    "Operation": "Insert",
    "Status": true,
    "Errors": null,
    "RefreshToken": false,
    "PartialSuccess": false
}

Workflow

The recommended workflow for this series of APIs is as follows:

Use the login token API, /api/account/login, to obtain the authorization JWToken that will be passed to the subsequent call. The authorization token will remains active for 5 minutes.
Use the getUsers API to pull the format for the request JSON.
Modify the response JSON from the getUsers request.
Use the login token API, /api/account/login, to obtain the authorization JWToken that will be passed to the subsequent call.
Use AddUpdateUsers to submit the modified getUsers response jsJSONon to apply adds/changes. When the request is submitted retain the request Id returned from AddUpdateUsers as this will be used with the API GetBatchStatus.
Use GetBatchStatus to check the status of the AddUpdateUsers submission or the status is also visible in the UI, under Admin, Provisioning, Import.

See GetBatchStatusAPI documentation for more information.

Refer to screenshot below:

The colored dots within the UI track the status of the import:

Color	Status
Grey	Request is pending in the queue for processing
Blue	Request is in process
Red	Request encountered an error
Green	Request was successful