Skip to main content

Recommendation API

Preview
This feature is in preview. It is being refined with early feedback, so its screens and behavior may change between releases, and it may need to be switched on for your organization before it appears. See experimental features for how preview works in Dime.Scheduler.

The RecommendationRecommendationA ranked suggestion of resources for a job, matched on skills, location and availability. Available through the API and through the MCP server’s recommendation tool. API supports planning automation and optimization. It finds available time slots for resourcesResourceAn entity that can carry out work - a person, vehicle, tool, or room - that you schedule on the planning board. 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. skillsSkillA qualification a resource holds and a task can require, typically modeled as a filter group. Skills drive resource filtering, the project team view and the solver’s choice of who can do what., regions).
  • location: object containing:
    • address: address string.
    • country: country code.
  • options: optional configuration object:
    • locationMode: e.g. home to use the resource's home addressHome addressThe address where a resource starts and ends the day. The map plots resources on it when live locations are hidden, and a round trip uses it as the fixed start and end..
    • 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"
    }
}'

Scorers​

The slots that come back are ranked by a set of scorers, and the optional scoring.weights object in the request lets you decide how much each one counts: it maps a scorer key to a weight, unknown keys are rejected, and the weights are normalized on the server, so only their ratio matters.

GET /recommendation/scorers returns the catalog of scorers you can weight: each entry has its key, a description of what it rewards, and the request fields it needs to be able to score at all (a distance scorer is useless without a location, for example). Call it once to see which keys this version offers rather than hard-coding them. See the REST API reference.

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
}

Read more​

Last updated on by Hendrik Bulens