Fair Use Policy for Bulk Data Upload Tools (KB040)

This document describes the “fair use” policy for bulk data upload tools such as the API and bulk data uploads known as KB020, and includes guidelines regarding API limits.

API

The Smartosh API is designed to facilitate data integration and synchronization between the Smart OSH platform and clients’ external systems. Its purpose is to enable:

Bidirectional exchange of information between corporate systems
Automated data updates from external sources (ERP, HRIS, management systems, etc.)
Ad hoc queries for integration with reporting or BI tools
Data synchronization with other organisational systems
Workflow automation that complements platform usage

Unintended Use

The API is not designed or offered for:

Creating alternative user interfaces that significantly replace the use of the Smart OSH web platform
Developing full applications that replicate the main functionality of Smart OSH
Replacing normal user access to the platform with exclusive API access
Continuously extracting the entire database to operate outside Smart OSH

General Principles

The Smart OSH API is available to all our clients without a fixed limit on queries or updates, under the principle of “fair use” of platform resources.

Authentication and Session Management

Authentication in the SmartOSH API is performed via HTTP Basic Authentication. On the first call, the client must authenticate using the API user credentials. The HTTP client will store the token resulting from the HTTP Authentication Challenge, and subsequent calls will be automatically authenticated.

Access credentials (username and password) can be created by the SmartOSH administrator from the platform’s administration console.

Session Management

When using Basic Authentication, the API client must maintain the session between calls. There are two equivalent methods:

Session cookies: The HTTP client automatically maintains the cookies received on the first call.
x-session header: The client captures the value of the x-session header received in the first response and resends it in all subsequent calls.

If the session is not maintained correctly:

Calls will be extremely slow
The client’s subscription performance may be compromised
The limit of simultaneous sessions will be reached

Session Limit

The API has a limit of 50 distinct session identifiers per user per hour. When this limit is exceeded, the service will reject requests with the message:

“You are using too many sessions. Please make sure that you are reusing your sessions using cookies. For more information please check the reference guide KB008.”

Common causes of session excess:

The same API user is shared by multiple real users or systems
Session identifiers are not properly preserved between calls
Session cookies are not being reused

Recommendations:

Maintain the session correctly using cookies or x-session headers
If multiple systems need simultaneous access, distribute requests among different API users
Verify that the HTTP client is configured to preserve cookies between calls

Expected Use

Data Updates

The API is designed to receive only data that has undergone actual changes. Clients must:

Send updates only when the information has effectively changed
Implement change detection logic before making API calls
NOT send repetitive updates of the same information without modifications

Technical Rate Limits

Although there is no hard total volume limit, Smart OSH implements rate controls to ensure service stability:

Maximum limit: 3,600 requests per hour (equivalent to 60 requests per minute)
Concurrent calls: 1. Parallel calls will receive a 429 status code
Protection mechanism: When the system detects a rate exceeding these values, a throttling mechanism is automatically activated to temporarily limit requests

Response Codes and Error Handling

Relevant HTTP Codes

Code	Meaning	Required Action
`200 OK`	Successful request	Continue normally
`400 Bad Request`	Usually “You are using too many sessions”	See session management
`401 Unauthorized`	Invalid credentials or expired session	Verify credentials and reauthenticate
`429 Too Many Requests`	Rate limit exceeded	Implement backoff and retry
`503 Service Unavailable`	Service temporarily unavailable	Retry with exponential strategy
`504 / 524 Gateway Timeout`	Timeout due to resource blocking	Retry after an interval

Scheduled Maintenance

Smart OSH performs periodic maintenance that may result in 503 Service Unavailable codes. Maintenance windows are notified in advance. Clients should implement retry strategies for 503 codes to handle these periods without data loss.

Locks Due to Concurrent Operations

The platform may temporarily hold or block access to certain data when:

Massive operations are running (imports, batch processes, etc.)
Other users are performing individual operations on the same resources
Intensive calculation processes are underway

During these locks, the API may experience longer response times or return 503 / 504 / 524 codes. The client should implement retries with increasing intervals.

Recommended Retry Strategies

Exponential backoff with jitter:

Retry 1: wait 1–2 seconds
Retry 2: wait 2–4 seconds
Retry 3: wait 30–60 seconds
Retry 4: wait 180–300 seconds

Codes requiring retry: 429, 503, 504, 524, network/timeout errors.

Codes that should NOT be retried automatically: 400, 401, 403, 404, 422.

Best Practices

Bulk queries with pagination — Use bulk query endpoints for large volumes. Recommended page size: 100–500 records.
Backoff strategies — Implement exponential backoff on errors or 429 / >500 responses. Add random jitter to avoid retry synchronization.
Local change detection — Maintain a record of data state in the client system. Consider using timestamps, checksums, or hashes to detect changes.
Update consolidation — Group multiple changes in a single request when the API allows. Use batch operations when available.
Appropriate timeouts — Connection: 10–30 seconds. Read: 60–100 seconds for complex operations.

Informative Headers

The API may include the following headers to monitor usage:

x-throttled — Indicates if queries are being limited by the server
x-requestsUserMinCount — Count of queries made in the last 60 seconds

Recommended Timings

For massive operations, avoid peak hours as much as possible:

Avoid: 9:00–18:00 (CET)
Prefer: 20:00–7:00 (CET) for bulk uploads
Coordinate with support for extraordinary operations

Bulk Uploads via Excel (KB020)

Purpose

Bulk upload tools using Excel files (KB020) are designed for:

Initial data migrations when implementing SmartOSH
Occasional massive updates when significant data changes occur
Incremental uploads of new records or modifications to existing records
Massive data corrections in response to identified issues

Incremental Use Principle

Uploads via KB020 should follow an incremental model, not total replacement:

Upload only records that have changed since the last upload
Include only columns with modified values when possible
NOT reload the entire database massively on a periodic basis
NOT upload files with data identical to that already existing on the platform
NOT use KB020 as the usual method for updating frequently changing data

Impact of Bulk Uploads

As with the API, each data upload via KB020 triggers validations, automatic recalculations, email notifications, workflow activations, and temporary resource locks.

Repetitive data uploads without changes generate unnecessary computational costs, overwhelm users with superfluous notifications, and may affect the overall performance of the client environment.

Inappropriate Use of KB020

Bulk upload tools must not be used to:

Replace data update functionalities available in the web interface
Perform systematic and periodic reloads of all data without effective modifications
Update records whose values have not changed
Constitute the main method of data management and maintenance instead of normal platform use

Best Practices for Batch Uploads

Excel file preparation:

Identify which records have actually changed since the last upload
Export the current state from SmartOSH if comparison is needed
Include only modified or new records with their identifying columns (ID, Key, unique code, etc.)

Recommended frequency:

Initial migrations: once when implementing
Normal updates: only when significant changes justify it
Maximum recommended frequency: one upload per day
For frequent, urgent, or single updates: use the API instead of KB020

Signs of improper use:

Daily or multiple weekly uploads of the same data
Files with thousands of records but few real changes
Scheduled automatic uploads without prior change validation generating many errors

Intervention in Cases of Abusive Use

Smartosh reserves the right to contact clients whose usage patterns:

Systematically exceed established rate limits
Generate unnecessary loads through repetitive updates without changes
Compromise overall platform performance
Do not implement adequate retry strategies

In such cases, we will work with the client to optimise their integration and ensure sustainable service use. SmartOSH reserves the right to limit or restrict API usage.

Availability and SLA

Target availability: 99.5% (excluding scheduled maintenance and functional data locks within the client’s own environment)
Technical support: Available during business hours