---
title: "Create/Update stops for a tour."
method: POST
path: "/tour/upsert_stop"
tags: ["Disposition|Tour"]
---

# Create/Update stops for a tour.

`POST /tour/upsert_stop`

This method can be used to create and update tour stops. An attempt is made to find an existing stop based on
the
given id. If one is found, it will be adjusted. Otherwise, a new stop is created.

To share the tour with the driver after a new stop has been added, it must first be calculated. This is made
possible at the `/tour/calculate` endpoint. To insert the stop at a certain point in the tour, the
`beforeStopId`
or `afterStopId` must be set. To share the tour with the driver, calculate the tour and set the status to
`READY`. The drivers can access the tour details via the orders menu in the geoCapture mobile app.

## Request body

- StandardDispoTourUpsertStopRequest
  - `records` object[] — The stop records.
    - `keyField` string — This parameter specifies the name of the unique key used to distinctly assign each dataset in the API. | Value | Description | |----------------|-----------------------------| | id | The internal tour stop ID |
    - `data` DispoTourUpsertStopRequestRecordData
      - `id` integer — The internal id of the stop.
      - `tourId` integer — The id of the tour the stop is assigned. (mandatory)
      - `sequence` integer — The sequence of the stop.
      - `type` string — The stop type. | Value | Description | |--------------------------|--------------------------------------| | HOME | Home Stop used to identify the start and end of the tour | | ORDER | Use this type for a normal stop with orders | | TBREAK | Break Stop | | HOTEL | Used for overnight stays | | FUEL | Used for fueling | | LOAD | Used for pickup and delivery orders. | | UNLOAD | Used for pickup and delivery orders. |
      - `name` string — The name address addition. (max. 255 characters)
      - `name2` string — The name2 address addition. (max. 255 characters)
      - `name3` string — The name3 address addition. (max. 255 characters)
      - `street` string — The street. (max. 255 characters)
      - `zipCode` string — The zip code.
      - `city` string — The city.
      - `countryCode` string — The two-digit ISO 3166 country code.
      - `provinceCode` string — The province code.
      - `latLng` number[] — Represents a geo coordinate. An array of two double values, representing the latitude and longitude.
      - `orderIds` integer[] — The internal id of the order to be added to the tour.
      - `contactPersonName` string — The contact person name. (max. 255 characters)
      - `contactPersonEmail` string — The contact person e-mail. (max. 255 characters)
      - `contactPersonPhoneNumber` string — The contact person phone number. (max. 64 characters)
      - `contactPersonMobileNumber` string — The contact person mobile number. (max. 64 characters)
      - `duration` integer — The duration in seconds for the new stop. Use this only when the duration is not equal with the work duration of the orders.
      - `breakDuration` integer — The duration in seconds for the break.
      - `noteDriver` string — A note for the driver. This info is shown to the driver in his app.
      - `notePlanner` string — A note for the planner.
      - `additionalCosts` number — Field for additional costs.
      - `fixedArrivalDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
      - `fixedArrivalTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
      - `fixedDepartureDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
      - `fixedDepartureTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
      - `beforeStopId` integer — The id of the stop, the new stop should be inserted before.
      - `afterStopId` integer — The id of the stop, the new stop should be inserted after.
  - `dryRun` boolean — Simulate the operation. (No records will be created or changed) This Parameter is optional.

## Response `200`

Success Response:

