Real-time planning: emergency visit (preview)

This guide describes features currently available as a preview feature. If you’d like early access to this feature, please Contact us. For information about the current supported feature, see Real-time planning.

There are many situations where Real-time planning (preview) is necessary.

Sometimes emergency visits have to be added to an existing schedule.

Consider the following schedule. Ann has 3 visits scheduled, Beth has 1 visit scheduled, and an emergency visit needs to be added to the schedule.

The emergency visit is located close to Ann’s existing route, so Visit M is added to Ann’s schedule, and Visit E is reassigned from Ann to Beth.

real time planning new urgent visit

Prerequisites

Learn how to configure an API Key to run the examples in this guide:

  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. Batch schedule: emergency visit

The original schedule was generated from the following input dataset during batch planning:

  • Input

  • Output

Try this example in Timefold Platform by saving this JSON into a file called sample.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": "Original shift plan: emergency visit example"
    }
  },
  "modelInput": {
    "vehicles": [
      {
        "id": "Ann",
        "shifts": [
          {
            "id": "Ann-2027-02-01",
            "startLocation": [33.68786, -84.18487],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startLocation": [33.70474, -84.06508],
            "minStartTime": "2027-02-01T09:00:00Z",
            "maxEndTime": "2027-02-01T17:00:00Z"
          }
        ]
      }
    ],
    "visits": [
      {
        "id": "Visit A",
        "location": [33.84475, -84.63649],
        "serviceDuration": "PT1H30M"
      },
      {
        "id": "Visit E",
        "location": [33.90719, -84.28149],
        "serviceDuration": "PT1H30M"
      },
      {
        "id": "Visit B",
        "location":  [33.67590, -84.11845],
        "serviceDuration": "PT1H30M"
      },
      {
        "id": "Visit C",
        "location":  [33.76156, -84.27259],
        "serviceDuration": "PT1H30M"
      }
    ]
  }
}
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>
{
  "metadata": {
    "id": "ID",
    "parentId": null,
    "originId": "ID",
    "name": "Original shift plan: emergency visit example",
    "submitDateTime": "2025-09-11T08:02:32.197445362Z",
    "startDateTime": "2025-09-11T08:02:49.531561964Z",
    "activeDateTime": "2025-09-11T08:02:49.577201833Z",
    "completeDateTime": "2025-09-11T08:03:20.052007498Z",
    "shutdownDateTime": "2025-09-11T08:03:20.568256347Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-9351soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "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:49:00Z",
                "startServiceTime": "2027-02-01T09:49:00Z",
                "departureTime": "2027-02-01T11:19:00Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT49M",
                "travelDistanceMetersFromPreviousStandstill": 54141,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit E",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T11:59:33Z",
                "startServiceTime": "2027-02-01T11:59:33Z",
                "departureTime": "2027-02-01T13:29:33Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT40M33S",
                "travelDistanceMetersFromPreviousStandstill": 42300,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit C",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T13:48:57Z",
                "startServiceTime": "2027-02-01T13:48:57Z",
                "departureTime": "2027-02-01T15:18:57Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT19M24S",
                "travelDistanceMetersFromPreviousStandstill": 20595,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT2H7M34S",
              "travelTimeFromStartLocationToFirstVisit": "PT49M",
              "travelTimeBetweenVisits": "PT59M57S",
              "travelTimeFromLastVisitToEndLocation": "PT18M37S",
              "totalTravelDistanceMeters": 132060,
              "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
              "travelDistanceBetweenVisitsMeters": 62895,
              "travelDistanceFromLastVisitToEndLocationMeters": 15024,
              "endLocationArrivalTime": "2027-02-01T15:37:34Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit B",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:10:37Z",
                "startServiceTime": "2027-02-01T09:10:37Z",
                "departureTime": "2027-02-01T10:40:37Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT10M37S",
                "travelDistanceMetersFromPreviousStandstill": 8842,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT21M15S",
              "travelTimeFromStartLocationToFirstVisit": "PT10M37S",
              "travelTimeBetweenVisits": "PT0S",
              "travelTimeFromLastVisitToEndLocation": "PT10M38S",
              "totalTravelDistanceMeters": 17676,
              "travelDistanceFromStartLocationToFirstVisitMeters": 8842,
              "travelDistanceBetweenVisitsMeters": 0,
              "travelDistanceFromLastVisitToEndLocationMeters": 8834,
              "endLocationArrivalTime": "2027-02-01T10:51:15Z"
            }
          }
        ]
      }
    ],
    "unassignedVisits": []
  },
  "inputMetrics": {
    "visits": 4,
    "visitGroups": 0,
    "vehicles": 2,
    "mandatoryVisits": 4,
    "optionalVisits": 0,
    "vehicleShifts": 2,
    "visitsWithSla": 0
  },
  "kpis": {
    "totalTravelTime": "PT2H28M49S",
    "travelTimeFromStartLocationToFirstVisit": "PT59M37S",
    "travelTimeBetweenVisits": "PT59M57S",
    "travelTimeFromLastVisitToEndLocation": "PT29M15S",
    "totalTravelDistanceMeters": 149736,
    "travelDistanceFromStartLocationToFirstVisitMeters": 62983,
    "travelDistanceBetweenVisitsMeters": 62895,
    "travelDistanceFromLastVisitToEndLocationMeters": 23858,
    "totalUnassignedVisits": 0,
    "totalAssignedVisits": 4,
    "assignedMandatoryVisits": 4,
    "assignedOptionalVisits": 0,
    "totalActivatedVehicles": 2,
    "workingTimeFairnessPercentage": 43.72
  }
}

