Visit requirements

Sometimes a specific technician is required to handle a customer visit. For instance, the visit might be one in a series of related customer visits that all need to be performed by the same technician.

There are also times a specific technician is preferred, for instance, if the customer had a positive experience with a technician and has requested them for a new visit.

If the experience was bad, a customer might want to exclude a specific technician from visiting them again.

This guide explains visit requirements with the following examples:

Prerequisites

To run the examples in this guide, you need to authenticate with a valid API key for this model:

  1. Log in to Timefold Platform: app.timefold.ai.

  2. From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.

  3. Create a new API key or use an existing one. Ensure the list of models for the API key contains the current model.

In the examples, replace <API_KEY> with the API Key you just copied.

1. Vehicles required by a visit

For a customer visit that must be handled by specific technicians, for instance, Beth or Carl, specify the list of required vehicle IDs (not vehicle shifts) in the visit’s requiredVehicles attribute:

{
  "visits": [
    {
      "id": "Visit A",
      "location": [33.77301, -84.43838],
      "serviceDuration": "PT1H30M",
      "requiredVehicles": [ "Beth", "Carl" ]
    }
  ]
}

If the requiredVehicles list is empty or not specified, the visit can be assigned to any vehicle’s shift.

Any solution that assigns the visit to a vehicle ID that is not "Beth" or "Carl" will be penalized for breaking a hard constraint.

Learn about the hard and soft constraints in the Field Service Routing model.

Below is an example dataset with three vehicles and one visit that can only be assigned to Beth’s or Carl’s shifts:

  • Input

  • Output

Try this example in Timefold Platform by saving the JSON into a file called required-vehicles-example-1.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]
{
  "config": {
    "run": {
      "name": "Required vehicles example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T12:30:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T12:30:00Z",
            "maxEndTime": "2027-02-01T16:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit A",
        "location": [33.77301, -84.43838],
        "serviceDuration": "PT1H30M",
        "requiredVehicles": [ "Beth", "Carl" ]
      }
    ]
  }
}
To request the solution, locate the ID from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>
{
  "run": {
    "id": "ID",
    "name": "Required vehicles example",
    "submitDateTime": "2024-07-15T04:39:34.792750944Z",
    "startDateTime": "2024-07-15T04:39:40.233674574Z",
    "activeDateTime": "2024-07-15T04:39:40.333674574Z",
    "completeDateTime": "2024-07-15T04:39:42.884169539Z",
    "shutdownDateTime": "2024-07-15T04:39:42.984169539Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-8soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit A",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:00:04Z",
                "startServiceTime": "2027-02-01T09:00:04Z",
                "departureTime": "2027-02-01T10:30:04Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT4S",
                "travelDistanceMetersFromPreviousStandstill": 25336,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT8S",
              "travelTimeFromStartLocationToFirstVisit": "PT4S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT4S",
              "totalTravelDistanceMeters": 50672,
              "travelDistanceFromStartLocationToFirstVisitMeters": 25336,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 25336,
              "endLocationArrivalTime": "2027-02-01T10:30:08Z"
            }
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T12:30:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null
            }
          }
        ]
      }
    ]
  },
  "kpis": {
    "totalTravelTime": "PT8S",
    "travelTimeFromStartLocationToFirstVisit": "PT4S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT4S",
    "totalTravelDistanceMeters": 50672,
    "travelDistanceFromStartLocationToFirstVisitMeters": 25336,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 25336,
    "totalUnassignedVisits": 0
  }
}

modelOutput contains the itineraries with Visit A assigned to Beth.

In this example, Ann’s shift startLocation is very close to Visit A, so assigning the visit to Ann would result in minimal travel time and is a more optimal schedule. However, because Visit A requires Beth or Carl, Beth is assigned instead of Ann.

This example illustrates that requirements for specific vehicles might result in a suboptimal schedule compared to a solution where any technician could be assigned the visit.

visit assignment required vehicles

