How to upload your HR data using the REST API

WARNING

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 file

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

Step 2 - Verify your file

BEFORE you post your file, you should always verify that it is correctly structured and contains valid data (e.g. a valid email address format). This will avoid your file 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 position 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.

NOTE

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 file 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 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

NOTE

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.)

Notifications

A non critical notification will be 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.

WARNING

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.

Troubleshooting

Please see the following articles:

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

Comments

0 comments

Please sign in to leave a comment.

Have more questions?
Submit a request