Recommendation API

Status: Preview

The Recommendation API is in preview. Functionality, request/response shape, and behavior may change between releases. Not recommended for production yet.

The Recommendation API supports planning automation and optimization. It finds available time slots for resources based on location, requirements, and other constraints. The API will evolve based on feedback before production release.

Endpoint

POST /recommendation

For the full reference, 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).
• endDate: end date for the search window (ISO 8601).
• duration: duration of the appointment (ISO 8601 duration, 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: e.g. home to use the resource's home address.
  • maxDistanceKm: maximum distance in kilometers.
  • granularity: time slot granularity (ISO 8601 duration, 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).
  • end: end time of the slot (ISO 8601).
  • 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
}