2. Vehicles preferred by a visit

When a customer visit prefers a specific technician (or technicians) to handle the visit, for instance, Beth or Carl, specify the list of required vehicle IDs (not vehicle shifts) in the visit’s preferredVehicles attribute:

{
  "visits": [
    {
      "id": "Visit A",
      "location": [33.68786, -84.18487],
      "serviceDuration": "PT1H30M",
      "preferredVehicles": [ "Beth", "Carl" ]
    }
  ]
}

If the preferredVehicles list is empty or not specified, the visit can be assigned to any vehicle’s shift.

If the visit is not assigned to either "Beth" or "Carl" a soft penalty will be added to the run score.

Timefold is incentivized to use solutions with the best score.

Learn about the hard and soft constraints in the Field Service Routing model.

Below is an example dataset with three vehicles and one visit that would prefer Beth or Carl attend the visit:

  • Input

  • Output

Try this example in Timefold Platform by saving the JSON into a file called preferred-vehicles-example-1.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]
{
  "config": {
    "run": {
      "name": "Preferred vehicles example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T12:30:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit A",
        "location": [33.68786, -84.18487],
        "serviceDuration": "PT1H30M",
        "preferredVehicles": [ "Beth", "Carl" ]
      }
    ]
  }
}
To request the solution, locate the ID from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>
{
  "run": {
    "id": "ID",
    "name": "Preferred vehicles example",
    "submitDateTime": "2025-05-06T06:49:42.714207787Z",
    "startDateTime": "2025-05-06T06:49:52.950624789Z",
    "activeDateTime": "2025-05-06T06:49:58.242247685Z",
    "completeDateTime": "2025-05-06T07:19:58.346135957Z",
    "shutdownDateTime": "2025-05-06T07:20:03.561854806Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-3825soft",
    "tags": [
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null,
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit A",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:29:43Z",
                "startServiceTime": "2027-02-01T09:29:43Z",
                "departureTime": "2027-02-01T10:59:43Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT29M43S",
                "travelDistanceMetersFromPreviousStandstill": 34030,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT59M31S",
              "travelTimeFromStartLocationToFirstVisit": "PT29M43S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT29M48S",
              "totalTravelDistanceMeters": 65532,
              "travelDistanceFromStartLocationToFirstVisitMeters": 34030,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 31502,
              "endLocationArrivalTime": "2027-02-01T11:29:31Z",
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T12:30:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null,
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      }
    ]
  },
  "inputMetrics": {
    "visits": 1,
    "visitGroups": 0,
    "vehicles": 3,
    "mandatoryVisits": 1,
    "optionalVisits": 0,
    "vehicleShifts": 3
  },
  "kpis": {
    "totalTravelTime": "PT59M31S",
    "travelTimeFromStartLocationToFirstVisit": "PT29M43S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT29M48S",
    "totalTravelDistanceMeters": 65532,
    "travelDistanceFromStartLocationToFirstVisitMeters": 34030,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 31502,
    "totalUnassignedVisits": 0,
    "totalAssignedVisits": 1,
    "assignedMandatoryVisits": 1,
    "assignedOptionalVisits": 0,
    "totalActivatedVehicles": 1,
    "workingTimeFairnessPercentage": 0.0,
    "totalTechnicianCosts": null,
    "totalOvertime": null
  }
}

modelOutput contains the itineraries with Visit A assigned to Beth.

3. Vehicles prohibited by a visit

It is also possible that a customer doesn’t want to be served by a specific technician (or technicians). This can be based on experiences or other reasons that excluded the technician from the visit. To specify the list of vehicle IDs (not vehicle shifts) that are prohibited from handling the visit, use the visit’s prohibitedVehicles attribute:

{
  "visits": [
    {
      "id": "Visit A",
      "location": [33.68786, -84.18487],
      "serviceDuration": "PT1H30M",
      "prohibitedVehicles": [ "Carl" ]
    }
  ]
}

