Calculate and retrieve a schedule
Calculates a schedule based on the calculation parameters and the field rep's data, blocks until completion and returns the schedule. The field rep's data can be provided in newDataSet, which will replace the existing data. Alternatively, the existing data of the field rep will be used.
This method requires an access token with one of the following scopes:
- Partner access token
- Organization access token for {organizationId}
- FieldRep access token for {fieldRepId}
path parameters
- organizationId
An id must consist of the following characters: [a-zA-Z0-9-_{}]
- fieldRepId
An id must consist of the following characters: [a-zA-Z0-9-_{}]
Request body schema: application/json
calculationParameters
Specifies the parameters for a schedule calculation.
- fieldRepCurrentLocalDateTime
The current local time of the field rep. Used to take work and business hours into account when calculating the schedule.
IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format
"yyyy-MM-ddTHH:mm", e.g."2022-01-31T23:59". - scheduleBeginAt
The begin time of the schedule. Must be at or after
fieldRepCurrentLocalDateTime.IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format
"yyyy-MM-ddTHH:mm", e.g."2022-01-31T23:59". - schedulePeriodDays
Specifies the number of days in the schedule.
Allowed values are: 1, 2, 3, 4, 5, 6, 7, 14, 21, or 28 days.
customStartLocation
Defines a custom start location of the schedule. Recommendation: To speed up the recalculation of the schedule in the field, use a nearby customer location or scheduling constraint location as customStartLocation, if applicable.
Note: If null the field rep's home location is used. Specify
addressand/orgeoPosition. If both are specified, thegeoPositionis used as the location. If only theaddressis specified, it is automatically geocoded and used as the location. Recommendation: To speed up the calculation, always send the geoposition when possible. You can use geocode to get the geoposition of an address.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- skipWorkBreakToday
Specifies whether to omit the break on the first day of the schedule if the schedule starts with today.
Default:false - includeRoutePolylinesInSchedule
Specifies whether the
routePolylineshould be filled in the drive rows of the schedule. Polylines are provided in Google's encoded polyline format, encoded in utf-8. They can be used to draw a drive on a map (see Polyline decoder utility).Default:false - customerPlanningMode
Specifies whether to include only forced calls or calls according to the interval as well. Allowed values are:
"AccordingToCallIntervalsAndForcedCalls""OnlyForcedCalls"
Default:"AccordingToCallIntervalsAndForcedCalls" - trafficConditionsForFirstRide
Specifies whether to use the current traffic or the typical traffic for the first ride of the schedule. Allowed values are:
"CurrentTraffic""TypicalTraffic"
Note: The current traffic can only be taken into account if the first ride starts within the next 15 minutes.
Default:"CurrentTraffic"
newDataSet
Provides the field rep's data to be used in the schedule calculation. If specified, overwrites the existing field rep's data.
Note: If null, the existing data of the field rep is used for the schedule calculation.
fieldRep
Replaces the field rep's settings.
Note: If null, the existing field rep data is kept. The FieldRep is a resource in the backend system that contains the basic data or settings necessary for the calculation of schedules.
- name
The full name of the field rep.
- languageCultureName
Is used to set language and formatting. The schedule's messages appear in the field rep's culture language and formatting.
Supported values are:
"de-AT","de-CH","de-DE","de-LI","de-LU","en-AU","en-CA","en-GB","en-IE","en-NZ","en-US","en-ZA","es-AR","es-CL","es-CO","es-ES","es-MX","es-US","fr-BE","fr-CA","fr-CH","fr-FR","fr-LU","it-CH","it-IT","pt-BR","pt-PT" homeLocation
The home location of the field rep. Specify
addressand/orgeoPosition. If both are specified, thegeoPositionis used as the location. If only theaddressis specified, it is automatically geocoded and used as the location. Recommendation: To speed up the calculation, always send the geoposition when possible. You can use geocode to get the geoposition of an address.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
workingHours
Defines the hours per weekday that a field rep works. At least one day must be set.
monday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
tuesday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
wednesday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
thursday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
friday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
saturday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
sunday
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
drivingTimeFactors
Allows you to set driving speeds that vary by road type and field rep.
Note: If this property is null, the default value for each road type is used.
- cityRoad
This factor is applied to driving times in cities when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
Default:1 - countryRoad
This factor is applied to driving times on country roads when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
Default:1 - highway
This factor is applied to driving times on highways when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
Default:1
overnightStayAwayFromHomeSettings
Defines the conditions for overnight stays away from home.
Note: If this property is not set, no overnight stays are scheduled.
- isAllowedOnMonday
Specifies whether overnight stays away from home are allowed on Mondays.
Default:false - isAllowedOnTuesday
Specifies whether overnight stays away from home are allowed on Tuesdays.
Default:false - isAllowedOnWednesday
Specifies whether overnight stays away from home are allowed on Wednesdays.
Default:false - isAllowedOnThursday
Specifies whether overnight stays away from home are allowed on Thursdays.
Default:false - isAllowedOnFriday
Specifies whether overnight stays away from home are allowed on Fridays
Default:false - isAllowedOnSaturday
Specifies whether overnight stays away from home are allowed on Saturdays.
Default:false - isAllowedOnSunday
Specifies whether overnight stays away from home are allowed on Sundays.
Default:false - minimumMetersFromHome
Defines the minimum meters from the rep's home location. If the distance is within the minimum, no overnight stay is scheduled.
Default:120000 - minimumMinutesFromHome
Defines the minimum minutes of driving time from the rep's home location. If the driving time is within the minimum, no overnight stay is scheduled.
Default:120 - stayAtPreferredOvernightLocationIfWithinMinutes
After the last customer visit of the day, if a preferred overnight location is reachable within the specified minutes, the stay may be scheduled at that preferred overnight location.
Default:45
generalCustomerSchedulingSettings
Applies to all of the field rep's customers for the schedule calculation.
Note: If this property is null, the default value is used for each setting.
- dueAfterLastCallIntervalPercent
Specifies the value (in %) of the elapsed call interval after which the next call can be scheduled.
Default:70 - adherenceToCallingHours
Specifies whether only the start of the call must be within the calling hours or the entire call must be within the calling hours.
"StartOfCall""EntireCall"
Default:"StartOfCall"
workBreak
Specifies how to schedule a work break.
Note: If this property is null, no break is scheduled.
scheduleWithin
The time range consists of the
fromtime and thetotime.- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
- durationMinutes
Specifies the duration of the work break in minutes. The duration must fit within
scheduleWithin.
customers
Replaces the entire set of customers.
Note: If null, the existing customers of the field rep are kept.
- id
- name
The name of the customer.
location
The customer's location. Specify the address, the geoposition, or both.
Note: If the address is defined but the geoposition is null, the address is automatically geocoded.
address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- activatedOn
Used to calculate the call urgency of never-called customers. The actual day for the initial call is selected according to an optimized schedule. Can be set in the future.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - lastCallOn
Date of the last call. Is used to calculate the urgency of the next call based on the customer's call interval. Unlike
activatedOn, in order for the customer to be due and therefore scheduled for the next call, the field rep'sdueAfterLastCallIntervalPercentmust be reached. Must not be earlier thanactivatedOn.Note: If null, the call urgency will be calculated based on
activatedOn.IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - lastMissedCallOn
Prevents the customer from being rescheduled for a call on the same day.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". callInterval
Specifies the interval at which the customer should be called.
Note: If null, the customer has no call interval.
- days
The customer's call interval in days. A next call can be scheduled when the
dueAfterLastCallIntervalPercentsince the last call is reached.Default:30 - isAdherencePreferred
If set to 'true', helps avoid exceeding the customer's call interval - even if the field rep's territory is too large.
Note: Use sparingly, as not all customers can be called in the given interval if the territory is too large.
Default:false
- callDurationMinutes
The duration of a call in minutes.
Default:20 - schedulingRestriction
Specifies whether to schedule the customer only in certain calendar weeks. Use this if a customer is to be visited by two or more field reps but not in the same week. The allowed values are:
"OnlyInOddWeeks""OnlyInEvenWeeks""OnlyInFirstOfThreeWeeks""OnlyInSecondOfThreeWeeks""OnlyInThirdOfThreeWeeks""OnlyInFirstOfFourWeeks""OnlyInSecondOfFourWeeks""OnlyInThirdOfFourWeeks""OnlyInFourthOfFourWeeks"
Note: If null, no restriction is applied.
- doForceCall
If true, this customer will be included in the next schedule regardless of their last call date and call interval. This allows you to schedule a call to a customer who needs to be called urgently, without changing their last call date or call interval.
Default:false callingHours
For each day of the week it is possible to define one or two periods during which the customer is open for customer calls. If it is preferred to visit the customer on certain days or at certain times, set the
isPreferredflag to true for these periods. Preferred periods cause portatour® to schedule the customer preferably within this period.The field rep's
adherenceToCallingHoursingeneralCustomerSchedulingSettingsspecifies whether only the start of the call must be within the calling hours ("StartOfCall", default) or the entire call must be within the calling hours ("EntireCall").Default: each day starts at “00:00:00” and ends at “23:59:00” on period 1. Period 2 is null.
mondayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
mondayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
tuesdayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
tuesdayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
wednesdayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
wednesdayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
thursdayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
thursdayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
fridayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
fridayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
saturdayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
saturdayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
sundayPeriod1
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
sundayPeriod2
- from
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"00:00:00" - to
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".Default:"23:59:00" - isPreferredDefault:
false
callBlocks
Used to block calls from being scheduled for the customer on the specified days, e.g. the customer's holidays.
- beginOn
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - endOn
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - description
preferredOvernightLocations
Replaces the entire set of preferred overnight locations.
Note: If null, the existing preferred overnight locations of the field rep are kept.
- id
- name
The name of the preferred overnight location.
location
The location of the preferred overnight location. Specify
addressand/orgeoPosition. If both are specified, thegeoPositionis used as the location. If only theaddressis specified, it is automatically geocoded and used as the location. Recommendation: To speed up the calculation, always send the geoposition when possible. You can use geocode to get the geoposition of an address.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
schedulingConstraints
Replaces the entire set of scheduling constraints.
Note: If null, the existing scheduling constraints of the field rep are kept.
Note: For support in your edition, please see the schedule constraint types below.
customerEvent
Schedules a customer call at the specified date and time for the given duration. The event can last for several days. The location of the event is typically the customer's location, but can optionally be set to another location.
- id
- subject
locationInformation
Specifies the location of the customer event.
- locationType
The allowed values are:
"HomeLocation""CustomerLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"CustomerLocation", the location of the customer is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location of the customer event.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- startDate
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - beginAt
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - endDate
If null, value of
startDateis used.IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - endAt
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - customerId
The id of the customer to which this customer event is related.
customerEventWithinTimeFrame
Schedules a customer call within the specified time frame. The location of the event is typically the customer's location, but can optionally be set to another location.
- id
- subject
locationInformation
Specifies the location of the customer event.
- locationType
The allowed values are:
"HomeLocation""CustomerLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"CustomerLocation", the location of the customer is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location of the customer event.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
The start date of the customer event.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - earliestBeginAt
The earliest start time of a customer event, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - latestEndAt
The latest end time of the customer event, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - durationMinutes
The duration of the customer event in minutes.
Note: This value must be less than the difference between
earliestBeginAtandlatestEndAt. - customerId
The id of the customer to which this customer event is related.
customerEventAnytimeOnADay
Schedules a customer call within the specified time frame. The location of the event is typically the customer's location, but can optionally be set to another location.
- id
- subject
locationInformation
Specifies the location of the customer event.
- locationType
The allowed values are:
"HomeLocation""CustomerLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"CustomerLocation", the location of the customer is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location of the customer event.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
The date of the customer event.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - durationMinutes
The duration of the customer event in minutes.
- customerId
The id of the customer to which this customer event is related.
blocker
Blocks the scheduling of calls for the field rep during the specified date and time range. It can last for several days.
- id
- subject
locationInformation
Specifies the location information of the blocker.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location information of the blocker.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- startDate
The start date of the blocker.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - beginAt
The start time of the blocker.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59".Default:"00:00" - endDate
The end date of the blocker.
Note: If null it is the same as the
startDate.IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - endAt
The end time of the blocker.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59".Default:"23:59"
blockerWithinTimeFrame
Schedules a blocker for the given duration within the specified date time range.
- id
- subject
locationInformation
Specifies the location information of the blocker.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location information of the blocker.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
The date of the blocker.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - earliestBeginAt
The earliest start time of the blocker, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - latestEndAt
The latest end time of the blocker, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - durationMinutes
The duration of the blocker in minutes.
Note: This value must be less than the difference between
earliestBeginAtandlatestEndAt.
blockerAnytimeOnADay
Schedules a blocker for the given duration within the specified day.
- id
- subject
locationInformation
Specifies the location information of the blocker.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""CustomLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location information of the blocker.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
The date of the blocker.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - durationMinutes
The duration of the blocker in minutes.
deviatingStartOfDay
Starts the workday at a specific location and time.
- id
- subject
locationInformation
Specifies the location infomation.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""PreferredOvernightLocation""CustomLocation"
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"PreferredOvernightLocation", the location of the preferred overnight stay is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location infomation.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
Date of the deviating start of day.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - beginAt
The start time of the deviating start of day. If null, the correspondig start time of the field rep's workday is used.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - preferredOvernightLocationId
The id of the preferred overnight location to which the deviating start of day event is related. Only used, if locationType is
"PreferredOvernightStay".
deviatingEndOfDay
Ends the workday at a specific location and time.
- id
- subject
locationInformation
Specifies the location infomation.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""PreferredOvernightLocation""CustomLocation"
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"PreferredOvernightLocation", the location of the preferred overnight stay is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location infomation.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- date
Date of the deviating end of day.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - endAt
The end time of the deviating end of day. If null, the correspondig end time of the field rep's workday is used.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - preferredOvernightLocationId
The id of the preferred overnight location to which the deviating start of day event is related. Only used, if locationType is
"PreferredOvernightStay".
overnightStay
Schedules an overnight stay at a specific location for a given day.
- id
- subject
locationInformation
Specifies the location infomation.
- locationType
The allowed types of locations are the following strings:
"HomeLocation""PreferredOvernightLocation""CustomLocation"
If the
locationTypeis"HomeLocation", the home location of the field rep is used. If thelocationTypeis"PreferredOvernightLocation", the location of the preferred overnight stay is used. If thelocationTypeis"CustomLocation", thelocationproperty is used as the location. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location infomation.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- startDate
The start date of the overnight stay.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". - beginAt
The time at which the overnight stay begins. If null, the correspondig end time of the field rep's workday is used.
Note: A fallback of
"00:00"is used if it is null and the field rep does not have a work time on the corresponding day.IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - endAtNextDay
The time at which the overnight stay ends on the next day. If null, the correspondig start time of the field rep's workday is used.
Note: A fallback of
"08:00"is used if it is null and the field rep does not have a work time on the corresponding day.IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - preferredOvernightLocationId
The id of the preferred overnight location to which the overnight stay is related.
generic
Automatically decides what type of scheduling constraint to use. To convert to a particular type, the required properties of the type must be met. If they are not met for any particular type, the scheduling constraint cannot be converted and will therefore not be scheduled. Do not provide multiple properties in the same generic scheduling constraint that could be converted to multiple different particular types of scheduling constraints, for example, do not provide PreferredOvernightLocationId and CustomerId in the same generic scheduling constraint.
Editions: The automatic scheduling constraint supports only the subset of properties available in your edition. If the resulting scheduling constraint type is not supported in your edition, an error is returned.
- id
- subject
locationInformation
Specifies the location infomation of the scheduling constraint.
- locationType
The allowed values are:
"HomeLocation""CustomerLocation""CustomLocation""PreferredOvernightLocation""Anywhere"([[AnywhereLocationType]])
If the
locationTypeis"CustomLocation", thelocationproperty is used as the location. If thelocationTypeis"Anywhere", no location is used. location
Required if
locationTypeis"CustomLocation". Must not be set for any other value oflocationType. Specifies the location infomation of the scheduling constraint.address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- earliestBeginAt
The earliest start time of the scheduling constraint, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - latestEndAt
The latest end time of the scheduling constraint, defined by a time string with minute precision.
IsoTimeStringMinutesPrecision is a time type that contains values in the format
"HH:mm", e.g."23:59". - durationMinutes
The duration of the scheduling constraint in minutes.
Note: This value must be less than the difference between
earliestBeginAtandlatestEndAt. - customerId
The id of the customer to which the scheduling constraint is related.
- preferredOvernightLocationId
The id of the preferred overnight location to which the scheduling constraint is related.
Responses
200 OK
Response schema: application/json
- id
Unique for each calculated schedule.
days
The scheduled days.
- day
Date of scheduled day.
IsoDateString is a date type that contains values in the format
"yyyy-MM-dd", e.g."2022-01-31". rows
One row represents one scheduled item. A typical schedule has multiple rows. For example, a Drive row followed by a StopAtCustomer row and a WorkBreak row.
- type
The row type determines which of the subsequent row fields below is set. E.g. if the type is
"WorkBreak", only the field workBreak is set. Possible values are:"Stop""Drive""SchedulingConstraintWithoutLocation""WorkBreak""Wait"
stop
Specifies a stop. Only set if the row type is
"Stop".- timeFrom
Start time of the stop.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - timeTo
End time of the stop.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - stopType
The type of the stop. A scheduled day begins with a departure stop and ends with an arrival stop. Other stops, such as stops at customers, are placed between the departure and arrival stops.
Possible departures:
"DepartureFromHome":
The scheduled day starts from the home location of the field rep."DepartureFromCustomStartLocation":
The scheduled day starts from a specific custom location, that originates from a custom location of a scheduling constraint."DepartureAfterAnOngoingSchedulingConstraint":
The scheduled day starts after an ongoing scheduling constraint, e.g. a scheduling constraint of typecustomerEvent."DepartureFromPreferredOvernightLocation":
The scheduled day starts from a preferred overnight location."DepartureFromSchedulingConstraint":
The scheduled day starts from the location of a specific scheduling constraint, e.g. a scheduling constraint of typecustomerEvent."DepartureFromOvernightArea":
The scheduled day starts from a planned overnight stay area.
Possible stops:
"StopAtCustomer":
A stop at a customer location."StopAtCustomerSchedulingConstraint":
A stop at a customer due to a scheduling constraint, e.g. a scheduling constraint of typecustomerEvent."StopAtOtherSchedulingConstraint":
A stop due to a scheduling constraint that does not have a customer reference, e.g. a scheduling constraint of typeblocker.
Possible arrivals:
"ArrivalAtHome":
The scheduled day ends at the home location of the field rep."ArrivalAtPreferredOvernightLocation":
The scheduled day ends with an overnight stay at a preferred overnight location of the field rep."ArrivalAtOvernightArea":
The scheduled day ends at an area where an overnight stay is planned nearby. This type of overnight stay is scheduled, when there is no viable preferred overnight location near the area of the overnight stay."ArrivalAtSchedulingConstraint":
The scheduled day ends at the location of a scheduling constraint, e.g. a scheduling constraint of typeovernightstay.
- displayName
Name or subject of the stop.
location
Location of the stop.
address
- streetWithHouseNumber
Contains the street and the house number of the address. Do not use if
singleLineAddressis set. Example for Germany: > Jahnstr. 18Example for USA: > 140 2nd St
- postalCode
Contains the postal code of the address. Do not use if
singleLineAddressis set. - city
Contains the city of the address. Do not use if
singleLineAddressis set. - state
Contains the state of the address. Do not use if
singleLineAddressis set. - country
Contains the country of an address. This property is required, even if
singleLineAddressis set. Optionally 2-letter or 3-letter ISO country codes can be used. - singleLineAddress
This field is used for input-only and will never be returned. Representation of an address as a single line. After saving, the address parts are decomposed into the correct properties and this property becomes empty. Do not use the other address properties if this property is set.
geoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
- longitude
- geocodeWarning
This field is used for output-only. Do not set this field.
- customerId
If the stop is associated with a customer, the customer id is provided.
- schedulingConstraintId
If the stop is associated with a scheduling constraint, the scheduling constraint id is provided.
- preferredOvernightLocationId
If the stop is associated with a preferred overnight location, the preferred overnight lcoation id is provided.
drive
Specifies a drive. Only set if the row type is
"Drive".- timeFrom
Start time of the drive.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - timeTo
End time of the drive.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - distanceMeters
Drive distance in meters.
- routingType
The routingType indicates how the routing was made. Possible values are:
"TypicalTraffic","CurrentTraffic","Beeline"
- routePolyline
Polylines are provided in Google's encoded polyline format, encoded in utf-8. Polylines can be used to draw drives on maps (see Polyline decoder utility). Set if
IncludeRoutePolylinesInScheduleis true in thecalculationParameters.
schedulingConstraintWithoutLocation
Specifies a period for a scheduling constraint without a location. Only set if the row type is
"SchedulingConstraintWithoutLocation".- timeFrom
Start of the scheduling constraint.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - timeTo
End of the scheduling constraint.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - displayName
Display name of the scheduling constraint.
- schedulingConstraintId
Id to the scheduling constraint.
- customerId
Id of the customer associated with the scheduling constraint.
Note: If null, there is no customer associated with the scheduling constraint.
workBreak
Specifies a work break. Only set if the row type is
"WorkBreak".- timeFrom
Start of the work break.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - timeTo
End of the work break.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
wait
Specifies a waiting period. Only set if the row type is
"Wait".- timeFrom
Start of the waiting period.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59". - timeTo
End of the waiting period.
IsoTimeStringSecondsPrecision is a time type that contains values in the format
"HH:mm:ss", e.g."23:59:59".
messages
Provide information about the schedule. The possible messages are documented in the schedule messages section.
Note: If null, there are no messages.
- messageId
Identifies the schedule message.
- severity
The severity level of the message. Possible values are:
"Info""Warning""Error"
- text
Is provided in the language of the field rep. Its content is described in the schedule message description.
Error responses (10)
400 Bad Request
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
401 Unauthorized
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
402 Payment Required
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
403 Forbidden
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
404 Not Found
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
409 Conflict
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
413 Content Too Large
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.
429 Too Many Requests
Response schema: application/json
- statusCode
Corresponds to the HTTP status code.
- message
Describes the error.
- errorCode
- correlationId
Is used to identify related internal methods involved in the request.