How to upload your HR data using the REST API

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:

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

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.

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

• 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

Notifications

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.

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