If the prohibitedVehicles list is empty or not specified, the visit can be assigned to any vehicle’s shift.

The list of prohibited vehicles is a hard constraint. Any solution that assigns the visit to a vehicle ID that is in the prohibitedVehicles list will be penalized for breaking a hard constraint.

Learn about the hard and soft constraints in the Field Service Routing model.

Below is an example dataset with three vehicles and one visit that cannot be assigned to Carl’s shift:

  • Input

  • Output

Try this example in Timefold Platform by saving the JSON into a file called prohibited-vehicles-example-1.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans [email protected]
{
  "config": {
    "run": {
      "name": "Prohibited vehicles example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startLocation": [33.77301, -84.43899],
            "minStartTime": "2027-02-01T12:30:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit A",
        "location": [33.68786, -84.18487],
        "serviceDuration": "PT1H30M",
        "prohibitedVehicles": [ "Carl" ]
      }
    ]
  }
}
To request the solution, locate the ID from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/field-service-routing/v1/route-plans/<ID>
{
  "run": {
    "id": "ID",
    "name": "Prohibited vehicles example",
    "submitDateTime": "2025-05-13T14:57:24.342067+02:00",
    "startDateTime": "2025-05-13T14:57:24.363099+02:00",
    "activeDateTime": "2025-05-13T14:57:24.425335+02:00",
    "completeDateTime": "2025-05-13T14:57:54.44669+02:00",
    "shutdownDateTime": "2025-05-13T14:57:54.462331+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-54577soft",
    "tags": null,
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit A",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:30:24Z",
                "startServiceTime": "2027-02-01T09:30:24Z",
                "departureTime": "2027-02-01T11:00:24Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT30M24S",
                "travelDistanceMetersFromPreviousStandstill": 25336,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H48S",
              "travelTimeFromStartLocationToFirstVisit": "PT30M24S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT30M24S",
              "totalTravelDistanceMeters": 50672,
              "travelDistanceFromStartLocationToFirstVisitMeters": 25336,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 25336,
              "endLocationArrivalTime": "2027-02-01T11:30:48Z",
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null,
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      },
      {
        "id": "Carl",
        "shifts": [
          {
            "id": "Carl-2027-02-01",
            "startTime": "2027-02-01T12:30:00Z",
            "itinerary": [],
            "metrics": {
              "totalTravelTime": "PT0S",
              "travelTimeFromStartLocationToFirstVisit": "PT0S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT0S",
              "totalTravelDistanceMeters": 0,
              "travelDistanceFromStartLocationToFirstVisitMeters": 0,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 0,
              "endLocationArrivalTime": null,
              "technicianCosts": null,
              "overtime": null
            }
          }
        ]
      }
    ]
  },
  "inputMetrics": {
    "visits": 1,
    "visitGroups": 0,
    "vehicles": 3,
    "mandatoryVisits": 1,
    "optionalVisits": 0,
    "vehicleShifts": 3
  },
  "kpis": {
    "totalTravelTime": "PT1H48S",
    "travelTimeFromStartLocationToFirstVisit": "PT30M24S",
    "travelTimeBetweenVisits": "PT0S",
    "travelTimeFromLastVisitToEndLocation": "PT30M24S",
    "totalTravelDistanceMeters": 50672,
    "travelDistanceFromStartLocationToFirstVisitMeters": 25336,
    "travelDistanceBetweenVisitsMeters": 0,
    "travelDistanceFromLastVisitToEndLocationMeters": 25336,
    "totalUnassignedVisits": 0,
    "totalAssignedVisits": 1,
    "assignedMandatoryVisits": 1,
    "assignedOptionalVisits": 0,
    "totalActivatedVehicles": 1,
    "workingTimeFairnessPercentage": 0.0,
    "totalTechnicianCosts": null,
    "totalOvertime": null
  }
}

modelOutput contains the itineraries with Visit A assigned to Ann.

Next