- StandardDispoTourUpsertStopResponse
  - `createdStops` object[] — The created stops.
    - `tourId` integer — The id of the tour the stop is assigned.
    - `id` integer — The internal id of the stop.
    - `sequence` integer — The sequence of the stop.
    - `type` string — The stop type. | Value | Description | |--------------------------|--------------------------------------| | HOME | Home Stop used to identify the start and end of the tour | | ORDER | Use this type for a normal stop with orders | | TBREAK | Break Stop | | HOTEL | Used for overnight stays | | FUEL | Used for fueling | | LOAD | Used for pickup and delivery orders. | | UNLOAD | Used for pickup and delivery orders. |
    - `name` string — The name address addition.
    - `name2` string — The name2 address addition.
    - `name3` string — The name3 address addition.
    - `street` string — The street.
    - `zipCode` string — The zip code.
    - `city` string — The city.
    - `countryCode` string — The two-digit ISO 3166 country code.
    - `provinceCode` string — The province code.
    - `latLng` number[] — Represents a geo coordinate. An array of two double values, representing the latitude and longitude.
    - `contactPersonName` string — The contact person name.
    - `contactPersonEmail` string — The contact person e-mail.
    - `contactPersonPhoneNumber` string — The contact person phone number.
    - `contactPersonMobileNumber` string — The contact person mobile number.
    - `noteDriver` string — A note for the driver. This info is shown to the driver in his app.
    - `notePlanner` string — A note for the planner.
    - `additionalCosts` number — Field for additional costs.
    - `duration` integer — The duration in seconds for the new stop. Use this only when the duration is not equal with the work duration of the orders. If the stop is a break it's used as break duration, if not it's the work duration.
    - `fixedArrivalDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedArrivalTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
    - `fixedDepartureDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedDepartureTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
  - `updatedStops` object[] — The changed stops.
    - `tourId` integer — The id of the tour the stop is assigned.
    - `id` integer — The internal id of the stop.
    - `sequence` integer — The sequence of the stop.
    - `type` string — The stop type. | Value | Description | |--------------------------|--------------------------------------| | HOME | Home Stop used to identify the start and end of the tour | | ORDER | Use this type for a normal stop with orders | | TBREAK | Break Stop | | HOTEL | Used for overnight stays | | FUEL | Used for fueling | | LOAD | Used for pickup and delivery orders. | | UNLOAD | Used for pickup and delivery orders. |
    - `name` string — The name address addition.
    - `name2` string — The name2 address addition.
    - `name3` string — The name3 address addition.
    - `street` string — The street.
    - `zipCode` string — The zip code.
    - `city` string — The city.
    - `countryCode` string — The two-digit ISO 3166 country code.
    - `provinceCode` string — The province code.
    - `latLng` number[] — Represents a geo coordinate. An array of two double values, representing the latitude and longitude.
    - `contactPersonName` string — The contact person name.
    - `contactPersonEmail` string — The contact person e-mail.
    - `contactPersonPhoneNumber` string — The contact person phone number.
    - `contactPersonMobileNumber` string — The contact person mobile number.
    - `noteDriver` string — A note for the driver. This info is shown to the driver in his app.
    - `notePlanner` string — A note for the planner.
    - `additionalCosts` number — Field for additional costs.
    - `duration` integer — The duration in seconds for the new stop. Use this only when the duration is not equal with the work duration of the orders. If the stop is a break it's used as break duration, if not it's the work duration.
    - `fixedArrivalDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedArrivalTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
    - `fixedDepartureDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedDepartureTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
  - `deletedStops` object[] — The deleted stops.
    - `tourId` integer — The id of the tour the stop is assigned.
    - `id` integer — The internal id of the stop.
    - `sequence` integer — The sequence of the stop.
    - `type` string — The stop type. | Value | Description | |--------------------------|--------------------------------------| | HOME | Home Stop used to identify the start and end of the tour | | ORDER | Use this type for a normal stop with orders | | TBREAK | Break Stop | | HOTEL | Used for overnight stays | | FUEL | Used for fueling | | LOAD | Used for pickup and delivery orders. | | UNLOAD | Used for pickup and delivery orders. |
    - `name` string — The name address addition.
    - `name2` string — The name2 address addition.
    - `name3` string — The name3 address addition.
    - `street` string — The street.
    - `zipCode` string — The zip code.
    - `city` string — The city.
    - `countryCode` string — The two-digit ISO 3166 country code.
    - `provinceCode` string — The province code.
    - `latLng` number[] — Represents a geo coordinate. An array of two double values, representing the latitude and longitude.
    - `contactPersonName` string — The contact person name.
    - `contactPersonEmail` string — The contact person e-mail.
    - `contactPersonPhoneNumber` string — The contact person phone number.
    - `contactPersonMobileNumber` string — The contact person mobile number.
    - `noteDriver` string — A note for the driver. This info is shown to the driver in his app.
    - `notePlanner` string — A note for the planner.
    - `additionalCosts` number — Field for additional costs.
    - `duration` integer — The duration in seconds for the new stop. Use this only when the duration is not equal with the work duration of the orders. If the stop is a break it's used as break duration, if not it's the work duration.
    - `fixedArrivalDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedArrivalTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss
    - `fixedDepartureDate` string — Represents a date. (ISO 8601) ICU-Format: yyyy-MM-dd
    - `fixedDepartureTime` string — Represents a time. (ISO 8601) ICU-Format: HH:mm:ss

---

[API](https://skmtc.net/geocapture/apis/geocapture-api.md) · [All operations](https://skmtc.net/geocapture/apis/geocapture-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/geocapture/geocapture-api/versions/869b05603541/schema)