modelOutput contains Ann’s and Beth’s shift itineraries.

2. Real-time planning update: emergency visit

A little before midday, an emergency visit needs to be included in the plan for the same day. Visit M must be added to the schedule. Because Visit M is a high priority, it includes "priority": "4".

The following shows the required input and the patch operation that will change the original input:

  • Input

  • Patch

{
  "id": "Visit M",
  "location":  [33.89104, -84.64711],
  "serviceDuration": "PT1H30M",
  "priority": "4"
}
{
  "op": "add",
  "path": "/visits/-",
  "value": {
    "id": "Visit M",
    "location": [
      33.89104,
      -84.64711
    ],
    "serviceDuration": "PT1H30M",
    "priority": "4"
  }
}

The departure times for visits that have already occurred and that technicians have already begin traveling to can be frozen by adding freezeDeparturesBeforeTime and including the time when the freeze is implemented.

The call for the emergency visit came in a little before 12:00 so set freezeDeparturesBeforeTime to 12:00.

The following shows the required input and the patch operation that will change the original input:

  • Input

  • Patch

{
  "modelInput": {
    "freezeDeparturesBeforeTime": "2027-02-01T12:00:00Z"
  }
}
{
  "op": "add",
  "path": "/freezeDeparturesBeforeTime",
  "value": "2027-02-01T12:00:00Z"
}

Submit the full patch to modify the original input dataset to the following endpoint. Replace <ID> with the dataset ID:

v1/route-plans/<ID>/from-patch/

When submitted, solving is triggered to generate a new revision of the plan.

  • Patch

  • Output

