How to upload your HR data using the REST API


This process is highly technical and will require someone to create one or more automated scripts (using whatever programming language you prefer).

Step 1 - Create your files

The first step is to create an employee file and positions file (where appropriate) that includes every Active employee. For more information about the file formats, see:

Step 2 - Verify your files

BEFORE you post your files, you should always verify that they are correctly structured and contain valid data (e.g. a valid email address format) for every Active employee. This will avoid your files being rejected. To do this:

  • Call our REST API to retrieve the appropriate XSD schema file (see below)
  • Use an appropriate function (in your preferred programming language) to check it validates against the schema

To download the appropriate schema, see the following endpoints in the REST API article:

  • For employee schema, refer to "GET /admin/api/v2/hrdatasync/employees.xsd"
  • For position schema, refer to "GET /admin/api/v2/hrdatasync/positions.xsd"

If you are providing a positions file (hierarchy) you should also check the hierarchy is valid otherwise your file will be rejected. In a valid hierarchy, employees report all the way up to the MD/CEO.


How to validate an XML file against a schema is outside the scope of this document as it differs depending on which programming language you use. However, XML is a widely used file format and the internet contains many examples of how to validate them against a schema.

Step 3 - Post your files to our REST API

For more information, see the following endpoints in the REST API article:

  • For employee files, refer to "POST /admin/api/v2/hrdatasync/employee"
  • For position files, refer to "POST /admin/api/v2/hrdatasync/position"

Step 4 - System Validation (Schema)

Once the file has been successfully received it will be validated against the same schema file you used in step 2.

  • If the files doesn’t validate against the schema, the ENTIRE FILE will be rejected, NO CHANGES will be made to the data we store
  • If the file validates against the schema, it will be queued for processing

Step 5 - Processing & Data Checks


Employee files will always be processed ahead of position files. This ensures the employee exists when they are assigned to a position.

  • The data processor runs every 5-15 minutes and automatically collects any queued files
  • The file is processed record by record and if an issue is detected ONLY THAT RECORD will be skipped and file processing will continue
  • If there are any errors/warnings an exception file will be generated to help you resolve any issues.
  • The employee data and positions will be updated appropriately, and any actions taken (e.g. employees added, employees removed, hierarchy changes applied, etc.)
  • Every sync cycle must sync your entire HRIS roster of Active employees; Any employee excluded from the employee file will be automatically deleted from the recognition platform


A non-critical notification will be added to the administration portal for the Primary Administrator and any Technical administrators at the validation and processing steps. An email will also be sent when a notification is added.


However, if any serious errors are found it will generate a critical notification which must be confirmed as read. Please ensure administrators are aware to check and confirm them as they indicate there is a problem with your data which WILL affect your program.


Please see the following articles:

Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.

Have more questions?
Submit a request