This article explains how to use the Assure Customer API (a secure RESTful API that enables automated integration with Assure) to create, update, and deactivate Organisational Units (Org Units; the nodes within the hierarchical structure of an organisation in Assure that group and categorise records by location, department, or area). It covers what the API can and cannot do, the minimum required fields for each operation, and the steps to set up the API. The Customer API functionality must be enabled by Evotix before use and requires a level of technical expertise. This article applies to the Organisational Configuration area of Assure.
Prerequisites
Before using the Customer API to manage Organisational Units, confirm the following are in place:
- API access is enabled - The Customer API functionality must be activated by the Evotix Support Team. Contact your Customer Development Manager (CDM) or Customer Success Manager (CSM) to request this.
- External IDs are configured for your Organisational Units - The API identifies Organisational Units using External IDs. Each Organisational Unit that needs to be managed via the API must have an External ID assigned in Assure. External IDs can be added individually via Settings > Organisational Configuration > Organisational Units > Edit Org Unit screen via clicking the cog wheel menu, or in bulk using the Org Unit import tool by uploading a CSV file.
- API authentication keys are generated - API keys must be created and managed in Assure before making any API requests. Refer to the API Key Management article for instructions.
- Technical resource is available - The Customer API requires a level of technical expertise to configure and operate. Implementation is typically handled by a company's IT function.
What is the Assure Customer API?
The Assure Customer API can be used to automate the processes of managing Organisational Units in Assure. The API is accessed via the internet as a secure RESTful API which is widely supported by integration platforms, ETL tools and all programming and scripting languages, so it can be easily set up to integrate with external systems.
How Does the Customer API Work?
With the Customer API, an administrator can perform the following operations on Organisational Units:
- Create new Organisational Units
- Update existing Organisational Units
- Deactivate Organisational Units
Each of these operations requires a request to the Customer API. A detailed user guide and supporting API schema are provided separately, detailing the API methods and the information required to use them.
What Details Have to be Provided?
Minimum Required Fields
The following fields are mandatory for every API request relating to an Organisational Unit:
- Name - the display name of the Organisational Unit
- External Organisational Unit identifier - requires External IDs to be configured for your Organisational Units
- Parent External Organisational Unit identifier - requires External IDs to be configured for your Organisational Units
Optional Fields
The following fields can be set and will be defaulted if not supplied:
- Default Users – defines users who are automatically assigned to records within the Organisational Unit, such as default approvers, reviewers, and notification recipients.
- Module Overrides – allows default users to be configured at a per-module level within the Organisational Unit. For example, a different default assignee can be set for Incident records than for Hazard Spotting records.
- Additional defined module fields – captures any additional fields configured for the Organisational Unit that are specific to individual modules. Examples include Incident Region, RIDDOR reporting fields (UK), and OSHA reporting fields (US).
Out of Scope
The following element is currently not supported by the API:
- Adding branding to Organisational Units - this includes report images and banner images. Branding must be applied manually via the Org Unit configuration in Assure.
Setting Up the API
- Before you can get started you need to request access from Evotix through your Customer Development or Customer Success Manager.
- You can create and manage your API authentication keys at any time in Assure. Check out this article for details (API Key Management Article).
- Set up the Customer API. Access the user guide here (Customer API User Guide 1 – Getting Started).
- Set up the API to manage Organisational Unit Structure. Access the user guide here (Customer API User Guide 3 – API for Org Unit Structure).
AI Metadata
Product Area: Customer API, Organisational Configuration
User Role: Technical Administrator (IT function), Assure System Administrator; requires API access enabled by Evotix
Tags: Organisational Unit, Org Unit, Customer API, API, REST, External ID, create org unit, update org unit, deactivate org unit, API integration, ETL
Version/Region: All Assure versions; all regions
Important Synonyms:
- Organisational Unit = Org Unit = Organisation Unit = org structure node
- Customer API = Assure Customer API = RESTful API
- External ID = External Identifier = Org Unit external identifier
- Deactivate = Disable Organisational Unit
- CDM = Customer Development Manager
- CSM = Customer Success Manager
Suggested Embedding Keywords: Assure Customer API, manage org units API, create organisational unit API, update organisational unit API, deactivate organisational unit, Assure API external ID, Assure REST API org unit, Assure integration org structure, Org Unit automation Assure, API for Org Unit Structure
Relevant Modules and Cross-Module Implications: This article is scoped to the Organisational Configuration area of Assure. Changes to Organisational Units via the API affect the entire Assure system. Organisational Units underpin record categorisation and user access across all Assure modules (Incident, Risk Assessment, Audit, Equipment Register, and others). Any branding assigned to Organisational Units is not manageable via this API and must be configured manually. The API also intersects with user management: the External ID assigned to an Organisational U