Try this example in Timefold Platform by saving this JSON into a file called patch.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/<ID>/from-patch [email protected]
{
  "config": {
    "run": {
      "name": "Real-time planning: emergency visit example"
    }
  },
  "patch": [
    {
      "op": "add",
      "path": "/freezeDeparturesBeforeTime",
      "value": "2027-02-01T12:00:00Z"
    },
    {
      "op": "add",
      "path": "/visits/-",
      "value": {
        "id": "Visit M",
        "location": [
          33.89104,
          -84.64711
        ],
        "serviceDuration": "PT1H30M",
        "priority": "4"
      }
    }
  ]
}
To request the solution, locate the ID from the response to the patch 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>
{
  "metadata": {
    "id": "ID",
    "parentId": "ORIGIN-ID",
    "originId": "ORIGIN-ID",
    "name": "Real-time planning: emergency visit example",
    "submitDateTime": "2025-09-11T08:10:10.091873675Z",
    "startDateTime": "2025-09-11T08:10:23.101944569Z",
    "activeDateTime": "2025-09-11T08:10:23.140173251Z",
    "completeDateTime": "2025-09-11T08:10:53.602826831Z",
    "shutdownDateTime": "2025-09-11T08:10:54.118354267Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-14941soft",
    "tags": [
      "system.type:from-patch",
      "system.profile:default"
    ],
    "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:49:00Z",
                "startServiceTime": "2027-02-01T09:49:00Z",
                "departureTime": "2027-02-01T11:19:00Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT49M",
                "travelDistanceMetersFromPreviousStandstill": 54141,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit E",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T11:59:33Z",
                "startServiceTime": "2027-02-01T11:59:33Z",
                "departureTime": "2027-02-01T13:29:33Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT40M33S",
                "travelDistanceMetersFromPreviousStandstill": 42300,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit M",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T14:07:29Z",
                "startServiceTime": "2027-02-01T14:07:29Z",
                "departureTime": "2027-02-01T15:37:29Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT37M56S",
                "travelDistanceMetersFromPreviousStandstill": 38245,
                "minStartTravelTime": "2027-02-01T12:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT3H4M27S",
              "travelTimeFromStartLocationToFirstVisit": "PT49M",
              "travelTimeBetweenVisits": "PT1H18M29S",
              "travelTimeFromLastVisitToEndLocation": "PT56M58S",
              "totalTravelDistanceMeters": 198487,
              "travelDistanceFromStartLocationToFirstVisitMeters": 54141,
              "travelDistanceBetweenVisitsMeters": 80545,
              "travelDistanceFromLastVisitToEndLocationMeters": 63801,
              "endLocationArrivalTime": "2027-02-01T16:34:27Z"
            }
          }
        ]
      },
      {
        "id": "Beth",
        "shifts": [
          {
            "id": "Beth-2027-02-01",
            "startTime": "2027-02-01T09:00:00Z",
            "itinerary": [
              {
                "id": "Visit B",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T09:10:37Z",
                "startServiceTime": "2027-02-01T09:10:37Z",
                "departureTime": "2027-02-01T10:40:37Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT10M37S",
                "travelDistanceMetersFromPreviousStandstill": 8842,
                "minStartTravelTime": "2027-02-01T00:00:00Z"
              },
              {
                "id": "Visit C",
                "kind": "VISIT",
                "arrivalTime": "2027-02-01T12:24:29Z",
                "startServiceTime": "2027-02-01T12:24:29Z",
                "departureTime": "2027-02-01T13:54:29Z",
                "effectiveServiceDuration": "PT1H30M",
                "travelTimeFromPreviousStandstill": "PT24M29S",
                "travelDistanceMetersFromPreviousStandstill": 23257,
                "minStartTravelTime": "2027-02-01T12:00:00Z"
              }
            ],
            "metrics": {
              "totalTravelTime": "PT1H1M17S",
              "travelTimeFromStartLocationToFirstVisit": "PT10M37S",
              "travelTimeBetweenVisits": "PT24M29S",
              "travelTimeFromLastVisitToEndLocation": "PT26M11S",
              "totalTravelDistanceMeters": 55487,
              "travelDistanceFromStartLocationToFirstVisitMeters": 8842,
              "travelDistanceBetweenVisitsMeters": 23257,
              "travelDistanceFromLastVisitToEndLocationMeters": 23388,
              "endLocationArrivalTime": "2027-02-01T14:20:40Z"
            }
          }
        ]
      }
    ],
    "unassignedVisits": []
  },
  "inputMetrics": {
    "visits": 5,
    "visitGroups": 0,
    "vehicles": 2,
    "mandatoryVisits": 5,
    "optionalVisits": 0,
    "vehicleShifts": 2,
    "visitsWithSla": 0
  },
  "kpis": {
    "totalTravelTime": "PT4H5M44S",
    "travelTimeFromStartLocationToFirstVisit": "PT59M37S",
    "travelTimeBetweenVisits": "PT1H42M58S",
    "travelTimeFromLastVisitToEndLocation": "PT1H23M9S",
    "totalTravelDistanceMeters": 253974,
    "travelDistanceFromStartLocationToFirstVisitMeters": 62983,
    "travelDistanceBetweenVisitsMeters": 103802,
    "travelDistanceFromLastVisitToEndLocationMeters": 87189,
    "totalUnassignedVisits": 0,
    "totalAssignedVisits": 5,
    "assignedMandatoryVisits": 5,
    "assignedOptionalVisits": 0,
    "totalActivatedVehicles": 2,
    "workingTimeFairnessPercentage": 82.74
  }
}

modelOutput contains Ann’s and Beth’s updated shift itineraries.

Because Ann is closer to Visit M, Visit M is assigned to Ann, and Visit C is reassigned to Beth.

Next