How to upload your HR data using the REST API

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:

• For employee file format - see XML File Format (Employees)
• For position file format - see XML File Format (Positions)

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.

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

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

Troubleshooting

Please see the following articles:

• How to view your HR Data Sync files and troubleshoot any issues
• Employees - Error File Messages
• Positions - Error File Messages