Stage Authentication Data
This endpoint process the authentication data and stages it in a "file/batch" for further review and approval. The batch is identified by the value of the "fileLogId" parameter.
Below is the example POST request sent to the /api/admin/authdata/stage endpoint
POST https://developer.q1.paperlessemployee.com/api/admin/authdata/stageHeaders
Content-Type: application/json
Authorization: bearer {token}
Body
{"fileLogId": "8375fb13-cce4-4cf1-8280-7bad9e6cb16f","validate": true, "allowNoAuth": false, "commit": true, "employee": [{ "employeeId": "string", "employeeStatus": "string", "authValue1": "string", "authValue2": "string", "authValue3": "string" }] }
The list of the fields are as follows. Required fields have been marked with *
The response will contain the status code and a summary of the changes as shown below:
{ "fileLogId": "8375fb13-cce4-4cf1-8280-7bad9e6cb16f", "totalNew": 0, "totalRecords": 1, "totalUpdates": 1, "totalErrors": 0, "totalNoChange": 0, "totalEmpIdUpdate": 0, "totalAuthValueChange": 1, "totalStatusChange": 1, "totalDuplicates": 0, "duplicateAuthValues": [], "thresholdExceptions": [], "errorDetails": [], "employeeDetails": [ { "Key": "tft1636662465", "Value": "Auth Value Updated" } ]}A breakdown of each of the above elements in the response is as follows:
"totalRecords" : 1
All incoming data is first scrubbed. This makes sure blanks and missing fields are handled consistently and removes any records that contain no data. The number of remaining records is reported here as ‘totalRecords’.
"fileLogId": "00000000-0000-0000-0000-000000000000"
When no value is supplied, the system will generate a new Guid as the data is committed to the staging table.
When a value is supplied, data can be added to an existing ‘batch’ with the same ID. Data is saved to the staging table until the ‘Process’ endpoint is called which must be supplied with this ID. Calling the endpoint repeatedly with this ID will cause all records to be appended to the batch.
"totalNew": 0, "totalUpdates": 1, "totalErrors": 0, "totalNoChange": 0, "totalDuplicates": 0
These five properties allow a way to reconcile the incoming authentication data. Every record will fit into one of these categories, so the total of these 5 will always add up to the total records above.
Authentication values where all values are the same as previously stored are indicated as ‘no change’.
No further processing occurs for two types of authentication values: those with errors, and those where no change has occurred. Error records are skipped, and if a defined error threshold is exceeded, the entire batch is cancelled.
For duplicate records, only the last record that has the most data is processed.
"totalEmpIdUpdate": 0, "totalAuthValueChange": 0, "totalStatusChange": 0
These 3 fields provide an additional reality check.
totalEmpIdUpdate – Auth values are the same, but user has a new employee Id.
totalAuthValuesChange – Employee ID stays the same, but user has new auth values.
totalStatusChange – both Employee ID and AuthValues are the same, but the employment status has changed.
"duplicateAuthValues": []
An array of employee Ids and Auth Values that were skipped due to being duplicated in this set of authentication data.
"thresholdExceptions":[]
If thresholds are defined and exceeded, this array returns information about each threshold. Possible values:
Number of added employees exceeds threshold: {X}%. Processing has stopped.
Number of employees with updates exceeds threshold: {X%. Processing has stopped.
Number of records with errors exceeds threshold: {X}%. Processing has stopped.
"errorDetails": [{“line”=X, “value”=”error”}] Every error that occurred is returned in this array, indexed by the line number within submitted authentication values.
"employeeDetails": [{ "Key": "{employeeID}", "Value": "New / Update / Error / No Change" }]This array contains one record for each processed record with the employee ID as the key, and the processing category as the value. Possible values are Error, No Change, Employee Id Updated and New Record.