Recommendation API

Status: Preview

This feature is currently in preview and available for testing in the sandbox environment.

A new recommendation API launched in preview mode to support planning automation and optimization. This API helps find available time slots for resources based on location, requirements, and other constraints. The API will evolve based on feedback before production release.

API Endpoint

The Recommendation API is available at:

POST /recommendation

For detailed API documentation, see the API Reference.

Request Format

The API accepts a JSON request with the following parameters:

• startDate: Start date for the search window (ISO 8601 format)
• endDate: End date for the search window (ISO 8601 format)
• duration: Duration of the appointment (ISO 8601 duration format, e.g., "PT1H" for 1 hour)
• requirements: Array of requirement filters (e.g., skills, regions)
• location: Object containing:
  • address: Address string
  • country: Country code
• options: Optional configuration object:
  • locationMode: Location mode (e.g., "home" to use resource's home address)
  • maxDistanceKm: Maximum distance in kilometers
  • granularity: Time slot granularity (ISO 8601 duration format, e.g., "PT15M" for 15 minutes)
  • timeZone: Time zone identifier (e.g., "Europe/Brussels")

Example Request

curl --location 'https://sandbox.api.dimescheduler.com/recommendation' \
--header 'content-type: application/json' \
--header 'X-Requested-With: XMLHttpRequest' \
--header 'X-API-KEY: DS-XXXX-XXXX-XXXXX' \
--data '{
    "startDate": "2025-12-22T00:00:00",
    "endDate": "2025-12-22T23:59:59",
    "duration": "PT1H",
    "requirements": [
        "WEST"
    ],
    "location": {
        "address": "The customer's address",
        "country": "DE"
    },
    "options": {
        "locationMode": "home",
        "maxDistanceKm": 100,
        "granularity": "PT15M",
        "timeZone": "Europe/Brussels"
    }
}'

Response Format

The API returns a JSON object containing:

• slots: Array of available time slots, each containing:
  • start: Start time of the slot (ISO 8601 format)
  • end: End time of the slot (ISO 8601 format)
  • resourceNo: Resource number/identifier
  • resourceName: Resource name
  • distance: Distance in kilometers from the resource's location to the appointment location
• totalSlots: Total number of slots found
• resourceCount: Number of unique resources with available slots

Example Response

{
    "slots": [
        {
            "start": "2025-12-23T08:00:00Z",
            "end": "2025-12-23T09:00:00Z",
            "resourceNo": "JEANNE",
            "resourceName": "Jeanne De Gant",
            "distance": 23.32
        },
        {
            "start": "2025-12-23T08:00:00Z",
            "end": "2025-12-23T09:00:00Z",
            "resourceNo": "WILLIAM",
            "resourceName": "William Wallonia",
            "distance": 85.17
        }
    ],
    "totalSlots": 63,
    "resourceCount": 3
}