Articles in this section

See more

Person Register API

  • Updated

This article explains how to use the Assure Customer API (a secure RESTful API that enables automated integration with Assure) to create, update, and delete Person Register records (the records held in Assure's People and Training module that store personal, employment, and next of kin information for individuals in your organisation). It covers what the API can and cannot do, the minimum required fields, the full list of optional fields, what is out of scope, 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 People and Training module within Assure.

 

Prerequisites

Before using the Customer API to manage Person Register records, confirm the following are in place:
  • API access is enabled - The API functionality must be enabled by the Evotix team before you can use it. Contact your CDM (Customer Development Manager) or CSM (Customer Success Manager) to request access. [shesoftwar...endesk.com]
  • API authentication keys are generated - You can create and manage your API authentication keys at any time in Assure. Refer to the API Key Management article for details. [shesoftwar...endesk.com]
  • Person Register Reference values are known - The Person Register reference field cannot be automatically assigned by the system when creating or updating records; it must be provided in the requests. References must be determined and available before any API call is made. [shesoftwar...endesk.com]
  • Caption maintenance mandatory fields are identified - In addition to the standard minimum required fields, any other fields which you have set as a mandatory requirement in the Person Register caption maintenance must also be supplied in the request. [shesoftwar...endesk.com]
  • Technical resource is available - Making use of the Customer API requires a level of technical expertise, so this is typically something that a company's IT function would handle.
     

Overview

The Assure Customer API can be used to automate the processes of managing Person Register records 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. Making use of the Customer API requires a level of technical expertise, so this is typically something that a company's IT function would handle. The API functionality must be enabled by the Evotix team before you can use it. Please contact your CDM (Customer Development Manager) or CSM (Customer Success Manager) should you be interested in procuring this feature.

 

What Can the Customer API Do?

With the Customer API you can:

  • Create new Person Register records
  • Update existing Person Register records (including marking a person as ‘not current’)
  • Delete Person Register records

Each of these operations requires you to make a request to the Customer API. A detailed user guide and supporting API schema is available, this detailing the API methods and the information required to use them.

 
Required and Optional Fields

The minimum required fields are:

  • Org Unit
  • Reference
  • Forename (First Name)
  • Surname (Last Name)
  • Plus any other fields which you have set as a mandatory requirement in the Person Register caption maintenance.

Other fields that can be set and will be defaulted if not supplied:

  • Linked User Name
  • Email
  • Current
  • Date of Birth
  • Title
  • Job Title
  • Is Confidential
  • Marital Status
  • NI Number (Social Security Number)
  • Nationality
  • Shift
  • Occupation
  • Date of Hire
  • Phone
  • Mobile
  • Type of Person
  • Manager Name
  • Manager Phone
  • Age Range
  • Address
  • Address 2
  • Address 3 (City, State)
  • Town
  • County
  • Postcode (Zip Code)
  • Location
  • Locality 
  • Next of Kin Name
  • Next of Kin Address 1
  • Next of Kin Address 2
  • Next of Kin Address 3 (Next of Kin City, State)
  • Next of Kin Town
  • Next of Kin County
  • Next of Kin Postcode (Next of Kin Zip Code)
  • Next of Kin Phone
  • Next of Kin Relationship
  • Next of Kin Mobile (Next of Kin Cell)
  • Next of Kin Email
  • Notes
  • User Field 1
  • User Field 2

 

Out of Scope

The following elements are currently out of scope:
  • Person Register Reference field changes - The Person Register reference field cannot be changed via the API. You can only create new records with a unique reference, or update records where there is an existing record for the reference provided.
  • Automatic reference assignment - The Person Register reference field cannot be automatically assigned by the system when creating or updating records. The reference must be provided in all requests.
  • Supporting items - Actions, attachments, notes, reviews, and links to policies and guidance cannot be added via the API. If default reviewers and approvers are configured, they will be automatically applied on record creation.
  • Project links - It is not possible to add Project records to Person Register records in the Project Links section via the API. Project records must be linked manually in Assure.
  • Caption maintenance default values - Any default values set within the caption maintenance area are not taken into consideration by the API


Setting Up the API

  1. Before you can get started you need to request access from Evotix through your Customer Development or Customer Success Manager.
  2. You can create and manage your API authentication keys at any time in Assure. Check out this article for details API Key Management Article
  3. Set up the Customer API. Access the user guide here Assure Customer API User Guide
  4. Set up the Person Register API. Access the user guide here Customer API User Guide-Person Register API

 

API Method Reference

The Customer API allows the updating of Person Register records in Assure using the /v1/person-register API method with the POST verb. The Person Register record details are supplied in the body of the API request using the Person Register JSON POST object.

 

AI Metadata

  • Product Area: Assure - People and Training module, Person Register, Customer API
  • User Role: Technical Administrator (IT function), Assure System Administrator, HR Administrator; requires API access enabled by Evotix
  • Tags: Person Register API, Customer API, RESTful API, create person record, update person record, delete person record, People and Training, Person Register, not current, caption maintenance, mandatory fields, Org Unit, TNA Template, API key, ETL, integration
  • Version/Region: All Assure versions; all regions
  • Important Synonyms:
    • Person Register = People Register = Person Record = People module record
    • Customer API = Assure Customer API = RESTful API
    • Org Unit = Organisational Unit
    • CDM = Customer Development Manager
    • CSM = Customer Success Manager
    • Not Current = Deactivated = Marked as not current
    • Caption Maintenance = Caption configuration = field label configuration
    • NI Number = National Insurance Number = Social Security Number (US)
    • Postcode = Zip Code (US)
    • Next of Kin Mobile = Next of Kin Cell (US)
    • Address 3 = City / State (US)
  • Suggested Embedding Keywords: Person Register API Assure, create person record API, update person record API, delete person record API, Person Register Customer API, People module API Assure, mark person not current API, Assure People API setup, Person Register mandatory fields API, Person Register optional fields API, API person record Org Unit, next of kin fields API Assure, TNA template person register API
  • Relevant Modules and Cross-Module Implications: This article is scoped to the People and Training module in Assure, specifically the Person Register. Person Register records created or updated via the Customer API can be linked to Assure User accounts (when People User Linking is enabled in System Settings). If a Person Register record is linked to a User managed via the SCIM API, many Person Register fields become read-only in the Assure UI and can only be updated via SCIM. TNA Templates (Qualifications / Job Role Templates) can be assigned to Person Register records via the API, which triggers automatic creation of Training Needs Analysis (TNA) records and Training Records. Supporting items (Actions, Attachments, Notes, Reviews, and Policy links) cannot be created via the API and must be managed manually in Assure.
Return to top

Related articles