Data Upload

The initial step in utilizing TimeDetect is to upload a dataset of approved time registrations.

Our machine learning model learns what patterns are considered normal based on historical data. That is why it makes sense to upload only approved registrations, as they represent the actual work pattern for an employee.

Within this documentation, the term Tenant, which is indicated by your unique tenantId, refers to the partner integrating with the TimeDetect API. This ID is chosen by you, and should be the same as the clientID you got in the authentication step.

Client Operations

The procedure for data uploading is as follows:

• Get Presigned URL: Call GET /presigned_url with the Client ID and Tenant ID in the header. You will receive a presigned url and a Job ID in response.
• Create JSON File: Formulate a JSON file containing the Datasets with approved time registrations, adhering to the request body of PUT /[presigned url].
• Send PUT Request: Issue a PUT request to the presigned url with the JSON file in the body.
• Check Status: Use GET /status with the Job ID in the header until it returns 200 with status="success", or utilize the webhook functionality described in webhook section.

After initiating the PUT request, the service begins validating and refining the uploaded data. This validation ensures compliance with the required schema. If data for any Dataset is invalid, the job status is updated, and no data is stored. The refinement process assesses existing data for each Dataset ID, replaces duplicates, and stores new records. It's advisable for the client to regularly upload new approved registrations, such as on a weekly basis.

Example Request Body for the PUT Endpoint

When sending data to the PUT endpoint, your request body should adhere to the following JSON structure, which contains necessary details about registrations and datasets. Below is an example of how to structure your request payload:

{
  "datasets": [
    {
      "datasetId": "12345",
      "registrations": [
        {
          "registrationId": "reg-001",
          "date": "2023-01-15",
          "employeeId": "emp-123",
          "projectId": "proj-456",
          "departmentId": "dept-789",
          "workCategory": "cat-012",
          "startTime": 8.0,
          "endTime": 16.5,
          "workDuration": 8.5,
          "breakDuration": 0.5,
          "publicHoliday": false,
          "numericals": [
            {
              "type": "drivingKm",
              "value": 8
            },
            {
              "type": "overtimeHours",
              "value": 0.5
            }
          ]
        }
      ]
    }
  ],
  "webhook": {
    "webhookUrl": "https://example.com/webhook/receive",
    "webhookApiKey": "abc123apikey"
  }
}